netwerk/cookie/nsICookieManager.idl

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