module Http_client:sig
..end
Http_client.Convenience
.Https_client
(in library
equeue-ssl
). HTTPS proxies are also supported (CONNECT method) (1)set_accept_encoding
) (1)(2) These features can be implemented on top of this module if really needed, but there is no special support for them.
Related modules/software:
Http_fs
allows you to access HTTP servers in the style of filesystems
The module can be compiled such that it is thread-safe. In particular,
one has to link the http_client_mt.cmxo
object, and thread-safety is
restricted to the following kinds of usage:
Convenience
module even serializes; see below.exception Bad_message of string
exception No_reply
exception Too_many_redirections
exception Name_resolution_error of string
Uq_engines.Host_not_found
exception URL_syntax_error of string
exception Timeout of string
exception Proxy_error of int
exception Response_too_large
exception Http_protocol of exn
exception Http_error of (int * string)
get_resp_body
, and by the
Http_client.Convenience
module.typestatus =
[ `Client_error
| `Http_protocol_error of exn
| `Redirection
| `Server_error
| `Successful
| `Unserved ]
`Unserved
: The call has not yet been finished`HTTP_protocol_error e
: An error on HTTP level occurred. Corresponds
to the exception Http_protocol
.`Successful
: The call is successful, and the response code is between
200 and 299.`Redirection
: The call is successful, and the response code is
between 300 and 399.`Client_error
: The call failed with a response code between 400 and
499.`Server_error
: The call failed for any other reason.type 'message_class
how_to_reconnect =
| |
Send_again |
(* | Send the request automatically again | *) |
| |
Request_fails |
(* | Drop the request | *) |
| |
Inquire of |
(* | If the function return true send again, otherwise
drop the request. | *) |
| |
Send_again_if_idem |
(* | Default behaviour: Send_again for idempotent
methods (GET, HEAD), Request_fails for the rest | *) |
type 'message_class
how_to_redirect =
| |
Redirect |
(* | Perform the redirection | *) |
| |
Do_not_redirect |
(* | No redirection | *) |
| |
Redirect_inquire of |
(* | If the function return true redirect, otherwise
do not redirect. It is legal to set the Location
header as part of the action performed by the
function. (Should be an absolute http URL.) | *) |
| |
Redirect_if_idem |
(* | Default behaviour: Redirect for idempotent
methods (GET, HEAD), Do_not_redirect for the rest | *) |
type
private_api
http_call
class typetyperesponse_body_storage =
[ `Body of unit -> Netmime.mime_body
| `Device of unit -> Uq_io.out_device
| `File of unit -> string
| `Memory ]
`Memory
: The response body is in-memory`File f
: The response body is stored into the file whose name
is returned by f()
`Body f
: The response body is stored into the object returned
by f()
`Device f
: The response is directly forwarded to the device
obtained by f()
(new since Ocamlnet-3.3)f
is called in the latter cases the response
header has already been received, and can be retrieved with the
response_header
method of the call object. Also, response_status_text
,
response_status_code
, and response_status
return meaningful
values.type
synchronization =
| |
Sync |
(* | The next request begins after the response of the last request has been received. | *) |
| |
Pipeline of |
(* | The client is allowed to send several requests without waiting
for responses. The number is the maximum number of unreplied
requests that are allowed. A typical value: 5.
If you increase this value, the risk becomes higher that requests
must be repeatedly sent to the server in the case the connection
crashes. Increasing is recommended if you send a bigger number of
GET or HEAD requests to the server. Decreasing is recommended if you
send large POST or PUT requests to the server.
Values > 8 are interpreted as 8. | *) |
The first request/response round is always done in
Sync mode, because the protocol version of the other side
is not known at that moment. Pipeline
requires HTTP/1.1.
In previous versions of netclient there was a third option,
Sync_with_handshake_before_request_body
. This option is no
longer necessary because the HTTP specification has been updated
in the meantime, and there is a better mechanism now (the
Expect
header is set).
typeresolver =
Unixqueue.unix_event_system ->
string -> (Unix.inet_addr option -> unit) -> unit
r
called as r esys name reply
.
As name
the name to resolve is passed. The resolver must
finally call reply
with either the resolved address or
with None
, indicating an error in the latter case.
The event system esys
can be used to carry out the resolution
process in an asynchronous way, but this is optional.
Only 1:1 resolution is supported, 1:n resolution not.
typechannel_binding_id =
int
Http_client.http_cb_id
for HTTP connectionsHttp_client.https_cb_id
for HTTPS connections without user
certificatesHttp_client.proxy_only_cb_id
for the restriction that this
protocol can only be used via a web proxytype
http_options = {
|
synchronization : |
(* | Default: Pipeline 5 . | *) |
|
maximum_connection_failures : |
(* | This option limits the number of connection attempts. Default: 2 | *) |
|
maximum_message_errors : |
(* | This option limits the number of protocol errors tolerated per request. If a request leads to a protocol error, the connection is shut down, the server is connected again, and the request is tried again (if the kind of the message allows retransmission). If a request repeatedly fails, this option limits the number of retransmissions. Default: 2 | *) |
|
inhibit_persistency : |
(* | This option turns persistent connections off.
Default: false
It is normally not necessary to change this option. | *) |
|
connection_timeout : |
(* | If there is no network transmission for this period of time, the connection is shut down, and tried again. Default: 300.0 (seconds) It may be necessary to increase this value if HTTP is used for batch applications that contact extremely slow services. | *) |
|
number_of_parallel_connections : |
(* | The client keeps up to this number of parallel connections to a single content server or proxy. Default: 2 You may increase this value if you are mainly connected with an HTTP/1.0 proxy. | *) |
|
maximum_redirections : |
(* | The maximum number of redirections per message | *) |
|
handshake_timeout : |
(* | The timeout when waiting for "100 Continue". Default: 1.0 | *) |
|
resolver : |
(* | The function for name resolution | *) |
|
configure_socket : |
(* | A function to configure socket options | *) |
|
schemes : |
(* | The list of supported URL schemes. The tuples mean
(scheme, syntax, default_port, cb) . By default, the
schemes "http", "https", and "ipp" are supported. | *) |
|
verbose_status : |
|||
|
verbose_request_header : |
|||
|
verbose_response_header : |
|||
|
verbose_request_contents : |
|||
|
verbose_response_contents : |
|||
|
verbose_connection : |
|||
|
verbose_events : |
(* | Enable various debugging message types.
verbose_status and verbose_connection are enabled.
Note that you also have to set Debug.enable to true to see
any log message at all! | *) |
let opts = pipeline # get_options in
let new_opts = { opts with <field> = <value>; ... } in
pipeline # set_options new_opts
New fields can be added anytime to this record, and this style
of changing options is transparent to field additions.
typeheader_kind =
[ `Base | `Effective ]
`Base
header is set by the user of http_call
and is never
changed during processing the call. The `Effective
header is a copy
of the base header at the time the request is sent. The effective header
contains additions like Content-length
and authentication info.class type http_call =object
..end
class type transport_channel_type =object
..end
class virtual generic_call :object
..end
http_call
.
class get_call :http_call
class trace_call :http_call
class options_call :http_call
class head_call :http_call
class post_call :http_call
class put_call :http_call
class delete_call :http_call
class get :string ->
http_call
class trace :string -> int ->
http_call
class options :string ->
http_call
class head :string ->
http_call
class post :string -> (string * string) list ->
http_call
class post_raw :string -> string ->
http_call
class put :string -> string ->
http_call
class delete :string ->
http_call
class type key =object
..end
key
is a user/password combination for a certain realm
val key : user:string ->
password:string -> realm:string -> domain:string list -> key
class type key_handler =object
..end
class key_ring :?uplink:#key_handler -> unit ->
object
..end
key_ring
is a cache for keys.
class type auth_session =object
..end
auth_session
represents an authenticated session
class type auth_handler =object
..end
class basic_auth_handler :?enable_auth_in_advance:bool -> #key_handler ->
auth_handler
class digest_auth_handler :?enable_auth_in_advance:bool -> #key_handler ->
auth_handler
class unified_auth_handler :#key_handler ->
auth_handler
class basic_auth_method :object
..end
class digest_auth_method :basic_auth_method
typeconnection_cache =
Http_client_conncache.connection_cache
val close_connection_cache : connection_cache -> unit
val create_restrictive_cache : unit -> connection_cache
val create_aggressive_cache : unit -> connection_cache
close_connection_cache
) when the
cache is no longer in use.val http_cb_id : channel_binding_id
val https_cb_id : channel_binding_id
val proxy_only_cb_id : channel_binding_id
val new_cb_id : unit -> channel_binding_id
val http_transport_channel_type : transport_channel_type
typeproxy_type =
[ `Http_proxy | `Socks5 ]
class pipeline :object
..end
let call = new get "http://server/path" in
let pipeline = new pipeline in
pipeline # add call;
pipeline # run(); (* Now the HTTP client is working... *)
match call # status with
| `Successful -> ...
| ...
val parse_proxy_setting : string -> string * int * (string * string) option
http_proxy
,
i.e. an HTTP URL. The argument is the URL.
Returns (host,port,auth)
where auth
may include user name and
password.val parse_no_proxy : string -> string list
no_proxy
. Returns
the list of domains.open Http_client.Convenience
for simple applications.module Convenience:sig
..end
module Debug:sig
..end