Module Nethttp.Cookie

module Cookie: sig .. end

type t 

Functions to manipulate cookies.

You should know that besides the name and value attribute, user agents will send at most the path, domain and port and usually will not send them at all.

For interoperability, cookies are set using version 0 (by Netscape) unless version 1 (RFC 2965 and the older RFC 2109) fields are set. While version 0 is well supported by browsers, RFC 2109 requires a recent browser and RFC 2965 is usually not supported. You do not have to worry however, cookies are always sent in such a way older browsers understand them -- albeit not all attributes of course -- so your application can be ready for the time RFC 2965 will be the norm.

This cookie representation is preferred over the Netscape-only type Nethttp.netscape_cookie.

N.B. This module appears also as Netcgi.Cookie.

Mutable cookie type

val make : ?max_age:int ->
       ?domain:string ->
       ?path:string ->
       ?secure:bool ->
       ?comment:string ->
       ?comment_url:string ->
       ?ports:int list -> string -> string -> t

make ?expires ?domain ?path ?secure name value creates a new cookie with name name holding value.

val name : t -> string

The name of the cookie.

val value : t -> string

The value of the cookie.

val domain : t -> string option

The domain of the cookie, if set.

val path : t -> string option

The path of the cookie, if set.

val ports : t -> int list option

port c the ports to which the cookie may be returned or [] if not set.

val max_age : t -> int option

The expiration time of the cookie, in seconds. None means that the cookie will be discarded when the browser exits. This information is not returned by the browser.

val secure : t -> bool

Tells whether the cookie is secure. This information is not returned by the browser.

val comment : t -> string

Returns the comment associated to the cookie or "" if it does not exists. This information is not returned by the browser.

val comment_url : t -> string

Returns the comment URL associated to the cookie or "" if it does not exists. This information is not returned by the browser.

val set_value : t -> string -> unit

set_value c v sets the value of the cookie c to v.

val set_max_age : t -> int option -> unit

set_max_age c (Some t) sets the lifetime of the cookie c to t seconds. If t <= 0, it means that the cookie should be discarded immediately. set_expires c None tells the cookie to be discarded when the user agent exits. (Despite the fact that the name is borrowed from the version 1 of the specification, it works transparently with version 0.)

val set_domain : t -> string option -> unit

Cookies are bound to a certain domain, i.e. the browser sends them only when web pages of the domain are requested:

• None: the domain is the hostname of the server.
• Some domain: the domain is domain.

val set_path : t -> string option -> unit

Cookies are also bound to certain path prefixes, i.e. the browser sends them only when web pages at the path or below are requested.

• None: the path is script name + path_info
• Some p: the path is p. With Some "/" you can disable the path restriction completely.

val set_secure : t -> bool -> unit

Cookies are also bound to the type of the web server: set_secure false means servers without SSL, set_secure true means servers with activated SSL ("https").

val set_comment : t -> string -> unit

set_comment c s sets the comment of the cookie c to s which must be UTF-8 encoded (RFC 2279). Because cookies can store personal information, the comment should describe how the cookie will be used so the client can decide whether to allow the cookie or not. To cancel a comment, set it to "".

Cookie version 1 (RFC 2109).

val set_comment_url : t -> string -> unit

set_comment_url c url same as Netcgi.Cookie.set_comment except that the cookie comment is available on the page pointed by url. To cancel, set it to "".

Cookie version 1 (RFC 2965).

val set_ports : t -> int list option -> unit

set ports c (Some p) says that the cookie c must only be returned if the server request comes from one of the listed ports. If p = [], the cookie will only be sent to the request-port it was received from. set_ports c None says that the cookie may be sent to any port.

Cookie version 1 (RFC 2965).

val of_netscape_cookie : Nethttp.netscape_cookie -> t

Convert a Netscape cookie to the new representation

val to_netscape_cookie : t -> Nethttp.netscape_cookie

Convert to Netscape cookie (with information loss)