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

    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.

Known bug: The rule that media ranges are sorted by degree of "specificness" is not implemented, e.g. that "text/html" is preferred over other "text/*" when both have the same "q" value.

    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_authorization : #Nethttp.http_header_ro -> string * (string * string) list

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.

    val set_authorization : #Nethttp.http_header -> string * (string * string) list -> 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 -> (string * (string * string) list) list

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

All present `Proxy-authenticate` headers are merged.
Raises `Not_found` when there is no `Proxy-authenticate` header.

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

Sets the `Proxy-authenticate` header

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

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.

    val set_proxy_authorization : #Nethttp.http_header -> string * (string * string) list -> 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 -> (string * (string * string) list) list

Returns the `WWW-Authenticate` header as list of challenges `(auth_scheme,auth_params)`.

All present `WWW-Authenticate` headers are merged.
Raises `Not_found` if the header is missing.

    val set_www_authenticate : #Nethttp.http_header -> (string * (string * string) list) 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).