nsICookieService.idl (7490B)
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/. */ 5 6 #include "nsISupports.idl" 7 8 interface nsIChannel; 9 interface nsICookie; 10 interface nsIURI; 11 webidl Document; 12 13 %{C++ 14 namespace mozilla { 15 class OriginAttributes; 16 17 namespace net { 18 class Cookie; 19 class CookieParser; 20 } 21 } 22 %} 23 24 [ref] native const_OriginAttributes(const mozilla::OriginAttributes); 25 native CookieRefPtr(RefPtr<mozilla::net::Cookie>); 26 [ref] native CookiePtr(mozilla::net::Cookie); 27 [ref] native CookieParserPtr(mozilla::net::CookieParser); 28 29 /** 30 * @see nsICookieService::runInTransaction 31 */ 32 [scriptable, function, uuid(0fc41ffb-f1b7-42d9-9a42-8dc420c158c1)] 33 interface nsICookieTransactionCallback : nsISupports 34 { 35 void callback(); 36 }; 37 38 /** 39 * nsICookieService 40 * 41 * Provides methods for setting and getting cookies in the context of a 42 * page load. See nsICookieManager for methods to manipulate the cookie 43 * database directly. This separation of interface is mainly historical. 44 * 45 * This service broadcasts the notifications detailed below when the cookie 46 * list is changed, or a cookie is rejected. 47 * 48 * NOTE: observers of these notifications *must* not attempt to change profile 49 * or switch into or out of private browsing mode from within the 50 * observer. Doing so will cause undefined behavior. Mutating the cookie 51 * list (e.g. by calling methods on nsICookieService and friends) is 52 * allowed, but beware that there may be pending notifications you haven't 53 * seen yet -- for instance, a COOKIES_BATCH_DELETED notification will likely be 54 * immediately followed by COOKIE_ADDED. You may check the state of the cookie 55 * list to determine if this is the case. 56 * 57 * topic : "cookie-changed" 58 * broadcast whenever the cookie list changes in some way. see 59 * explanation of data strings below. 60 * subject: The cookie notification. See nsICookieNotification for details. 61 * data : none. For possible actions see nsICookieNotification_Action. 62 * 63 * topic : "cookie-rejected" 64 * broadcast whenever a cookie was rejected from being set as a 65 * result of user prefs. 66 * subject: an nsIURI interface pointer representing the URI that attempted 67 * to set the cookie. 68 * data : none. 69 */ 70 [builtinclass, scriptable, uuid(1e94e283-2811-4f43-b947-d22b1549d824)] 71 interface nsICookieService : nsISupports 72 { 73 /* 74 * Possible values for the "network.cookie.cookieBehavior" preference. 75 */ 76 const uint32_t BEHAVIOR_ACCEPT = 0; // allow all cookies 77 const uint32_t BEHAVIOR_REJECT_FOREIGN = 1; // reject all third-party cookies 78 const uint32_t BEHAVIOR_REJECT = 2; // reject all cookies 79 const uint32_t BEHAVIOR_LIMIT_FOREIGN = 3; // reject third-party cookies unless the 80 // eTLD already has at least one cookie 81 const uint32_t BEHAVIOR_REJECT_TRACKER = 4; // reject trackers 82 const uint32_t BEHAVIOR_REJECT_TRACKER_AND_PARTITION_FOREIGN = 5; // reject trackers, partition third-party cookies 83 // When adding a new cookie behavior, please increase this value! 84 const uint32_t BEHAVIOR_LAST = 5; 85 86 /* 87 * Get the list of cookies associated with a base domain and an OriginAttributes. 88 * This method is meant to be used for `document.cookie` only. Any security 89 * check about storage-access permission and cookie behavior must be done by 90 * the caller. 91 */ 92 [noscript, notxpcom, nostdcall] void getCookiesFromHost(in ACString aBaseDomain, 93 in const_OriginAttributes aOriginAttributes, 94 out Array<CookieRefPtr> aCookies); 95 96 /* Update the last access to stale cookies */ 97 [noscript, notxpcom, nostdcall] void staleCookies(in Array<CookieRefPtr> aCookies, 98 in int64_t aCurrentTimeInUsec); 99 100 /* Return true if there are existing cookies for the host and OriginAttributes. */ 101 [noscript, notxpcom, nostdcall] boolean hasExistingCookies(in ACString aBaseDomain, 102 in const_OriginAttributes aOriginAttributes); 103 104 /* Return true if there are existing cookies for the host and OriginAttributes. */ 105 [noscript, notxpcom, nostdcall] void addCookieFromDocument(in CookieParserPtr aCookieParser, 106 in ACString aBaseDomain, 107 in const_OriginAttributes aOriginAttributes, 108 in CookiePtr aCookie, 109 in int64_t aCurrentTimeInUsec, 110 in nsIURI aDocumentURI, 111 in boolean aThirdParty, 112 in Document document); 113 114 /* 115 * Get the complete cookie string associated with the URI. 116 * 117 * This function is NOT redundant with getCookieString, as the result 118 * will be different based on httponly (see bug 178993) 119 * 120 * @param aURI 121 * The URI of the document for which cookies are being queried. 122 * file:// URIs (i.e. with an empty host) are allowed, but any other 123 * scheme must have a non-empty host. A trailing dot in the host 124 * is acceptable, and will be stripped. This argument must not be null. 125 * @param aChannel 126 * the channel used to load the document. 127 * 128 * @return the resulting cookie string 129 */ 130 ACString getCookieStringFromHttp(in nsIURI aURI, in nsIChannel aChannel); 131 132 /* 133 * Set the cookie string and expires associated with the URI. 134 * 135 * This function is NOT redundant with setCookieString, as the result 136 * will be different based on httponly (see bug 178993) 137 * 138 * @param aURI 139 * The URI of the document for which cookies are being queried. 140 * file:// URIs (i.e. with an empty host) are allowed, but any other 141 * scheme must have a non-empty host. A trailing dot in the host 142 * is acceptable, and will be stripped. This argument must not be null. 143 * @param aCookie 144 * the cookie string to set. 145 * @param aChannel 146 * the channel used to load the document. 147 */ 148 void setCookieStringFromHttp(in nsIURI aURI, in ACString aCookie, 149 in nsIChannel aChannel); 150 151 /* 152 * Batch SQLite operations into one transaction. By default each call to 153 * CookieService that affects the underlying SQLite database (add, remove, 154 * setCookieString etc.) runs in a separate transaction. If you do this many 155 * times in a row, it's faster and suggested to wrap them all in a single 156 * transaction by setting all the operations into the callback parameter. 157 * Example: test scripts that need to construct a large cookie database. 158 * @param aCallback 159 * nsICookieTransactionCallback interface to call 160 * @throws NS_ERROR_FAILURE if aCallback() fails. 161 * @throws NS_ERROR_NOT_AVAILABLE if the connection is not established. 162 */ 163 void runInTransaction(in nsICookieTransactionCallback aCallback); 164 };