Ocamlnet 4 Reference Manual : Nethttp.Header

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