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