Plasma GitLab Archive
Projects Blog Knowledge

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. 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_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
Powered by Caml