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

This web site is published by Informatikbüro Gerd Stolpmann

Plasma	GitLab	Archive
Projects	Blog	Knowledge