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