Ocamlnet 4 Reference Manual : Nethttp.Cookie

# 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`.
`max_age` : see `Netcgi.Cookie.set_max_age`. Default: when user agent exits.
`domain` : see `Netcgi.Cookie.set_domain`. Default: hostname of the server.
`path` : see `Netcgi.Cookie.set_path`. Default: script name + path_info.
`secure` : see `Netcgi.Cookie.set_secure`. Default: `false`.
`comment` : see `Netcgi.Cookie.set_comment`. Default: `""`.
`comment_url` : see `Netcgi.Cookie.set_comment_url`. Default: `""`.
`ports` : see `Netcgi.Cookie.set_ports`. Default: same port the cookie was sent.

    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)