nsICookieService

Provides methods for setting and getting cookies in the context of a page load.
Inherits from: nsISupports Last changed in Gecko 1.9 (Firefox 3)

See nsICookieManager and nsICookieManager2 for methods to manipulate the cookie database directly. This separation of interface is mainly historical.

var cookieSvc = Components.classes["@mozilla.org/cookieService;1"]
                  .getService(Components.interfaces.nsICookieService);

Notifications

This service broadcasts the following notifications when the cookie list is changed, or a cookie is rejected:

Topic Subject Data

cookie-changed
Broadcast whenever the cookie list changes in some way. There are four possible data strings for this notification; one notification will be broadcast for each change.

 Depending on the Data value, either an nsICookie2 interface pointer representing the cookie object that changed, or an nsIArray of nsICookie2 objects. A keyword indicating what was done to the affected cookie.
deleted
A cookie was deleted. The subject is the deleted cookie.
added
A cookie was added. The subject is the added cookie.
changed
A cookie was changed. The subject is the changed cookie.
batch-deleted
A set of cookies were deleted as part of a purge operation. This typically happens because they have either expired or because the cookie list has grown too large. The subject is an nsIArray of deleted cookies.
cleared
The entire cookie list was cleared. The subject is null.
reload
The entire cookie list was changed, and the observer should reload the list of cookies. The subject is null.
private-cookie-changed
Since Firefox 20 (see bugzilla #837091)		 Same as cookie-changed, except used in lieu of cookie-changed for private windows. See cookie-changed.
cookie-rejected

Broadcast whenever the user's preferences cause a cookie to be rejected from being set.

 An nsIURI interface pointer representing the URI that attempted to set the cookie. None.

Method overview

string getCookieString(in nsIURI aURI, in nsIChannel aChannel);
string getCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIChannel aChannel);
void setCookieString(in nsIURI aURI, in nsIPrompt aPrompt, in string aCookie, in nsIChannel aChannel);
void setCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIPrompt aPrompt, in string aCookie, in string aServerTime, in nsIChannel aChannel);

Attributes

Attribute Type Description
cookieIconIsVisible boolean This attribute really doesn't belong on this interface. CVS blame will tell you why it is here. It remains until we can find a better home for it.

Methods

getCookieString()

Get the complete cookie string associated with the URI.

 string getCookieString(
   in nsIURI aURI, 
   in nsIChannel aChannel
 );
Parameters
aURI
The URI of the document for which cookies are being queried.
aChannel
The channel used to load the document. this parameter may be null, but it is strongly recommended that a non-null value be provided to ensure that the cookie privacy preferences are honored.
Return value

Returns the resulting cookie string.

getCookieStringFromHttp()

Get the complete cookie string associated with the URI.

Note: This function is redundant and will most likely be removed in a future revision of this interface. getCookieString() will query the documentURI property off of nsIHttpChannelInternal if supported, so getCookieString() can be used in place of this method.
 string getCookieStringFromHttp(
   in nsIURI aURI, 
   in nsIURI aFirstURI, 
   in nsIChannel aChannel
 );
Parameters
aURI
The URI of the document for which cookies are being queried.
aFirstURI
The URI that the user originally typed in or clicked on to initiate the load of the document referenced by aURI.
aChannel
The channel used to load the document. this parameter may be null, but it is strongly recommended that a non-null value be provided to ensure that the cookie privacy preferences are honored.
Return value

Returns the resulting cookie string.

setCookieString()

Set the cookie string associated with the URI.

Note: Should be able to allow null aPrompt, since nsIPrompt can be queried from aChannel.

 void setCookieString(
   in nsIURI aURI, 
   in nsIPrompt aPrompt, 
   in string aCookie, 
   in nsIChannel aChannel
 );
Parameters
aURI
The URI of the document for which cookies are being queried.
aPrompt
The prompt to use for all user-level cookie notifications.
aCookie
The cookie string to set.
aChannel
The channel used to load the document. this parameter may be null, but it is strongly recommended that a non-null value be provided to ensure that the cookie privacy preferences are honored.

setCookieStringFromHttp()

Set the cookie string and expires associated with the URI.

Note: This function is redundant and will most likely be removed in a future revision of this interface. setCookieString() will query the documentURI property off of nsIHttpChannelInternal if supported, and setCookieString() could also query the Date header from the channel if aChannel supports nsIHttpChannel.
 void setCookieStringFromHttp(
   in nsIURI aURI, 
   in nsIURI aFirstURI, 
   in nsIPrompt aPrompt, 
   in string aCookie, 
   in string aServerTime, 
   in nsIChannel aChannel
 );
Parameters
aURI
The URI of the document for which cookies are being queried.
aFirstURI
The URI that the user originally typed in or clicked on to initiate the load of the document referenced by aURI.
aPrompt
The prompt to use for all user-level cookie notifications.
aCookie
The cookie string to set.
aServerTime
The expiry information of the cookie (the Date header from the HTTP response).
aChannel
The channel used to load the document. this parameter may be null, but it is strongly recommended that a non-null value be provided to ensure that the cookie privacy preferences are honored.

See also

Document Tags and Contributors

Tags: 
 Contributors to this page: gorhill, Sheppy, YuanXulei, dstaudigel, Dwitte, trevorh, Ehsan, Brettz9, Ayhfung
 Last updated by: gorhill,