Plasma GitLab Archive
Projects Blog Knowledge

Class type Http_client.http_call


class type http_call = object .. end
The container for HTTP calls

http_call is the runtime container for HTTP method calls. It contains the request message, the response message, and the current transmission status.

In previous versions of netclient, this class type was called message. This was quite inexact because this class embraces both messages that are part of a call.

Incompatible changes:

  • using_proxy has been removed. This simply isn't a property of an individual call.
  • get_req_uri has been removed from the public interface for similar reasons.
  • The request and response messages are now primarily stored as Netmime.mime_header and Netmime.mime_body objects. The old style access methods remain in the API for now. The advantage is that it is possible to use external files as body containers.
  • There are two request headers, `Base and `Effective.

Call State

method is_served : bool
true if request/response cycle(s) have been finished, i.e. the call was successful, or a final error state has been reached.
method status : status
The condensed status

Accessing the request message (new style)

method request_method : string
The HTTP method as string
method request_uri : string
The request URI as string. This is always an absolute URI in the form "http://server/path".
method set_request_uri : string -> unit
Sets the request URI
method request_header : header_kind -> Netmime.mime_header
The whole header of the request. Users of this class should only modify the `Base header. After the call has been processed, the `Effective header contains the version of the header that has actually been transmitted.

The user should set the following headers:

  • Content-length: Set this to the length of the request body if known. (The client falls back to HTTP 1.0 if not set!)
  • Content-type: Set this to the media type of the request body
  • Expect: Set this to "100-continue" to enable a handshake before the body is sent. Recommended for large bodies.
The following headers may be set, but there are reasonable defaults:
  • Date
  • User-agent
The following headers must not be set:
  • Connection

method set_request_header : Netmime.mime_header -> unit
Replaces the whole `Base header object
method effective_request_uri : string
The URI actually sent to the server in the request line of the protocol.
method request_body : Netmime.mime_body
The whole body of the request
method set_request_body : Netmime.mime_body -> unit
Replaces the whole body object

Accessing the response message (new style)

These methods will fail if the call has not yet been served! If the call has been finished, but a hard error (e.g. socket error) occurred, the exception Http_protocol is raised. When the server only sent an error code, no exception is raised - but the user can manually test for such codes (e.g. with repsonse_status or status).

method response_status_code : int
The three-digit status code
method response_status_text : string
The text transmitted along with the code
method response_status : Nethttp.http_status
The decoded code. Unknown codes are mapped to the generic status values `Ok, `Multiple_choices, `Bad_request, and `Internal_server_error.
method response_protocol : string
The HTTP version indicated in the response
method response_header : Netmime.mime_header
The whole header of the response. If the call has not succeeded, Http_protocol will be raised.
method response_body : Netmime.mime_body
The whole body of the response. If the call has not succeeded, Http_protocol will be raised. If the call has succeeded, but no body has been transmitted, the empty body is substituted.

Options

method response_body_storage : response_body_storage
How to create the response body. Defaults to `Memory.
method set_response_body_storage : response_body_storage -> unit
Sets how to create the response body
method get_reconnect_mode : http_call how_to_reconnect
Get what to do if the server needs to be reconnected, i.e. if the request must be sent repeatedly. By default, this is Send_again_if_idem.
method set_reconnect_mode : http_call how_to_reconnect -> unit
Sets the reconnect mode
method get_redirect_mode : http_call how_to_redirect
By default, the redirect mode is Redirect_if_idem.
method set_redirect_mode : http_call how_to_redirect -> unit
Sets the redirect mode
method proxy_enabled : bool
Returns the proxy mode
method set_proxy_enabled : bool -> unit
Sets the proxy mode
method no_proxy : unit -> unit
Same as set_proxy_enabled false
method is_proxy_allowed : unit -> bool
Deprecated. Same as proxy_enabled

Method characteristics

These properties describe the HTTP method

method empty_path_replacement : string
The string to substitute in the request line for the empty path. This is usually "/", and for OPTIONS it is "*".
method is_idempotent : bool
Whether the method is to be considered as idempotent ( = repeated invocations have the same result and no side effect). This is true for GET and HEAD.
method has_req_body : bool
Whether the method allows to send a request body
method has_resp_body : bool
Whether the method allows to reply with a body. This is true except for HEAD.

Repeating calls

method same_call : unit -> http_call
This method returns a new object that will perform the same call as this object (this function is called "reload" in browsers). The new object is initialized as follows:
  • The state is set to `Unserved
  • The request method remains the same (the class of the returned object remains the same)
  • The request URI is the same string as the original URI
  • The base request header is the same object
  • The request body is the same object
  • Options like reconnect, redirect mode, and proxy mode are copied.

Old style access methods

These method were introduced in previous versions of netclient, but are quite limited. Some questionable methods are now deprecated and will be removed in future versions of netclient.

method get_req_method : unit -> string
Get the name of the request method. Same as request_method.
method get_host : unit -> string
The host name of the content server, extracted from the URI
method get_port : unit -> int
The port number of the content server, extracted from the URI
method get_path : unit -> string
The path extracted from the URI
method get_uri : unit -> string
the full URI of this message: http://server:port/path. If the path is empty, it is omitted. - Same as request_uri.
method get_req_body : unit -> string
What has been sent as body in the (last) request. Same as request_body # value.
method get_req_header : unit -> (string * string) list
Deprecated. What has been sent as header in the (last) request. Returns (key, value) pairs, where the keys are all in lowercase.

In new code, the request_header object should be accessed instead.

method assoc_req_header : string -> string
Query a specific header entry, or raise Not_found
method assoc_multi_req_header : string -> string list
Return all header values for a given field name (header entries which allow several values separated by commas can also be transmitted by several header lines with the same name).
method set_req_header : string -> string -> unit
method get_resp_header : unit -> (string * string) list
Deprecated. Get the header of the last response. The keys are in lowercase characters again.
method assoc_resp_header : string -> string
Query a specific header entry of the response.
method assoc_multi_resp_header : string -> string list
Return all response header values for a given field name (header entries which allow several values separated by commas can also be transmitted by several header lines with the same name).
method get_resp_body : unit -> string
Deprecated. Returns the body of the last response if the response status is OK (i.e. the code is in the range 200 to 299).

Otherwise, Http_error (code, body) is raised where 'code' is the response code and 'body' is the body of the (errorneous) response.

method dest_status : unit -> string * int * string
Returns the status line of the last response (but status lines with code 100 are ignored). The returned triple is (http_string, code, text)

Private

method private_api : private_api
This web site is published by Informatikbüro Gerd Stolpmann
Powered by Caml