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
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
isfalse
.
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
.