nsICookieManager2

The nsICookieManager2 interface contains additional methods that expand upon the nsICookieManager interface.

Please add a summary to this article.
Last changed in Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

Inherits from: nsICookieManager

This interface is included in The Services.jsm JavaScript code module. To create an object implementing this interface:

Components.utils.import("resource://gre/modules/Services.jsm");
var cookieService = Services.cookies;

Method overview

void add(in AUTF8String aHost, in AUTF8String aPath, in ACString aName, in ACString aValue, in boolean aIsSecure, in boolean aIsHttpOnly, in boolean aIsSession, in PRInt64 aExpiry);
boolean cookieExists(in nsICookie2 aCookie);
unsigned long countCookiesFromHost(in AUTF8String aHost);
boolean findMatchingCookie(in nsICookie2 aCookie, out unsigned long aCountFromHost); Obsolete since Gecko 1.9
nsISimpleEnumerator getCookiesFromHost(in AUTF8String aHost);
void importCookies(in nsIFile aCookieFile);

Methods

add()

Adds a cookie. nsICookieService is the normal way to do this. This method is something of a back door.

void add(
  in AUTF8String aHost,
  in AUTF8String aPath,
  in ACString aName,
  in ACString aValue,
  in boolean aIsSecure,
  in boolean aIsHttpOnly,
  in boolean aIsSession,
  in PRInt64 aExpiry
);
Parameters
aHost
The host or domain for which the cookie is set. presence of a leading dot indicates a domain cookie; otherwise, the cookie is treated as a non-domain cookie. See RFC2109 for details. The host string will be normalized to ASCII or ACE; any trailing dot will be stripped. To be a domain cookie, the host must have at least two subdomain parts (e.g. '.foo.com', not '.com'), otherwise an exception will be thrown. An empty string is acceptable (e.g. file:// URI's).
aPath
The path within the domain for which the cookie is valid.
aName
The cookie name.
aValue
The cookie data.
aIsSecure
true if the cookie should only be sent over a secure connection.
aIsHttpOnly
true if the cookie should only be sent to, and can only be modified by, an HTTP connection.
aIsSession
true if the cookie should exist for the current session only.
aExpiry
Holds the expiration date, in seconds since the epoch. Only relevant if aIsSession is false.

cookieExists()

Returns whether or not a matching cookie already exists.

boolean cookieExists(
  in nsICookie2 aCookie
);
Parameters
aCookie
The cookie to look for.
Return value

Returns true if a cookie was found which matches the host, path, and name fields of aCookie.

countCookiesFromHost()

Returns the number of cookies that would be returned to a given host.

This ignores the cookie flags isDomain, isSecure, and isHttpOnly. Therefore, if the specified host is "weather.yahoo.com", host or domain cookies for "weather.yahoo.com" and "yahoo.com" would both be counted, while a cookie for "my.weather.yahoo.com" would not.

unsigned long countCookiesFromHost(
  in AUTF8String aHost
);
Parameters
aHost
The host string to look for, such as "google.com". This should consist only of the host portion of the URI and should not contain a leading dot, port number, or other information.
Return value

The number of matching cookies found.

findMatchingCookie()

Obsolete since Gecko 1.9 (Firefox 3)

Find whether a matching cookie already exists, and how many cookies a given host has already set. This is useful when e.g. prompting the user whether to accept a given cookie.

boolean findMatchingCookie(
  in nsICookie2 aCookie,
  out unsigned long aCountFromHost
);
Parameters
aCookie
The cookie to look for.
aCountFromHost
The number of cookies found whose hosts are the same as, or subdomains of, the host field of aCookie.
Return value

true if a cookie was found which matches the host, path, and name fields of aCookie.

getCookiesFromHost()

Returns an enumerator of cookies that would be returned to a given host, ignoring the cookie flags isDomain, isSecure, and isHttpOnly. Therefore, if the specified host is "weather.yahoo.com", host or domain cookies for "weather.yahoo.com" and "yahoo.com" would both be returned, while a cookie for "my.weather.yahoo.com" would not.

nsISimpleEnumerator getCookiesFromHost(
  in AUTF8String aHost
);
Parameters
aHost
The host string to look for, such as "google.com". This should consist only of the host portion of the URI and should not contain a leading dot, port number, or other information.
Return value

An nsISimpleEnumerator of nsICookie2 objects representing the matching cookies.

importCookies()

Imports an old-style cookie file. The imported cookies will be added to the existing cookie database. If the database contains any cookies that are the same as those being imported (that is, they have the same domain, name, and path), they are replaced with the ones being imported.

void importCookies(
  in nsIFile aCookieFile
);
Parameters
aCookieFile
The file to import. This is usually cookies.txt.

See also