nsICookieManager.idl (13178B)
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 #include "nsICookie.idl" 8 #include "nsIThirdPartyCookieBlockingExceptionListService.idl" 9 #include "nsIURI.idl" 10 11 %{ C++ 12 #include <functional> 13 namespace mozilla { 14 class OriginAttributes; 15 namespace net { 16 class CookieStruct; 17 } // namespace net 18 } // mozilla namespace 19 %} 20 21 [ptr] native OriginAttributesPtr(mozilla::OriginAttributes); 22 23 interface nsICookieValidation; 24 25 /** 26 * An optional interface for accessing or removing the cookies 27 * that are in the cookie list 28 */ 29 30 [scriptable, builtinclass, uuid(AAAB6710-0F2C-11d5-A53B-0010A401EB10)] 31 interface nsICookieManager : nsISupports 32 { 33 34 /** 35 * Called to remove all cookies from the cookie list 36 */ 37 void removeAll(); 38 39 /** 40 * Returns an array of cookies in the cookie list. 41 * The objects in the array are of type nsICookie 42 * This array only contains non-private browsing cookies. 43 * To retrieve an array of private browsing cookies, use 44 * getCookiesWithOriginAttributes. 45 */ 46 readonly attribute Array<nsICookie> cookies; 47 48 /** 49 * Returns an array of session cookies in the cookie list. 50 * The objects in the array are of type nsICookie 51 * This array only contains non-private browsing cookies. 52 */ 53 readonly attribute Array<nsICookie> sessionCookies; 54 55 /** 56 * Returns current effective value of the cookieBehavior. It will return the 57 * different pref according to the aIsPrivate. If aIsPrivate is true, it will 58 * return the pref "network.cookie.cookieBehavior". Otherwise, it will return 59 * the pref "network.cookie.cookieBehavior.pbmode" 60 */ 61 uint32_t getCookieBehavior(in boolean aIsPrivate); 62 %{C++ 63 static uint32_t GetCookieBehavior(bool aIsPrivate); 64 %} 65 66 /** 67 * Called to remove an individual cookie from the cookie list, specified 68 * by host, name, and path. If the cookie cannot be found, no exception 69 * is thrown. Typically, the arguments to this method will be obtained 70 * directly from the desired nsICookie object. 71 * 72 * @param aHost The host or domain for which the cookie was set. @see 73 * nsICookieManager::add for a description of acceptable host 74 * strings. If the target cookie is a domain cookie, a leading 75 * dot must be present. 76 * @param aName The name specified in the cookie 77 * @param aPath The path for which the cookie was set 78 * @param aOriginAttributes The originAttributes of this cookie. 79 * 80 */ 81 [implicit_jscontext] 82 void remove(in AUTF8String aHost, 83 in ACString aName, 84 in AUTF8String aPath, 85 in jsval aOriginAttributes); 86 87 [notxpcom] 88 nsresult removeNative(in AUTF8String aHost, 89 in ACString aName, 90 in AUTF8String aPath, 91 in OriginAttributesPtr aOriginAttributes, 92 in boolean aFromHttp, 93 in nsIDPtr aOperationID); 94 95 /** 96 * Add a cookie. nsICookieService is the normal way to do this. This 97 * method is something of a backdoor. 98 * 99 * @param aHost 100 * the host or domain for which the cookie is set. presence of a 101 * leading dot indicates a domain cookie; otherwise, the cookie 102 * is treated as a non-domain cookie (see RFC2109). The host string 103 * will be normalized to ASCII or ACE; any trailing dot will be 104 * stripped. To be a domain cookie, the host must have at least two 105 * subdomain parts (e.g. '.foo.com', not '.com'), otherwise an 106 * exception will be thrown. An empty string is acceptable 107 * (e.g. file:// URI's). 108 * @param aPath 109 * path within the domain for which the cookie is valid 110 * @param aName 111 * cookie name 112 * @param aValue 113 * cookie data 114 * @param aIsSecure 115 * true if the cookie should only be sent over a secure connection. 116 * @param aIsHttpOnly 117 * true if the cookie should only be sent to, and can only be 118 * modified by, an http connection. 119 * @param aIsSession 120 * true if the cookie should exist for the current session only. 121 * see aExpiry. 122 * @param aExpiry 123 * expiration date, in mseconds since midnight (00:00:00), January 1, 124 * 1970 UTC. note that expiry time will also be honored for session cookies; 125 * in this way, the more restrictive of the two will take effect. 126 * @param aOriginAttributes 127 * the originAttributes of this cookie. 128 * @param aSameSite 129 * the SameSite attribute. 130 * @param aSchemeMap 131 * the schemes this cookie has been set on. See nsICookie.idl. 132 * @param aIsPartitioned 133 * true if the cookie should be stored with the Partitioned attribute. 134 */ 135 [implicit_jscontext] 136 nsICookieValidation add(in AUTF8String aHost, 137 in AUTF8String aPath, 138 in ACString aName, 139 in AUTF8String aValue, 140 in boolean aIsSecure, 141 in boolean aIsHttpOnly, 142 in boolean aIsSession, 143 in int64_t aExpiry, 144 in jsval aOriginAttributes, 145 in int32_t aSameSite, 146 in nsICookie_schemeType aSchemeMap, 147 [optional] in boolean aIsPartitioned); 148 149 /** 150 * This method is the non-xpcom version of add(). In case of an invalid 151 * cookie, it returns a nsICookieValidation object and NS_ERROR_ILLEGAL_VALUE 152 * as error code. 153 */ 154 [notxpcom] 155 nsresult addNative(in nsIURI aCookieURI, 156 in AUTF8String aHost, 157 in AUTF8String aPath, 158 in ACString aName, 159 in AUTF8String aValue, 160 in boolean aIsSecure, 161 in boolean aIsHttpOnly, 162 in boolean aIsSession, 163 in int64_t aExpiry, 164 in OriginAttributesPtr aOriginAttributes, 165 in int32_t aSameSite, 166 in nsICookie_schemeType aSchemeMap, 167 in boolean aIsPartitioned, 168 in boolean aFromHttp, 169 in nsIDPtr aOperationID, 170 out nsICookieValidation aValidation); 171 172 /** 173 * Find whether a given cookie already exists. 174 * 175 * @param aHost 176 * the cookie's host to look for 177 * @param aPath 178 * the cookie's path to look for 179 * @param aName 180 * the cookie's name to look for 181 * @param aOriginAttributes 182 * the cookie's originAttributes to look for 183 * 184 * @return true if a cookie was found which matches the host, path, name and 185 * originAttributes fields of aCookie 186 */ 187 [implicit_jscontext] 188 boolean cookieExists(in AUTF8String aHost, 189 in AUTF8String aPath, 190 in ACString aName, 191 in jsval aOriginAttributes); 192 193 [notxpcom] 194 nsresult cookieExistsNative(in AUTF8String aHost, 195 in AUTF8String aPath, 196 in ACString aName, 197 in OriginAttributesPtr aOriginAttributes, 198 out boolean aExists); 199 200 /** 201 * Get a specific cookie by host, path, name and OriginAttributes. 202 * 203 * @param aHost 204 * the cookie's host to look for 205 * @param aPath 206 * the cookie's path to look for 207 * @param aName 208 * the cookie's name to look for 209 * @param aOriginAttributes 210 * the cookie's originAttributes to look for 211 * 212 * @return cookie matching the arguments or nullptr if not existing. 213 */ 214 [notxpcom] 215 nsresult getCookieNative(in AUTF8String aHost, 216 in AUTF8String aPath, 217 in ACString aName, 218 in OriginAttributesPtr aOriginAttributes, 219 out nsICookie aCookie); 220 221 /** 222 * Count how many cookies exist within the base domain of 'aHost'. 223 * Thus, for a host "weather.yahoo.com", the base domain would be "yahoo.com", 224 * and any host or domain cookies for "yahoo.com" and its subdomains would be 225 * counted. 226 * 227 * @param aHost 228 * the host string to search for, e.g. "google.com". this should consist 229 * of only the host portion of a URI. see @add for a description of 230 * acceptable host strings. 231 * 232 * @return the number of cookies found. 233 */ 234 unsigned long countCookiesFromHost(in AUTF8String aHost); 235 236 /** 237 * Returns an array of cookies that exist within the base domain of 238 * 'aHost'. Thus, for a host "weather.yahoo.com", the base domain would be 239 * "yahoo.com", and any host or domain cookies for "yahoo.com" and its 240 * subdomains would be returned. 241 * 242 * @param aHost 243 * the host string to search for, e.g. "google.com". this should consist 244 * of only the host portion of a URI. see @add for a description of 245 * acceptable host strings. 246 * @param aOriginAttributes The originAttributes of cookies that would be 247 * retrived. 248 * @param aSorted (optional) if true the cookies will be sorted by creation 249 * time and path length as described in RFC 6265 250 * 251 * @return an array of nsICookie objects. 252 * 253 * @see countCookiesFromHost 254 */ 255 [implicit_jscontext] 256 Array<nsICookie> getCookiesFromHost(in AUTF8String aHost, 257 in jsval aOriginAttributes, 258 [optional] in boolean aSorted); 259 260 [notxpcom] 261 nsresult getCookiesFromHostNative(in AUTF8String aHost, 262 in OriginAttributesPtr aOriginAttributes, 263 in boolean aSorted, 264 out Array<nsICookie> aCookies); 265 266 /** 267 * Returns an array of all cookies whose origin attributes matches aPattern 268 * 269 * @param aPattern origin attribute pattern in JSON format 270 * 271 * @param aHost 272 * the host string to search for, e.g. "google.com". this should consist 273 * of only the host portion of a URI. see @add for a description of 274 * acceptable host strings. This attribute is optional. It will search 275 * all hosts if this attribute is not given. 276 * @param aSorted (optional) if true the cookies will be sorted by creation 277 * time and path length as described in RFC 6265 278 */ 279 Array<nsICookie> getCookiesWithOriginAttributes(in AString aPattern, 280 [optional] in AUTF8String aHost, 281 [optional] in boolean aSorted); 282 283 /** 284 * Remove all the cookies whose origin attributes matches aPattern 285 * 286 * @param aPattern origin attribute pattern in JSON format 287 */ 288 void removeCookiesWithOriginAttributes(in AString aPattern, 289 [optional] in AUTF8String aHost); 290 291 /** 292 * Remove all the cookies whose origin attributes matches aPattern and the 293 * host is exactly aHost (without subdomain matching). 294 * 295 * @param aHost the host to match 296 * @param aPattern origin attribute pattern in JSON format 297 */ 298 void removeCookiesFromExactHost(in AUTF8String aHost, in AString aPattern); 299 300 /** 301 * Removes all cookies that were created on or after aSinceWhen, and returns 302 * a Promise which will be resolved when the last such cookie has been 303 * removed. 304 * 305 * @param aSinceWhen the starting point in time after which no cookies should 306 * be created when the Promise returned from this method is resolved. 307 */ 308 [implicit_jscontext] 309 Promise removeAllSince(in int64_t aSinceWhen); 310 311 /** 312 * Retrieves all the cookies that were created on or after aSinceWhen, order 313 * by creation time */ 314 Array<nsICookie> getCookiesSince(in int64_t aSinceWhen); 315 316 317 /** 318 * Adds a list of exceptions to the third party cookie blocking exception 319 * list. 320 */ 321 void addThirdPartyCookieBlockingExceptions( 322 in Array<nsIThirdPartyCookieExceptionEntry> aExcpetions); 323 324 /** 325 * Removes a list of exceptions from the third party cookie blocking 326 * exception list. 327 */ 328 void removeThirdPartyCookieBlockingExceptions( 329 in Array<nsIThirdPartyCookieExceptionEntry> aExceptions); 330 331 // Test getter to inspect remote exception list state. 332 Array<ACString> testGet3PCBExceptions(); 333 334 /** 335 * Helper to cap an expiry time using the network.cookie.maxageCap pref. 336 * 337 * @param aExpiry expiry time in milliseconds since the UNIX epoch. 338 * @return the minimum between aExpiry and the current time plus 339 * StaticPrefs::network_cookie_maxageCap() seconds. 340 */ 341 int64_t maybeCapExpiry(in int64_t aExpiryInMSec); 342 };