net/http.eh (libnet API)

net/http.eh

HTTP and HTTPS connections. More...

use "net/http.eh"

Constants

const GET = "GET"
const HEAD = "HEAD"
const HTTP_ACCEPTED = 202
const HTTP_BAD_GATEWAY = 502
const HTTP_BAD_METHOD = 405
const HTTP_BAD_REQUEST = 400
const HTTP_CLIENT_TIMEOUT = 408
const HTTP_CONFLICT = 409
const HTTP_CREATED = 201
const HTTP_ENTITY_TOO_LARGE = 413
const HTTP_EXPECT_FAILED = 417
const HTTP_FORBIDDEN = 403
const HTTP_GATEWAY_TIMEOUT = 504
const HTTP_GONE = 410
const HTTP_INTERNAL_ERROR = 500
const HTTP_LENGTH_REQUIRED = 411
const HTTP_MOVED_PERM = 301
const HTTP_MOVED_TEMP = 302
const HTTP_MULT_CHOICE = 300
const HTTP_NO_CONTENT = 204
const HTTP_NOT_ACCEPTABLE = 406
const HTTP_NOT_AUTHORITATIVE = 203
const HTTP_NOT_FOUND = 404
const HTTP_NOT_IMPLEMENTED = 501
const HTTP_NOT_MODIFIED = 304
const HTTP_OK = 200
const HTTP_PARTIAL = 206
const HTTP_PAYMENT_REQUIRED = 402
const HTTP_PRECON_FAILED = 412
const HTTP_PROXY_AUTH = 407
const HTTP_REQ_TOO_LONG = 414
const HTTP_RESET = 205
const HTTP_SEE_OTHER = 303
const HTTP_TEMP_REDIRECT = 307
const HTTP_UNAUTHORIZED = 401
const HTTP_UNAVAILABLE = 503
const HTTP_UNSUPPORTED_RANGE = 416
const HTTP_UNSUPPORTED_TYPE = 415
const HTTP_USE_PROXY = 305
const HTTP_VERSION = 505
const POST = "POST"

Types

type Http < StreamConnection;
type Https < Http;

Functions

def Http.get_date(): Long;
def Http.get_encoding(): String;
def Http.get_expires(): Long;
def Http.get_length(): Long;
def Http.get_modified(): Long;
def Http.get_req_method(): String;
def Http.get_req_property(key: String): String;
def Http.get_resp_code(): Int;
def Http.get_resp_msg(): String;
def Http.get_type(): String;
def Http.set_req_method(method: String);
def Http.set_req_property(key: String, value: String);
def Https.get_port(): Int;
def Https.get_secinfo(): SecInfo;
def new_http(host: String): Http;
def new_https(host: String): Https;

Description

This header defines functions to establish HTTP and HTTPS connections.

The Http connection has three states:

Setup, in which the request parameters can be set;
Connected, in which request parameters have been sent and the response is expected;
Closed, the final state, in which HTTP connection has been terminated.

New Http object created by new_http() or new_https() is initially in Setup state. The following methods may be invoked only in the Setup state:

The following methods establish internet connection and turn Http object into Connected state:

Opening output stream with StreamConnection.open_output does not trigger connection, but after the output stream has been opened, attempts to change the request parameters via set_req_method and set_req_property are ignored. When an output stream is closed via Stream.close, the connection enters the Connected state. When the output stream is flushed via OStream.flush, the request parameters are sent along with any data written to the stream.

Http connection becomes closed once all opened streams are closed and Connection.close function is called.

Example using HTTP

Read the HTTP headers and and data.

The HTTP connection is opened, headers are read and processed. If the length is available, it is used to read data in bulk. Otherwise, every byte is read until end of file.

// Create new Http connection.
var http = new_http("example.com")

// Getting the response code will open the connection,
// send the request, and read the HTTP response headers.
var rc = http.get_resp_code()
if (rc != HTTP_OK) {
  stderr().println("HTTP response code: " + rc)
} else {
  // Get the content-type
  var ctype = http.get_type()

  // Get the length and process the data
  var len:Int = http.get_length()
  var in = http.open_input()
  if (len > 0) {
    var count = 0
    var bytesread = 0
    var data = new BArray(len)
    while ((count < len) && (bytesread != -1)) {
      bytesread = in.read(data, count, len - count)
      if (bytesread != -1) count += bytesread
    }
    ...
  } else {
    var ch = in.read()
    while (ch != EOF) {
      ...
      ch = in.read()
    }
  }
  in.close()
}

// Finally, close the Http connection.
http.close()

Example using POST with HTTP

Post a request with some headers and content to the server and process the headers and content.

The HTTP connection is opened. The request method is set to POST and request headers set. A simple command is written and flushed. The HTTP headers are read and processed. If the length is available, it is used to read data in bulk. Otherwise, every byte is read until end of file.

var http = new_http("example.com")

// Set the request method and headers
http.set_req_method(POST)
http.set_req_property("If-Modified-Since", "29 Oct 1999 19:43:31 GMT")
http.set_req_property("User-Agent", "Profile/MIDP-2.0 Configuration/CLDC-1.0")
http.set_req_property("Content-Language", "en-US")

// Getting the output stream may flush the headers
var out = http.open_output()
out.println("LIST games")
out.flush()

// Getting the response code will open the connection,
// send the request, and read the HTTP response headers.
var rc = http.get_resp_code()
if (rc != HTTP_OK) {
  stderr().println("HTTP response code: " + rc)
} else {
  // Get the content-type
  var ctype = http.get_type()

  // Get the length and process the data
  var len:Int = http.get_length()
  var in = http.open_input()
  if (len > 0) {
    var count = 0
    var bytesread = 0
    var data = new BArray(len)
    while ((count < len) && (bytesread != -1)) {
      bytesread = in.read(data, count, len - count)
      if (bytesread != -1) count += bytesread
    }
    ...
  } else {
    var ch = in.read()
    while (ch != EOF) {
      ...
      ch = in.read()
    }
  }
  in.close()
}

// Finally, close the Http connection.
out.close()
http.close()

Constant details

const HEAD = "HEAD"

HTTP Head method.

const GET = "GET"

HTTP Get method.

const POST = "POST"

Http Post method.

const HTTP_OK = 200

200: The request has succeeded.

const HTTP_CREATED = 201

201: The request has been fulfilled and resulted in a new resource being created.

const HTTP_ACCEPTED = 202

202: The request has been accepted for processing, but the processing has not been completed.

const HTTP_NOT_AUTHORITATIVE = 203

203: The returned meta-information in the entity-header is not the definitive set as available from the origin server.

const HTTP_NO_CONTENT = 204

204: The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta-information.

const HTTP_RESET = 205

205: The server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent.

const HTTP_PARTIAL = 206

206: The server has fulfilled the partial GET request for the resource.

const HTTP_MULT_CHOICE = 300

300: The requested resource corresponds to any one of a set of representations, each with its own specific location, and agent-driven negotiation information is being provided so that the user (or user agent) can select a preferred representation and redirect its request to that location.

const HTTP_MOVED_PERM = 301

301: The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs.

const HTTP_MOVED_TEMP = 302

302: The requested resource resides temporarily under a different URI. (Note: the name of this status code reflects the earlier publication of RFC2068, which was changed in RFC2616 from "moved temporalily" to "found". The semantics were not changed. The Location header indicates where the application should resend the request.)

const HTTP_SEE_OTHER = 303

303: The response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource.

const HTTP_NOT_MODIFIED = 304

304: If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code.

const HTTP_USE_PROXY = 305

305: The requested resource MUST be accessed through the proxy given by the Location field.

const HTTP_TEMP_REDIRECT = 307

307: The requested resource resides temporarily under a different URI.

const HTTP_BAD_REQUEST = 400

400: The request could not be understood by the server due to malformed syntax.

const HTTP_UNAUTHORIZED = 401

401: The request requires user authentication. The response MUST include a WWW-Authenticate header field containing a challenge applicable to the requested resource.

const HTTP_PAYMENT_REQUIRED = 402

402: This code is reserved for future use.

const HTTP_FORBIDDEN = 403

403: The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.

const HTTP_NOT_FOUND = 404

404: The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

const HTTP_BAD_METHOD = 405

405: The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

const HTTP_NOT_ACCEPTABLE = 406

406: The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

const HTTP_PROXY_AUTH = 407

407: This code is similar to 401 (Unauthorized), but indicates that the client must first authenticate itself with the proxy.

const HTTP_CLIENT_TIMEOUT = 408

408: The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time.

const HTTP_CONFLICT = 409

409: The request could not be completed due to a conflict with the current state of the resource.

const HTTP_GONE = 410

410: The requested resource is no longer available at the server and no forwarding address is known.

const HTTP_LENGTH_REQUIRED = 411

411: The server refuses to accept the request without a defined Content-Length.

const HTTP_PRECON_FAILED = 412

412: The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.

const HTTP_ENTITY_TOO_LARGE = 413

413: The server is refusing to process a request because the request entity is larger than the server is willing or able to process.

const HTTP_REQ_TOO_LONG = 414

414: The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.

const HTTP_UNSUPPORTED_TYPE = 415

415: The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

const HTTP_UNSUPPORTED_RANGE = 416

416: A server SHOULD return a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field.

const HTTP_EXPECT_FAILED = 417

417: The expectation given in an Expect request-header field could not be met by this server, or, if the server is a proxy, the server has unambiguous evidence that the request could not be met by the next-hop server.

const HTTP_INTERNAL_ERROR = 500

500: The server encountered an unexpected condition which prevented it from fulfilling the request.

const HTTP_NOT_IMPLEMENTED = 501

501: The server does not support the functionality required to fulfill the request.

const HTTP_BAD_GATEWAY = 502

502: The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

const HTTP_UNAVAILABLE = 503

503: The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

const HTTP_GATEWAY_TIMEOUT = 504

504: The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI or some other auxiliary server it needed to access in attempting to complete the request.

const HTTP_VERSION = 505

505: The server does not support, or refuses to support, the HTTP protocol version that was used in the request message.

Type details

type Http < StreamConnection;

HTTP connection.

type Https < Http;

HTTPS connection.

Function details

def new_http(host: String): Http;

Creates new HTTP connection with given host.

def Http.get_req_method(): String;

Returns request method of this connection: HEAD, GET or POST.

def Http.set_req_method(method: String);

Sets the current request method of this connection. Argument must be one of HEAD, GET, POST. The default value is GET.

def Http.get_req_property(key: String): String;

Returns the value of the named general request property for this connection. If there is no key with with the specified name, then null is returned.

def Http.set_req_property(key: String, value: String);

Sets the general request property. If a property with the key already exists, overwrites its value with the new value.

def Http.get_type(): String;

Returns the type of content that the resource connected to is providing. For HTTP connection this is the value of the content-type header field. Returns null if type is not known.

def Http.get_encoding(): String;

Returns the encoding of the content which the resource connected to is providing. For HTTP connection this is the value of the content-encoding header field. Returns null if encoding is not known.

def Http.get_length(): Long;

Returns the length of the content which is being provided. For HTTP connection this is the value of the content-length header field. Returns -1 if length is not known.

def Http.get_resp_code(): Int;

Returns the HTTP response status code.

def Http.get_resp_msg(): String;

Gets the HTTP response message, if any, returned along with the response code from a server.

def Http.get_expires(): Long;

Returns value of the expires header field, as a date.

def Http.get_date(): Long;

Returns value of the date header field, as a date.

def Http.get_modified(): Long;

Returns value of the last-modified header field, as a date.

def new_https(host: String): Https;

Creates new HTTPS connection with given host.

def Https.get_port(): Int;

Returns port to which connection is made.

def Https.get_secinfo(): SecInfo;

Return the security information associated with this successfully opened connection. If the connection is still in Setup state then the connection is initiated to establish the secure connection to the server. The method returns when the connection is established and the Certificate supplied by the server has been validated. The SecInfo is only returned if the connection has been successfully made to the server.