Module Nethttp.Header

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.

type param_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.

type auth_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.

type auth_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) list

A 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 -> string

returns `Q unchanged, and puts a `V into double quotes if necessary

val value_of_param : param_value -> string

return the real value wrapped by `Q or `V

val get_accept : #Nethttp.http_header_ro ->
       (string * (string * string) list * (string * string) list) list

Returns 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) list

Returns 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 -> unit

Sets the Accept header

val get_accept_charset : #Nethttp.http_header_ro -> (string * (string * string) list) list

Returns 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 -> string

Returns 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 -> unit

Sets the Accept-charset header

val get_accept_encoding : #Nethttp.http_header_ro -> (string * (string * string) list) list

Returns 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 -> string

Returns 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 -> unit

Sets the Accept-encoding header

val get_accept_language : #Nethttp.http_header_ro -> (string * (string * string) list) list

Returns 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 -> unit

Sets the Accept-language header

val get_accept_ranges : #Nethttp.http_header_ro -> string list

Returns 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 -> unit

Sets the Accept-ranges header

val get_age : #Nethttp.http_header_ro -> float

Returns the Age header as number

val set_age : #Nethttp.http_header -> float -> unit

Sets the Age header

val get_allow : #Nethttp.http_header_ro -> string list

Returns 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 -> unit

Sets the Allow header

val get_authentication_info : #Nethttp.http_header_ro -> (string * param_value) list

Returns 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 -> unit

Sets the Authentication-Info header.

val get_authorization : #Nethttp.http_header_ro -> auth_credentials

Returns 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).

val set_authorization : #Nethttp.http_header -> auth_credentials -> unit

Sets 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 list

Returns 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 -> unit

Sets the Cache-control header

val get_connection : #Nethttp.http_header_ro -> string list

Returns 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 -> unit

Sets the Connection header

val get_content_encoding : #Nethttp.http_header_ro -> string list

Returns the Content-encoding header as list of tokens.

All present Content-encoding headers are merged.

Raises Not_found when there is no Content-encoding header.

val set_content_encoding : #Nethttp.http_header -> string list -> unit

Sets the Content-encoding header

val get_content_language : #Nethttp.http_header_ro -> string list

Returns the Content-language header as list of tokens.

All present Content-language headers are merged.

Raises Not_found when there is no Content-language header.

val set_content_language : #Nethttp.http_header -> string list -> unit

Sets the Content-language header

val get_content_length : #Nethttp.http_header_ro -> int64

Returns the Content-length header as number. If the number is too big for int64, the exception Bad_header_field "Content-length" will be raised.

Raises Not_found when the header is missing.

val set_content_length : #Nethttp.http_header -> int64 -> unit

Sets the Content-length header

val get_content_location : #Nethttp.http_header_ro -> string

Returns the Content-location header as string.

Raises Not_found when the header is missing.

val set_content_location : #Nethttp.http_header -> string -> unit

Sets the Content-location header

val get_content_md5 : #Nethttp.http_header_ro -> string

Returns the Content-MD5 header as string. The Base64 encoding has not been touched.

Raises Not_found when the header is missing.

val set_content_md5 : #Nethttp.http_header -> string -> unit

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

Raises Not_found when the header is missing.

val set_content_range : #Nethttp.http_header ->
       [ `Bytes of (int64 * int64) option * int64 option ] -> unit

Sets the Content-range header

val get_content_type : #Nethttp.http_header_ro -> string * (string * string) list

Returns the Content-type header as pair (media_type, params).

Raises Not_found when the header is missing.

val set_content_type : #Nethttp.http_header -> string * (string * string) list -> unit

Sets the Content-type header

val get_date : #Nethttp.http_header_ro -> float

Returns the Date header as number (seconds since the Epoch).

Raises Not_found when the header is missing.

val set_date : #Nethttp.http_header -> float -> unit

Sets the Date header

val get_etag : #Nethttp.http_header_ro -> Nethttp.etag

Returns the Etag header.

Raises Not_found when the header is missing.

val set_etag : #Nethttp.http_header -> Nethttp.etag -> unit

Sets the Etag header

val get_expect : #Nethttp.http_header_ro ->
       (string * string option * (string * string) list) list

Returns the Expect header as list of triples (token,value,params).

All present Expect headers are merged.

Raises Not_found when there is no Expect header.

val set_expect : #Nethttp.http_header ->
       (string * string option * (string * string) list) list -> unit

Sets the Expect header

val get_expires : #Nethttp.http_header_ro -> float

Returns the Expires header as number (seconds since the Epoch).

Raises Not_found when the header is missing.

val set_expires : #Nethttp.http_header -> float -> unit

Sets the Expires header

val get_from : #Nethttp.http_header_ro -> string

Returns the From header as string.

Raises Not_found when the header is missing.

val set_from : #Nethttp.http_header -> string -> unit

Sets the From header

val get_host : #Nethttp.http_header_ro -> string * int option

Returns the Host header as pair (host,port).

Raises Not_found when the header is missing.

val set_host : #Nethttp.http_header -> string * int option -> unit

Sets the Host header

val get_if_match : #Nethttp.http_header_ro -> Nethttp.etag list option

Returns the If-match header. The value None means "*".

Raises Not_found when the header is missing.

val set_if_match : #Nethttp.http_header -> Nethttp.etag list option -> unit

Sets the If-match header

val get_if_modified_since : #Nethttp.http_header_ro -> float

Returns the If-modified-since header as number (seconds since the Epoch).

Raises Not_found when the header is missing.

val set_if_modified_since : #Nethttp.http_header -> float -> unit

Sets the If-modified-since header

val get_if_none_match : #Nethttp.http_header_ro -> Nethttp.etag list option

Returns the If-none-match header. The value None means "*".

Raises Not_found when the header is missing.

val set_if_none_match : #Nethttp.http_header -> Nethttp.etag list option -> unit

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

Raises Not_found when the header is missing.

val set_if_range : #Nethttp.http_header -> [ `Date of float | `Etag of Nethttp.etag ] -> unit

Sets the If-range header

val get_if_unmodified_since : #Nethttp.http_header_ro -> float

Returns the If-unmodified-since header as number (seconds since the Epoch).

Raises Not_found when the header is missing.

val set_if_unmodified_since : #Nethttp.http_header -> float -> unit

Sets the If-unmodified-since header

val get_last_modified : #Nethttp.http_header_ro -> float

Returns the Last-modified header as number (seconds since the Epoch).

Raises Not_found when the header is missing.

val set_last_modified : #Nethttp.http_header -> float -> unit

Sets the Last-modified header

val get_location : #Nethttp.http_header_ro -> string

Returns the Location header as string.

Raises Not_found when the header is missing.

val set_location : #Nethttp.http_header -> string -> unit

Sets the Location header

val get_max_forwards : #Nethttp.http_header_ro -> int

Returns the Max-forwards header as number.

Raises Not_found when the header is missing.

val set_max_forwards : #Nethttp.http_header -> int -> unit

Sets the Max-forwards header

val get_pragma : #Nethttp.http_header_ro -> (string * string option) list

Returns the Pragma header as list of pairs (token,value).

All present Pragma headers are merged.

Raises Not_found when there is no Pragma header.

val set_pragma : #Nethttp.http_header -> (string * string option) list -> unit

Sets the Pragma header

val get_proxy_authenticate : #Nethttp.http_header_ro -> auth_challenge list

Returns the Proxy-authenticate header as list of challenges (auth_scheme,auth_params). See also get_www_authenticate.

All present Proxy-authenticate headers are merged.

Raises 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 -> unit

Sets the Proxy-authenticate header

val get_proxy_authentication_info : #Nethttp.http_header_ro -> (string * param_value) list

Returns 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 -> unit

Sets the Proxy-Authentication-Info header.

val get_proxy_authorization : #Nethttp.http_header_ro -> auth_credentials

Returns the Proxy-authorization header as pair (auth_scheme,auth_params).

Raises 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).

val set_proxy_authorization : #Nethttp.http_header -> auth_credentials -> unit

Sets 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).

Raises Not_found when the header is missing.

val set_range : #Nethttp.http_header ->
       [ `Bytes of (int64 option * int64 option) list ] -> unit

Sets the Range header

val get_referer : #Nethttp.http_header_ro -> string

Returns the Referer header as string.

Raises Not_found when the header is missing.

val get_referrer : #Nethttp.http_header_ro -> string

Same, for addicts of correct orthography

val set_referer : #Nethttp.http_header -> string -> unit

Sets the Referer header

val set_referrer : #Nethttp.http_header -> string -> unit

Same, for addicts of correct orthography

val get_retry_after : #Nethttp.http_header_ro -> [ `Date of float | `Seconds of int ]

Returns the Retry-after header.

Raises Not_found when the header is missing.

val set_retry_after : #Nethttp.http_header -> [ `Date of float | `Seconds of int ] -> unit

Sets the Retry-after header

val get_server : #Nethttp.http_header_ro -> string

Returns the Server header as uninterpreted string (including comments).

Raises Not_found when the header is missing.

val set_server : #Nethttp.http_header -> string -> unit

Sets the Server header

val get_te : #Nethttp.http_header_ro ->
       (string * (string * string) list * (string * string) list) list

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

Raises Not_found if there no such headers at all.

val set_te : #Nethttp.http_header ->
       (string * (string * string) list * (string * string) list) list -> unit

Sets the TE header

val get_trailer : #Nethttp.http_header_ro -> string list

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

Raises Not_found if there no such headers at all.

val set_trailer : #Nethttp.http_header -> string list -> unit

Sets the Trailer header

val get_transfer_encoding : #Nethttp.http_header_ro -> (string * (string * string) list) list

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

Raises Not_found if there no such headers at all.

val set_transfer_encoding : #Nethttp.http_header -> (string * (string * string) list) list -> unit

Sets the Transfer-encoding header

val get_upgrade : #Nethttp.http_header_ro -> string list

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

Raises Not_found if there no such headers at all.

val set_upgrade : #Nethttp.http_header -> string list -> unit

Sets the Upgrade header

val get_user_agent : #Nethttp.http_header_ro -> string

Returns the User-agent header as uninterpreted string (including comments).

Raises Not_found if the header is missing.

val set_user_agent : #Nethttp.http_header -> string -> unit

Sets the User-agent header

val get_vary : #Nethttp.http_header_ro -> [ `Fields of string list | `Star ]

Returns the Vary header.

Raises Not_found if the header is missing.

val set_vary : #Nethttp.http_header -> [ `Fields of string list | `Star ] -> unit

Sets the Vary header

val get_www_authenticate : #Nethttp.http_header_ro -> auth_challenge list

Returns 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).

Raises Not_found if the header is missing.

val set_www_authenticate : #Nethttp.http_header -> auth_challenge list -> unit

Sets the WWW-Authenticate header

val get_cookie : #Nethttp.http_header_ro -> (string * string) list

Get the (Netscape) cookies as (name,value) pairs (or Not_found).

val get_cookie_ct : #Nethttp.http_header_ro -> Nethttp.Cookie.t list

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

val set_cookie : #Nethttp.http_header -> (string * string) list -> unit

Set the Cookie header. Note: This does not set cookies in the client, use set_set_cookie instead!

val get_set_cookie : #Nethttp.http_header_ro -> Nethttp.netscape_cookie list

Get the Set-Cookie header

val set_set_cookie : #Nethttp.http_header -> Nethttp.netscape_cookie list -> unit

Set the Set-Cookie header

val set_set_cookie_ct : #Nethttp.http_header -> Nethttp.Cookie.t list -> unit

Set 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).

This web site is published by Informatikbüro Gerd Stolpmann

Plasma	GitLab	Archive
Projects	Blog	Knowledge