# Module: Cookies

## About this module

The Cookie module parses received cookie headers, processes them, rejects invalid onces based on rules or filters, and stores the accepted ones for the specified period, and when requested generates a list of cookies currently stored for the domain of the URL for which the cookies are requested.

Supported protocols:

- Netscape Cookies
- RFC 2965

## Interface overview and API documentation

API documentation generated by Doxygen contains all necessary information for the external APIs.

The Cookie_Manager class is part of the URL_Manager class from the URL module, and is used as part of the API provided through the URL API and URL_Manager.

Cookie_Manager objects may be created as standalone objects used to administrate a separate cookie database, persistent or temporary, identified by a context ID stored in each URL_Rep object associated with the store. Management of these objects is done by the Cookie_Manager that is included in the URL_Manager class.

### Primary API

g_url_api->GetCookiesL()
  This function is used to retrieve cookies for the specified URL
g_url_api->HandleSingleCookieL()
  This function is used by non-protocol callers to set cookies for the specified URL
g_url_manager->HandleCookiesL()
  This function is used by protocol callers to set cookies from headers for the specified URL.

## Implementation description

API documentation generated by Doxygen contains information about the internal organization of the module.

### Cookie_Manager

The Cookie_Manager contains a database of all cookies, organized as a tree of domains, and for each domain there is a tree database organizing the cookies and the pathstructure for which cookies are set. This database is stored in the cookies4.dat file in a tree structure.

The cookies are processed either as a sequence of headers, provided by the URL module, or individual strings from the JavaScript document.cookie DOM object or HTML Meta tags.

When a cookies are received each individual header is broken up into individual name/value argument pairs by the formats module. Set-Cookie2 headers, which can set multiple cookies in a single header are initially broken up into the individual cookies before the name/value split.

After parsing, validation and preparation the cookies are inserted into a list of accepted cookies. This list is used to resolve duplicates. After all headers are processed the remaining cookies are passed on to be inserted into the database, optionally the user is asked first.

When cookies are retrieved for a given URL, a list of cookies are written to a temporary buffer, the selection of which are decided by the scheme, servername, port, and the path components of the request URL.

The filter rules used for cookies are maintained by the relevant ServerNames.

### Footprint

The module is fairly small.

Various features can be enabled or disabled, either through feature defines or specific defines

### Dynamic memory use and OOM handling

OOM policies

  Most of the functions LEAVE in case of OOM

Who handles OOM?
  In the case of LEAVE functions the caller must TRAP the errors, and handle the OOM situations. In the case of the internal functions these usually aborts their operation with an error message, and a raised status flag, which must be handled either by the caller, or the document.
Flow

  Part of the module is message callback based, and these functions are not able to report OOM situations directly to the documents or UI. In these cases the current operation will be terminated, and errormessages sent.

  Much of the external API is based on direct calls. In many cases these are LEAVE bases, and callers must TRAP them and handle them appropriately.

Heap memory usage

  Cookies can consume up to 4 KB per cookie, but should usually average less than 300 bytes.

  The maximum number of cookies range from 30 for some limited memory configuration, up to 300 for contexts and 65000 for desktop versions.

Stack memory usage

  Usually large objects are allocated.

  In most cases stack consumption should be less than 300 bytes.

Static memory usage

  A couple of buffers in the Cookie manager (part of URL manager) will normally allocate 5-6KB. In additon to this, the object maintains all the stored cookies, which will range from less than 100 bytes to about 4KB

  The maximum number of cookies range from 30 for some limited memory configuration, up to 300 for contexts and 65000 for desktop versions.

  The allocated objects are deleted by URL_Manager or URL_API on exit

Caching and freeing memory

  The cookie databases can be destroyed by a call to g_url_api->ClearCookiesL() or g_url_api->PurgeData(). Calls to the latter can be restricted to session cookies (those that are not stored to disk) or delete all cookies.

Freeing memory on exit
  The destruction of the URL_Manager destroys the Cookie_Manager, and all temporary buffers, the stored cookies and all extra cookie contexts.
Temp buffers

  The Cookie Manager maintains two temporary buffers that are used internally.

Memory tuning

  At present there are no opportunities to tune memory use.

Improvements

  Possible improvements