nsICookieManager2

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

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

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.

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

• nsICookie
• nsICookie2
• nsICookieManager
• nsICookiePermission