module Header:sig..end
This module is a parser/printer for the header fields used in HTTP/1.1.
The get_* functions generally raise Not_found when the queried header
is not present. If the syntax of the field is a comma-separated list of
multiple values, the get_* functions generally merge all headers of
the same type. The order is preserved in this case. The list [] means
that the header exists, but only with empty value. For example,
Accept: text/html
Accept: text/plain
would be returned as ["text/html",[],[]; "text/plain", [],[]]
by get_accept. The header
Accept:
would be returned as [].
The set_* functions generally produce only a single header with comma-
separated values. Existing header are overwritten/removed.
To remove a header, simply use the delete_field method of http_header.
Error behaviour: The get_* functions raise Bad_header_field
when they cannot parse a header field. The set_* functions
raise Invalid_argument when an invalid value is passed to them
(only very few functions do that). The argument of both
exceptions is the function name.
typeparam_value =[ `Q of string | `V of string ]
Some parameters may occur quoted and unquoted. In partivular for authentication it is important to get this aspect right, so we represent values in two ways:
`V s is the already decoded value. Originally it could be in
quotes or not, but the parser removed the quotes already.`Q s is a value where s includes the quotes, i.e. it is the
"raw" string.The parsers below always return values in the `V form. For the
printers, you can specify whether to automatically add quotes
(using `V) or to pass the raw values (using `Q) that already
contains the quotes if needed.
typeauth_challenge =string * (string * param_value) list
The type of a single challenge, used during authentication.
It is interpreted as (mechanism_name, params). The headers
www-authenticate and proxy-authenticate use this.
See RFC 7235 for general information.
typeauth_credentials =string * (string * param_value) list
The type of a single credentials response, used during
authentication. It is interpreted as (mechanism_name, params).
The headers authorize and proxy-authorize use this.
See RFC 7235 for general information.
val parse_quoted_parameters : string -> (string * string) listA generic parser for comma-separated parameters in the form key=value or key="value". Fails if the string cannot be parsed.
val print_param_value : param_value -> stringreturns `Q unchanged, and puts a `V into double quotes if necessary
val value_of_param : param_value -> stringreturn the real value wrapped by `Q or `V
val get_accept : #Nethttp.http_header_ro ->
(string * (string * string) list * (string * string) list) listReturns the Accept header as list of triples (media_range,
media_range_params, accept_params). If there are
accept_params, the first such parameter is always "q".
All present Accept headers are merged. The function returns
[] when there is at least one Accept header, but none of
the headers has a non-empty value. The function raises
Not_found if there no such headers at all (which should be
interpreted as ["*/*",[],[] ] ).
val best_media_type : #Nethttp.http_header_ro -> string list -> string * (string * string) listReturns the best media type for a header and a list of supported types. If any type is acceptable, "*/*" will be returned. If no type is acceptable, "" will be returned. The supported media types should be sorted such that the best type is mentioned first. Of several media types with equal quality the one mentioned first in the list of supported types is chosen. In case several types in the Accept: header match the same type in the list of supported types, the most specific type is chosen.
val set_accept : #Nethttp.http_header ->
(string * (string * string) list * (string * string) list) list -> unitSets the Accept header
val get_accept_charset : #Nethttp.http_header_ro -> (string * (string * string) list) listReturns the Accept-charset header as list of pairs (charset,params).
The only mentioned parameter in RFC 2616 is "q".
All present Accept-charset headers are merged. The function
raises Not_found when there is no Accept-charset header
(which should be interpreted as ["*",[]] ).
val best_charset : #Nethttp.http_header_ro -> string list -> stringReturns the best charset for a header and a list of supported charsets. If any charset is acceptable, "*" will be returned. The supported charsets should be sorted such that the best charset is mentioned first.
This function already implements the special handling of ISO-8859-1 mentioned in RFC 2616.
val set_accept_charset : #Nethttp.http_header -> (string * (string * string) list) list -> unitSets the Accept-charset header
val get_accept_encoding : #Nethttp.http_header_ro -> (string * (string * string) list) listReturns the Accept-encoding header as list of pairs (coding,params).
The only mentioned parameter in RFC 2616 is "q". The RFC describes
compatibility problems with the "q" parameter.
All present Accept-encoding headers are merged. The function
raises Not_found when there is no Accept-encoding header
(which should be interpreted as ["identity",[]] ). The
return value [] must be interpreted as ["identity",[]] .
val best_encoding : #Nethttp.http_header_ro -> string list -> stringReturns the best encoding for a header and a list of supported encodings. If anything else fails, "identity" will be returned. The supported encodings should be sorted such that the best encoding is mentioned first.
val set_accept_encoding : #Nethttp.http_header -> (string * (string * string) list) list -> unitSets the Accept-encoding header
val get_accept_language : #Nethttp.http_header_ro -> (string * (string * string) list) listReturns the Accept-language header as list of pairs
(lang_range,params). The only mentioned parameter in RFC
2616 is "q".
All present Accept-language headers are merged. The function
raises Not_found when there is no Accept-language header
(which should be interpreted as ["*",[]] ).
val set_accept_language : #Nethttp.http_header -> (string * (string * string) list) list -> unitSets the Accept-language header
val get_accept_ranges : #Nethttp.http_header_ro -> string listReturns the Accept-ranges header as list of tokens.
All present Accept-ranges headers are merged. The function
raises Not_found when there is no Accept-ranges
header. The RFC leaves it open how this is to be interpreted
in general.
val set_accept_ranges : #Nethttp.http_header -> string list -> unitSets the Accept-ranges header
val get_age : #Nethttp.http_header_ro -> floatReturns the Age header as number
val set_age : #Nethttp.http_header -> float -> unitSets the Age header
val get_allow : #Nethttp.http_header_ro -> string listReturns the Allow header as list of tokens.
All present Allow headers are merged. The function raises Not_found
when there is no Allow header. The RFC leaves it open how this is
to be interpreted in general.
val set_allow : #Nethttp.http_header -> string list -> unitSets the Allow header
val get_authentication_info : #Nethttp.http_header_ro -> (string * param_value) listReturns the Authentication-Info header as list auth_params,
or raises Not_found if not present.
val set_authentication_info : #Nethttp.http_header -> (string * param_value) list -> unitSets the Authentication-Info header.
: #Nethttp.http_header_ro -> auth_credentialsReturns the Authorization header as pair (auth_scheme,auth_params),
or raises Not_found if not present.
The "Basic" authentication scheme is represented specially as
("basic", [ "credentials", creds ]) where creds are the
Base64-encoded credentials.
At present, parameters are always decoded (`V).
: #Nethttp.http_header -> auth_credentials -> unitSets the Authorization header.
The "Basic" authentication scheme is represented as explained for
get_authorization.
val get_cache_control : #Nethttp.http_header_ro -> Nethttp.cache_control_token listReturns the Cache-control header as list of tokens.
All present Cache-control headers are merged. The function
raises Not_found when there is no Cache-control header.
val set_cache_control : #Nethttp.http_header -> Nethttp.cache_control_token list -> unitSets the Cache-control header
val get_connection : #Nethttp.http_header_ro -> string listReturns the Connection header as list of tokens.
All present Connection headers are merged. The function
raises Not_found when there is no Connection header.
The Connection header must be ignored when received from a HTTP/1.0 client.
val set_connection : #Nethttp.http_header -> string list -> unitSets the Connection header
val get_content_encoding : #Nethttp.http_header_ro -> string listReturns the Content-encoding header as list of tokens.
All present Content-encoding headers are merged.
Not_found when there is no Content-encoding header.val set_content_encoding : #Nethttp.http_header -> string list -> unitSets the Content-encoding header
val get_content_language : #Nethttp.http_header_ro -> string listReturns the Content-language header as list of tokens.
All present Content-language headers are merged.
Not_found when there is no Content-language header.val set_content_language : #Nethttp.http_header -> string list -> unitSets the Content-language header
val get_content_length : #Nethttp.http_header_ro -> int64Returns the Content-length header as number. If the number
is too big for int64, the exception Bad_header_field
"Content-length" will be raised.
Not_found when the header is missing.val set_content_length : #Nethttp.http_header -> int64 -> unitSets the Content-length header
val get_content_location : #Nethttp.http_header_ro -> stringReturns the Content-location header as string.
Not_found when the header is missing.val set_content_location : #Nethttp.http_header -> string -> unitSets the Content-location header
val get_content_md5 : #Nethttp.http_header_ro -> stringReturns the Content-MD5 header as string. The Base64 encoding
has not been touched.
Not_found when the header is missing.val set_content_md5 : #Nethttp.http_header -> string -> unitSets the Content-MD5 header
val get_content_range : #Nethttp.http_header_ro ->
[ `Bytes of (int64 * int64) option * int64 option ]Returns the Content-range header as
`Bytes(byte_range_resp_spec, instance_length). The option value
None corresponds to "*" in the RFC.
Not_found when the header is missing.val set_content_range : #Nethttp.http_header ->
[ `Bytes of (int64 * int64) option * int64 option ] -> unitSets the Content-range header
val get_content_type : #Nethttp.http_header_ro -> string * (string * string) listReturns the Content-type header as pair (media_type, params).
Not_found when the header is missing.val set_content_type : #Nethttp.http_header -> string * (string * string) list -> unitSets the Content-type header
val get_date : #Nethttp.http_header_ro -> floatReturns the Date header as number (seconds since the Epoch).
Not_found when the header is missing.val set_date : #Nethttp.http_header -> float -> unitSets the Date header
val get_etag : #Nethttp.http_header_ro -> Nethttp.etagReturns the Etag header.
Not_found when the header is missing.val set_etag : #Nethttp.http_header -> Nethttp.etag -> unitSets the Etag header
val get_expect : #Nethttp.http_header_ro ->
(string * string option * (string * string) list) listReturns the Expect header as list of triples (token,value,params).
All present Expect headers are merged.
Not_found when there is no Expect header.val set_expect : #Nethttp.http_header ->
(string * string option * (string * string) list) list -> unitSets the Expect header
val get_expires : #Nethttp.http_header_ro -> floatReturns the Expires header as number (seconds since the Epoch).
Not_found when the header is missing.val set_expires : #Nethttp.http_header -> float -> unitSets the Expires header
val get_from : #Nethttp.http_header_ro -> stringReturns the From header as string.
Not_found when the header is missing.val set_from : #Nethttp.http_header -> string -> unitSets the From header
val get_host : #Nethttp.http_header_ro -> string * int optionReturns the Host header as pair (host,port).
Not_found when the header is missing.val set_host : #Nethttp.http_header -> string * int option -> unitSets the Host header
val get_if_match : #Nethttp.http_header_ro -> Nethttp.etag list optionReturns the If-match header. The value None means "*".
Not_found when the header is missing.val set_if_match : #Nethttp.http_header -> Nethttp.etag list option -> unitSets the If-match header
val get_if_modified_since : #Nethttp.http_header_ro -> floatReturns the If-modified-since header as number (seconds
since the Epoch).
Not_found when the header is missing.val set_if_modified_since : #Nethttp.http_header -> float -> unitSets the If-modified-since header
val get_if_none_match : #Nethttp.http_header_ro -> Nethttp.etag list optionReturns the If-none-match header. The value None means "*".
Not_found when the header is missing.val set_if_none_match : #Nethttp.http_header -> Nethttp.etag list option -> unitSets the If-none-match header
val get_if_range : #Nethttp.http_header_ro -> [ `Date of float | `Etag of Nethttp.etag ]Returns the If-range header.
Not_found when the header is missing.val set_if_range : #Nethttp.http_header -> [ `Date of float | `Etag of Nethttp.etag ] -> unitSets the If-range header
val get_if_unmodified_since : #Nethttp.http_header_ro -> floatReturns the If-unmodified-since header as number (seconds
since the Epoch).
Not_found when the header is missing.val set_if_unmodified_since : #Nethttp.http_header -> float -> unitSets the If-unmodified-since header
val get_last_modified : #Nethttp.http_header_ro -> floatReturns the Last-modified header as number (seconds since the Epoch).
Not_found when the header is missing.val set_last_modified : #Nethttp.http_header -> float -> unitSets the Last-modified header
val get_location : #Nethttp.http_header_ro -> stringReturns the Location header as string.
Not_found when the header is missing.val set_location : #Nethttp.http_header -> string -> unitSets the Location header
val get_max_forwards : #Nethttp.http_header_ro -> intReturns the Max-forwards header as number.
Not_found when the header is missing.val set_max_forwards : #Nethttp.http_header -> int -> unitSets the Max-forwards header
val get_pragma : #Nethttp.http_header_ro -> (string * string option) listReturns the Pragma header as list of pairs (token,value).
All present Pragma headers are merged.
Not_found when there is no Pragma header.val set_pragma : #Nethttp.http_header -> (string * string option) list -> unitSets the Pragma header
val get_proxy_authenticate : #Nethttp.http_header_ro -> auth_challenge listReturns the Proxy-authenticate header as list of challenges
(auth_scheme,auth_params). See also get_www_authenticate.
All present Proxy-authenticate headers are merged.
Not_found when there is no Proxy-authenticate header.
At present, parameters are always decoded (`V).val set_proxy_authenticate : #Nethttp.http_header -> auth_challenge list -> unitSets the Proxy-authenticate header
val get_proxy_authentication_info : #Nethttp.http_header_ro -> (string * param_value) listReturns the Proxy-Authentication-Info header as list
auth_params, or raises Not_found if not present.
val set_proxy_authentication_info : #Nethttp.http_header -> (string * param_value) list -> unitSets the Proxy-Authentication-Info header.
: #Nethttp.http_header_ro -> auth_credentialsReturns the Proxy-authorization header as pair
(auth_scheme,auth_params).
Not_found when the header is
missing.
The "Basic" authentication scheme is represented specially as
("basic", [ "credentials", creds ]) where creds are the
Base64-encoded credentials.
At present, parameters are always decoded (`V). : #Nethttp.http_header -> auth_credentials -> unitSets the Proxy-authorization header
The "Basic" authentication scheme is represented as explained for
get_proxy_authorization.
val get_range : #Nethttp.http_header_ro -> [ `Bytes of (int64 option * int64 option) list ]Returns the Range header as `Bytes ranges, where the list ranges
has elements of the form (Some first_pos, Some last_pos),
(Some first_pos, None) (prefix range), or (None, Some
last_pos) (suffix range).
Not_found when the header is missing.val set_range : #Nethttp.http_header ->
[ `Bytes of (int64 option * int64 option) list ] -> unitSets the Range header
val get_referer : #Nethttp.http_header_ro -> stringReturns the Referer header as string.
Not_found when the header is missing.val get_referrer : #Nethttp.http_header_ro -> stringSame, for addicts of correct orthography
val set_referer : #Nethttp.http_header -> string -> unitSets the Referer header
val set_referrer : #Nethttp.http_header -> string -> unitSame, for addicts of correct orthography
val get_retry_after : #Nethttp.http_header_ro -> [ `Date of float | `Seconds of int ]Returns the Retry-after header.
Not_found when the header is missing.val set_retry_after : #Nethttp.http_header -> [ `Date of float | `Seconds of int ] -> unitSets the Retry-after header
val get_server : #Nethttp.http_header_ro -> stringReturns the Server header as uninterpreted string (including
comments).
Not_found when the header is missing.val set_server : #Nethttp.http_header -> string -> unitSets the Server header
val get_te : #Nethttp.http_header_ro ->
(string * (string * string) list * (string * string) list) listReturns the TE header as list of triples
(te_token, te_params, accept_params).
If there are accept_params, the first such parameter is always "q".
All present TE headers are merged. The function returns [] when
there is at least one TE header, but none of the headers has a
non-empty value.
Not_found if there no such headers at all.val set_te : #Nethttp.http_header ->
(string * (string * string) list * (string * string) list) list -> unitSets the TE header
val get_trailer : #Nethttp.http_header_ro -> string listReturns the Trailer header as list of field names.
All present Trailer headers are merged. The function returns
[] when there is at least one Trailer header, but none of
the headers has a non-empty value.
Not_found if there no such headers at all.val set_trailer : #Nethttp.http_header -> string list -> unitSets the Trailer header
val get_transfer_encoding : #Nethttp.http_header_ro -> (string * (string * string) list) listReturns the Transfer-encoding header as list of pairs
(token, params).
All present Transfer-encoding headers are merged. The
function returns [] when there is at least one
Transfer-encoding header, but none of the headers has a
non-empty value.
Not_found if there no such headers at all.val set_transfer_encoding : #Nethttp.http_header -> (string * (string * string) list) list -> unitSets the Transfer-encoding header
val get_upgrade : #Nethttp.http_header_ro -> string listReturns the Upgrade header as list of products.
All present Upgrade headers are merged. The function returns
[] when there is at least one Upgrade header, but none of
the headers has a non-empty value.
Not_found if there no such headers at all.val set_upgrade : #Nethttp.http_header -> string list -> unitSets the Upgrade header
val get_user_agent : #Nethttp.http_header_ro -> stringReturns the User-agent header as uninterpreted string
(including comments).
Not_found if the header is missing.val set_user_agent : #Nethttp.http_header -> string -> unitSets the User-agent header
val get_vary : #Nethttp.http_header_ro -> [ `Fields of string list | `Star ]Returns the Vary header.
Not_found if the header is missing.val set_vary : #Nethttp.http_header -> [ `Fields of string list | `Star ] -> unitSets the Vary header
val get_www_authenticate : #Nethttp.http_header_ro -> auth_challenge listReturns the WWW-Authenticate header as list of challenges
(auth_scheme,auth_params).
All present WWW-Authenticate headers are merged.
The scheme "negotiate" uses a deviating header format.
This data is returned as e.g. ("negotiate", ["credentials", data]).
At present, parameters are always decoded (`V).
Not_found if the header is missing.val set_www_authenticate : #Nethttp.http_header -> auth_challenge list -> unitSets the WWW-Authenticate header
: #Nethttp.http_header_ro -> (string * string) listGet the (Netscape) cookies as (name,value) pairs (or Not_found).
: #Nethttp.http_header_ro -> Nethttp.Cookie.t listGet the cookies in the Nethttp.Cookie.t representation
(the suffix "_ct" reminds of Cookie.t).
This function also supports version 1 cookies.
Returns the empty list if there are no cookies.
: #Nethttp.http_header -> (string * string) list -> unitSet the Cookie header. Note: This does not set cookies in the client,
use set_set_cookie instead!
: #Nethttp.http_header_ro -> Nethttp.netscape_cookie listGet the Set-Cookie header
: #Nethttp.http_header -> Nethttp.netscape_cookie list -> unitSet the Set-Cookie header
: #Nethttp.http_header -> Nethttp.Cookie.t list -> unitSet the Set-Cookie and Set-Cookie2 headers:
set_set_cookie_ct header cookies sets the cookies in header
using version 0 or version 1 depending on whether version 1
fields are used. For better browser compatibility, if
"Set-cookie2" (RFC 2965) is issued, then a "Set-cookie"
precedes (declaring the same cookie with a limited number of
options).