ns_cookie(n) 4.99.5 naviserver "NaviServer Built-In Commands"

Name

ns_cookie - HTTP cookies

Table Of Contents
Synopsis
Description
COMMANDS
OPTIONS
EXAMPLES
See Also
Keywords

Synopsis

ns_setcookie ?-secure bool? ?-scriptable bool? ?-domain d? ?-path p? ?-expires t? ?--? name data
ns_getcookie name ?default?
ns_deletecookie ?-secure bool? ?-domain d? ?-path p? ?--? name

Cookies are small pieces of data which the server sends to the user agent and the user agent sends back during subsequent requests. You can use this mechanism to save state between otherwise statelss HTTP requests.

Cookie size limits are user agent dependent. Practically, as cookies are sent with every request to the server (for which the optional domain and path match), size should be kept to a minimum.

These commands implement the original version 1 Netscape cookie protocol which is widely supported by user agents.

COMMANDS

ns_setcookie ?-secure bool? ?-scriptable bool? ?-domain d? ?-path p? ?-expires t? ?--? name data

Send data to the user agent as a cookie, using name as the identifier. The user agent will send the cookie data back to the server during subsequent requests for which the domain and path match, if it has not expired.

A cookie is identified by a signature which is made up of it's name, domain, path and secure flag. A cookie named foo with path /x/y is a different cookie than one named foo with path /x/y/z. During a request for the URL /x/y/z both cookies named foo are sent.

The data will be URL-encoded to escape special characters. ns_getcookie correctly reverses the encoding.

ns_getcookie name ?default?

Get the cookie data identified by name. If no such cookie exists then default is returned. If default is not given and no such cookie exists, an error is raised.

Only the first cookie identified by name is returned. If two cookies with the same name are sent by the user agent, each with a different domain and/or path, which cookie data is returned depends on the user agent.

When using domain or path to restrict cookies, use a unique name for each restricted cookie.

ns_deletecookie ?-secure bool? ?-domain d? ?-path p? ?--? name

Instruct the client to delete the cookie data identified by name. The complete cookie signature including domain and path must match for the cookie to be deleted.

OPTIONS

-secure boolean

If the secure option is true then the the cookie will only be sent back to the server when the client uses a secure (TLS/SSL) connection.

-scriptable boolean

If the scriptable option is false or not given the cookie is unavailable to javascript on the client. This can prevent cross site scripting attacks (XSS) on clients which support the HttpOnly option. Set -scriptable to true if you need to access the cookie via javascript.

-domain domain

Restrict the cookie to a domain name, such as example.com. The current domain is implied if none is specified.

-path path

Restrict the cookie to a URL path such as /foo/bar. If no path is specified then the cookie will be back sent to the server for all requests. If a path is specified the cookie will only be sent back for requests which match the specified path, or a sub-path.

-expires time

The cookie will expire in time seconds, after which the client will no longer send the cookie back to the server. If time is large it is treated as the absolute time in the future when the cookie should expire. The special value -1 may be used to indicate that the cookie should never expire.

The expiry time is valid across browser sessions. If no expiry is specified then the cookie will expire when the browser session ends, which is ususally when the user closes their browser.

EXAMPLES

Track all user agents which ever vist out site:

proc browser_tracking_filter {} {
    if {![ns_getcookie first_visit 0]} {
        ns_setcookie -expires -1 -- first_visit [clock seconds]
    }
}
ns_register_filter preauth GET /* browser_tracking_filter

Keywords

cookie, session