1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
interface nsIURI;
interface nsIPrompt;
interface nsIChannel;
/**
* nsICookieService
*
* Provides methods for setting and getting cookies in the context of a
* page load. See nsICookieManager for methods to manipulate the cookie
* database directly. This separation of interface is mainly historical.
*
* This service broadcasts the notifications detailed below when the cookie
* list is changed, or a cookie is rejected.
*
* NOTE: observers of these notifications *must* not attempt to change profile
* or switch into or out of private browsing mode from within the
* observer. Doing so will cause undefined behavior. Mutating the cookie
* list (e.g. by calling methods on nsICookieService and friends) is
* allowed, but beware that there may be pending notifications you haven't
* seen yet -- for instance, a "batch-deleted" notification will likely be
* immediately followed by "added". You may check the state of the cookie
* list to determine if this is the case.
*
* topic : "cookie-changed"
* broadcast whenever the cookie list changes in some way. see
* explanation of data strings below.
* subject: see below.
* data : "deleted"
* a cookie was deleted. the subject is an nsICookie2 representing
* the deleted cookie.
* "added"
* a cookie was added. the subject is an nsICookie2 representing
* the added cookie.
* "changed"
* a cookie was changed. the subject is an nsICookie2 representing
* the new cookie. (note that host, path, and name are invariant
* for a given cookie; other parameters may change.)
* "batch-deleted"
* a set of cookies was purged (typically, because they have either
* expired or because the cookie list has grown too large). The subject
* is an nsIArray of nsICookie2's representing the deleted cookies.
* Note that the array could contain a single cookie.
* "cleared"
* the entire cookie list was cleared. the subject is null.
*
* topic : "cookie-rejected"
* broadcast whenever a cookie was rejected from being set as a
* result of user prefs.
* subject: an nsIURI interface pointer representing the URI that attempted
* to set the cookie.
* data : none.
*
* topic : "third-party-cookie-accepted"
* broadcast whenever a third party cookie was accepted
* subject: an nsIURI interface pointer representing the URI that attempted
* to set the cookie.
* data : the referrer, or "?" if unknown
*
* topic : "third-party-cookie-rejected"
* broadcast whenever a third party cookie was rejected
* subject: an nsIURI interface pointer representing the URI that attempted
* to set the cookie.
* data : the referrer, or "?" if unknown
*/
[scriptable, uuid(1e94e283-2811-4f43-b947-d22b1549d824)]
interface nsICookieService : nsISupports
{
/*
* Possible values for the "network.cookie.cookieBehavior" preference.
*/
const uint32_t BEHAVIOR_ACCEPT = 0; // allow all cookies
const uint32_t BEHAVIOR_REJECT_FOREIGN = 1; // reject all third-party cookies
const uint32_t BEHAVIOR_REJECT = 2; // reject all cookies
const uint32_t BEHAVIOR_LIMIT_FOREIGN = 3; // reject third-party cookies unless the
// eTLD already has at least one cookie
/*
* Possible values for the "network.cookie.lifetimePolicy" preference.
*/
const uint32_t ACCEPT_NORMALLY = 0; // accept normally
// Value = 1 is considered the same as 0 (See Bug 606655).
const uint32_t ACCEPT_SESSION = 2; // downgrade to session
const uint32_t ACCEPT_FOR_N_DAYS = 3; // limit lifetime to N days
/*
* Get the complete cookie string associated with the URI.
*
* @param aURI
* The URI of the document for which cookies are being queried.
* file:// URIs (i.e. with an empty host) are allowed, but any other
* scheme must have a non-empty host. A trailing dot in the host
* is acceptable, and will be stripped. This argument must not be null.
* @param aChannel
* the channel used to load the document. this parameter should not
* be null, otherwise the cookies will not be returned if third-party
* cookies have been disabled by the user. (the channel is used
* to determine the originating URI of the document; if it is not
* provided, the cookies will be assumed third-party.)
*
* @return the resulting cookie string
*/
string getCookieString(in nsIURI aURI, in nsIChannel aChannel);
/*
* Get the complete cookie string associated with the URI.
*
* This function is NOT redundant with getCookieString, as the result
* will be different based on httponly (see bug 178993)
*
* @param aURI
* The URI of the document for which cookies are being queried.
* file:// URIs (i.e. with an empty host) are allowed, but any other
* scheme must have a non-empty host. A trailing dot in the host
* is acceptable, and will be stripped. This argument must not be null.
* @param aFirstURI
* the URI that the user originally typed in or clicked on to initiate
* the load of the document referenced by aURI.
* @param aChannel
* the channel used to load the document. this parameter should not
* be null, otherwise the cookies will not be returned if third-party
* cookies have been disabled by the user. (the channel is used
* to determine the originating URI of the document; if it is not
* provided, the cookies will be assumed third-party.)
*
* @return the resulting cookie string
*/
string getCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIChannel aChannel);
/*
* Set the cookie string associated with the URI.
*
* @param aURI
* The URI of the document for which cookies are being queried.
* file:// URIs (i.e. with an empty host) are allowed, but any other
* scheme must have a non-empty host. A trailing dot in the host
* is acceptable, and will be stripped. This argument must not be null.
* @param aPrompt
* the prompt to use for all user-level cookie notifications. This is
* presently ignored and can be null. (Prompt information is determined
* from the channel if necessary.)
* @param aCookie
* the cookie string to set.
* @param aChannel
* the channel used to load the document. this parameter should not
* be null, otherwise the cookies will not be set if third-party
* cookies have been disabled by the user. (the channel is used
* to determine the originating URI of the document; if it is not
* provided, the cookies will be assumed third-party.)
*/
void setCookieString(in nsIURI aURI, in nsIPrompt aPrompt, in string aCookie, in nsIChannel aChannel);
/*
* Set the cookie string and expires associated with the URI.
*
* This function is NOT redundant with setCookieString, as the result
* will be different based on httponly (see bug 178993)
*
* @param aURI
* The URI of the document for which cookies are being queried.
* file:// URIs (i.e. with an empty host) are allowed, but any other
* scheme must have a non-empty host. A trailing dot in the host
* is acceptable, and will be stripped. This argument must not be null.
* @param aFirstURI
* the URI that the user originally typed in or clicked on to initiate
* the load of the document referenced by aURI.
* @param aPrompt
* the prompt to use for all user-level cookie notifications. This is
* presently ignored and can be null. (Prompt information is determined
* from the channel if necessary.)
* @param aCookie
* the cookie string to set.
* @param aServerTime
* the current time reported by the server, if available. This should
* be the string from the Date header in an HTTP response. If the
* string is empty or null, server time is assumed to be the current
* local time. If provided, it will be used to calculate the expiry
* time of the cookie relative to the server's local time.
* @param aChannel
* the channel used to load the document. this parameter should not
* be null, otherwise the cookies will not be set if third-party
* cookies have been disabled by the user. (the channel is used
* to determine the originating URI of the document; if it is not
* provided, the cookies will be assumed third-party.)
*/
void setCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIPrompt aPrompt, in string aCookie, in string aServerTime, in nsIChannel aChannel);
};
|
