module Http_client:HTTP 1.1 clientsig
..end
Http_client.Convenience
.
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 Http_error of (int * string)
get_resp_body
.exception No_reply
exception Too_many_redirections
exception Http_protocol of exn
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 'a
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 'a
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 | *) |
| |
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 | `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()
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. | *) |
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).
type
http_options = {
|
synchronization : |
(* | Default: Pipeline 5 . | *) |
|
maximum_connection_failures : |
(* | This option limits the number of connection attempts. Default: 5 | *) |
|
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 | *) |
|
verbose_status : |
|||
|
verbose_request_header : |
|||
|
verbose_response_header : |
|||
|
verbose_request_contents : |
|||
|
verbose_response_contents : |
|||
|
verbose_connection : |
(* | Enable various debugging message types.
| *) |
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 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
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 basic_auth_method :object
..end
class digest_auth_method :basic_auth_method
type
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.
Aggressive caching is an experimental feature. Reports about success
and/or problems are very welcome.
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 -> ...
| ...
open Http_client.Convenience
for simple applications.module Convenience:sig
..end