Ocamlnet 3 Reference Manual : Http_client.http_call

# 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" or "https://server/path".

    method set_request_uri : string -> unit

Sets the request URI. This implicitly also sets the channel binding ID (see below).

Changed in Ocamlnet-3.3: The URI is no longer immediately parsed, but first when the call is submitted to a pipeline. This means that parsing errors will first be reported by the `add` method. The background is that parsing now depends on pipeline options.

    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. (See also `set_expect_handshake` below.)

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 set_expect_handshake : unit -> unit

Configures that a handshake is done before sending the request body. This is useful when the request body can be large, and authentication or response indirections are possible. New since Ocamlnet-3.3.

    method set_chunked_request : unit -> unit

Configures that the request is transmitted using chunked encoding. This has advantages when the size of the request is not known in advance. However, this works only for true HTTP/1.1 servers. New since Ocamlnet-3.3.

    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. This method fails after `set_request_device` has been called (no body then).

    method set_request_body : Netmime.mime_body -> unit

Replaces the whole body object

    method set_request_device : (unit -> Uq_io.in_device) -> unit

Sets that the request data is read from the passed device instead of taking it from a body object. The device must be connected with the same event loop as the HTTP client.

    method set_accept_encoding : unit -> unit

Sets the `Accept-Encoding` field in the request header, and includes all decompression algorithms registered in `Netcompression`. Additionally, the automatic decompression of the response body is enabled.

Note that you need to ensure that the algorithms are really registered at `Netcompression`. For example, to get `gzip` support, run

     Netgzip.init()

, and include `netzip` as library.

## 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.

If the response is directly forwarded to a device (after calling `set_response_body_storage (`Device d)`), there is no accessible response body, and this method will fail.

## 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 max_response_body_length : int64

Returns the current maximum length (initially `Int64.max_int`)

    method set_max_response_body_length : int64 -> unit

Sets a new maximum length. When the body exceeds this maximum by more than the size of the internal buffer, the reception of the response is interrupted, and the error is set to `Response_too_large`.

    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 proxy_use_connect : bool

Whether to use the CONNECT method if the connection is made via a web proxy. This is normally true if the channel binding is `Http_client.https_cb_id`

    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.

## Channel bindings

Channel bindings are used to distinguish between security requirements. There are normally only two types of requirements:

- The ID `Http_client.http_cb_id` is used for messages that can only be sent over HTTP connections, i.e. unencrypted TCP. It is automatically set when the URL of the message starts with "http://".
- The ID `Http_client.https_cb_id` describes the requirement that the message can only be sent over HTTPS connections, i.e. TLS-protected TCP. It is automatically set when the URL of the message starts with "https://".

It is possible to change the channel binding to establish further types of security requirements (e.g. that certain client certificates are used), or even other details of the transport connection.

The method `channel_binding` is gone from this object type. It is now available as part of `pipeline`.

    method set_channel_binding : channel_binding_id -> unit

Sets the channel binding. Note that `set_request_uri` also sets the channel binding, but always to the default for the type of URL.

## 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 channel binding ID is the same
- 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.

Changed in Ocamlnet-3.3: The host can first be extracted after the call is submitted to a pipeline.

    method get_port : unit -> int

The port number of the content server, extracted from the URI.

Changed in Ocamlnet-3.3: The port can first be extracted after the call is submitted to a pipeline.

    method get_path : unit -> string

The path (incl. query, if any) extracted from the URI.

Changed in Ocamlnet-3.3: The path can first be extracted after the call is submitted to a pipeline.

    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