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.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.`Base and `Effective.method is_served : booltrue if request/response cycle(s) have been finished, i.e. the
call was successful, or a final error state has been reached.
method status : statusThe condensed status
method auth_status : unit auth_statusAuthenticaton status. This status code is important for mutual
authentication (i.e. when the client also authenticates the server),
which can be enabled for some generic authentication handlers.
In this case status and all the other methods just report about the
last message from the server. They will not indicate whether the
authentication
failed on the side of the client (in particular, no exception is
thrown). It is required to check that auth_status=`OK.
An example of a mechanism with mutual authentication is
Netmech_digest_http.Digest_mutual.
method tls_session_props : Nettls_support.tls_session_props optionIf TLS is enabled, this returns the session properties
method gssapi_props : Netsys_gssapi.client_props optionIf GSSAPI is active, return the properties
method request_method : stringThe HTTP method as string
method request_uri : stringThe 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 -> unitSets the request URI. This implicitly also sets the transport layer 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_headerThe 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 bodyExpect: 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:
DateUser-agentThe following headers must not be set:
Connectionmethod set_request_header : Netmime.mime_header -> unitReplaces the whole `Base header object
method set_expect_handshake : unit -> unitConfigures 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 -> unitConfigures 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 : stringThe URI actually sent to the server in the request line of the protocol.
method request_body : Netmime.mime_bodyThe 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 -> unitReplaces the whole body object
method set_request_device : (unit -> Uq_io.in_device) -> unitSets 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 -> unitSets 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.
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 : intThe three-digit status code
method response_status_text : stringThe text transmitted along with the code
method response_status : Nethttp.http_statusThe decoded code. Unknown codes are mapped to the generic status
values `Ok, `Multiple_choices, `Bad_request, and
`Internal_server_error.
method response_protocol : stringThe HTTP version indicated in the response
method response_header : Netmime.mime_headerThe whole header of the response. If the call has not succeeded,
Http_protocol will be raised.
method response_body : Netmime.mime_bodyThe 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.
method response_body_storage : response_body_storageHow to create the response body. Defaults to `Memory.
method set_response_body_storage : response_body_storage -> unitSets how to create the response body
method max_response_body_length : int64Returns the current maximum length (initially Int64.max_int)
method set_max_response_body_length : int64 -> unitSets 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_reconnectGet 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 -> unitSets the reconnect mode
method get_redirect_mode : http_call how_to_redirectBy default, the redirect mode is Redirect_if_idem.
method set_redirect_mode : http_call how_to_redirect -> unitSets the redirect mode
method proxy_enabled : boolReturns the proxy mode
method set_proxy_enabled : bool -> unitSets the proxy mode
method no_proxy : unit -> unitSame as set_proxy_enabled false
method is_proxy_allowed : unit -> boolDeprecated. Same as proxy_enabled
These properties describe the HTTP method
method proxy_use_connect : boolWhether to use the CONNECT method if the connection is made via a
web proxy. This is normally true if the transport layer is
Nethttp_client.https_trans_id
method empty_path_replacement : stringThe string to substitute in the request line for the empty path. This is usually "/", and for OPTIONS it is "*".
method is_idempotent : boolWhether 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 : boolWhether the method allows to send a request body
method has_resp_body : boolWhether the method allows to reply with a body. This is true except for HEAD.
Transport layer bindings are used to distinguish between security requirements. There are normally only two types of requirements:
Nethttp_client.http_trans_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://".Nethttp_client.https_trans_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 transport binding to establish further types of security requirements (e.g. that certain client certificates are used), or even other details of the transport connection.
method set_transport_layer : transport_layer_id -> unitSets the transport layer. Note that set_request_uri also sets
this ID, but always to the default for the type of URL.
method same_call : unit -> http_callThis 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:
`UnservedThese 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 -> stringGet the name of the request method. Same as request_method.
method get_host : unit -> stringThe 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 -> intThe 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 -> stringThe 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 -> stringthe 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 -> stringWhat has been sent as body in the (last) request. Same as
request_body # value.
method get_req_header : unit -> (string * string) listDeprecated. 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 -> stringQuery a specific header entry, or raise Not_found
method assoc_multi_req_header : string -> string listReturn 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) listDeprecated. Get the header of the last response. The keys are in lowercase characters again.
method assoc_resp_header : string -> stringQuery a specific header entry of the response.
method assoc_multi_resp_header : string -> string listReturn 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 -> stringDeprecated. 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 * stringReturns the status line of the last response (but status lines with code 100 are ignored). The returned triple is (http_string, code, text)
method private_api : private_api
