DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (3cc34f31408f)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

%{ C++
namespace mozilla {
class OriginAttributes;
} // mozilla namespace
%}

[ptr] native OriginAttributesPtr(mozilla::OriginAttributes);

interface nsISimpleEnumerator;
interface nsICookie;
interface nsIFile;

/**
 * An optional interface for accessing or removing the cookies
 * that are in the cookie list
 */

[scriptable, builtinclass, uuid(AAAB6710-0F2C-11d5-A53B-0010A401EB10)]
interface nsICookieManager : nsISupports
{

  /**
   * Called to remove all cookies from the cookie list
   */
  void removeAll();

  /**
   * Called to enumerate through each cookie in the cookie list.
   * The objects enumerated over are of type nsICookie
   * This enumerator should only be used for non-private browsing cookies.
   * To retrieve an enumerator for private browsing cookies, use
   * getCookiesWithOriginAttributes.
   */
  readonly attribute nsISimpleEnumerator enumerator;

  /**
   * Called to enumerate through each session cookie in the cookie list.
   * The objects enumerated over are of type nsICookie
   * This enumerator should only be used for non-private browsing cookies.
   */
  readonly attribute nsISimpleEnumerator sessionEnumerator;

  /**
   * Called to remove an individual cookie from the cookie list, specified
   * by host, name, and path. If the cookie cannot be found, no exception
   * is thrown. Typically, the arguments to this method will be obtained
   * directly from the desired nsICookie object.
   *
   * @param aHost The host or domain for which the cookie was set. @see
   *              nsICookieManager::add for a description of acceptable host
   *              strings. If the target cookie is a domain cookie, a leading
   *              dot must be present.
   * @param aName The name specified in the cookie
   * @param aPath The path for which the cookie was set
   * @param aOriginAttributes The originAttributes of this cookie.
   *
   */
  [implicit_jscontext]
  void remove(in AUTF8String   aHost,
              in ACString      aName,
              in AUTF8String   aPath,
              in jsval         aOriginAttributes);

  [notxpcom]
  nsresult removeNative(in AUTF8String   aHost,
                        in ACString      aName,
                        in AUTF8String   aPath,
                        in OriginAttributesPtr aOriginAttributes);

  /**
   * Add a cookie. nsICookieService is the normal way to do this. This
   * method is something of a backdoor.
   *
   * @param aHost
   *        the host or domain for which the cookie is set. presence of a
   *        leading dot indicates a domain cookie; otherwise, the cookie
   *        is treated as a non-domain cookie (see RFC2109). The host string
   *        will be normalized to ASCII or ACE; any trailing dot will be
   *        stripped. To be a domain cookie, the host must have at least two
   *        subdomain parts (e.g. '.foo.com', not '.com'), otherwise an
   *        exception will be thrown. An empty string is acceptable
   *        (e.g. file:// URI's).
   * @param aPath
   *        path within the domain for which the cookie is valid
   * @param aName
   *        cookie name
   * @param aValue
   *        cookie data
   * @param aIsSecure
   *        true if the cookie should only be sent over a secure connection.
   * @param aIsHttpOnly
   *        true if the cookie should only be sent to, and can only be
   *        modified by, an http connection.
   * @param aIsSession
   *        true if the cookie should exist for the current session only.
   *        see aExpiry.
   * @param aExpiry
   *        expiration date, in seconds since midnight (00:00:00), January 1,
   *        1970 UTC. note that expiry time will also be honored for session cookies;
   *        in this way, the more restrictive of the two will take effect.
   * @param aOriginAttributes
   *        the originAttributes of this cookie.
   * @param aSameSite
   *        the SameSite attribute.
   */
  [implicit_jscontext]
  void add(in AUTF8String aHost,
           in AUTF8String aPath,
           in ACString    aName,
           in AUTF8String aValue,
           in boolean     aIsSecure,
           in boolean     aIsHttpOnly,
           in boolean     aIsSession,
           in int64_t     aExpiry,
           in jsval aOriginAttributes,
           in int32_t aSameSite);

  [notxpcom]
  nsresult addNative(in AUTF8String aHost,
                     in AUTF8String aPath,
                     in ACString    aName,
                     in AUTF8String aValue,
                     in boolean     aIsSecure,
                     in boolean     aIsHttpOnly,
                     in boolean     aIsSession,
                     in int64_t     aExpiry,
                     in OriginAttributesPtr aOriginAttributes,
                     in int32_t aSameSite);

  /**
   * Find whether a given cookie already exists.
   *
   * @param aHost
   *        the cookie's host to look for
   * @param aPath
   *        the cookie's path to look for
   * @param aName
   *        the cookie's name to look for
   * @param aOriginAttributes
   *        the cookie's originAttributes to look for
   *
   * @return true if a cookie was found which matches the host, path, name and
   *         originAttributes fields of aCookie
   */
  [implicit_jscontext]
  boolean cookieExists(in AUTF8String aHost,
                       in AUTF8String aPath,
                       in ACString    aName,
                       in jsval aOriginAttributes);

  [notxpcom]
  nsresult cookieExistsNative(in AUTF8String aHost,
                              in AUTF8String aPath,
                              in ACString    aName,
                              in OriginAttributesPtr aOriginAttributes,
                              out boolean aExists);

  /**
   * Count how many cookies exist within the base domain of 'aHost'.
   * Thus, for a host "weather.yahoo.com", the base domain would be "yahoo.com",
   * and any host or domain cookies for "yahoo.com" and its subdomains would be
   * counted.
   *
   * @param aHost
   *        the host string to search for, e.g. "google.com". this should consist
   *        of only the host portion of a URI. see @add for a description of
   *        acceptable host strings.
   *
   * @return the number of cookies found.
   */
  unsigned long countCookiesFromHost(in AUTF8String aHost);

  /**
   * Returns an enumerator of cookies that exist within the base domain of
   * 'aHost'. Thus, for a host "weather.yahoo.com", the base domain would be
   * "yahoo.com", and any host or domain cookies for "yahoo.com" and its
   * subdomains would be returned.
   *
   * @param aHost
   *        the host string to search for, e.g. "google.com". this should consist
   *        of only the host portion of a URI. see @add for a description of
   *        acceptable host strings.
   * @param aOriginAttributes The originAttributes of cookies that would be
   *                          retrived.
   *
   * @return an nsISimpleEnumerator of nsICookie objects.
   *
   * @see countCookiesFromHost
   */
  [implicit_jscontext]
  nsISimpleEnumerator getCookiesFromHost(in AUTF8String aHost,
                                         in jsval aOriginAttributes);

  /**
   * Import an old-style cookie file. Imported cookies will be added to the
   * existing database. If the database contains any cookies the same as those
   * being imported (i.e. domain, name, and path match), they will be replaced.
   *
   * @param aCookieFile the file to import, usually cookies.txt
   */
  void importCookies(in nsIFile aCookieFile);

  /**
   * Returns an enumerator of all cookies whose origin attributes matches aPattern
   *
   * @param aPattern origin attribute pattern in JSON format
   *
   * @param aHost
   *        the host string to search for, e.g. "google.com". this should consist
   *        of only the host portion of a URI. see @add for a description of
   *        acceptable host strings. This attribute is optional. It will search
   *        all hosts if this attribute is not given.
   */
  nsISimpleEnumerator getCookiesWithOriginAttributes(in AString aPattern,
                                                     [optional] in AUTF8String aHost);

  /**
   * Remove all the cookies whose origin attributes matches aPattern
   *
   * @param aPattern origin attribute pattern in JSON format
   */
  void removeCookiesWithOriginAttributes(in AString aPattern,
                                         [optional] in AUTF8String aHost);

  /**
   * Remove all the cookies whose origin attributes matches aPattern and the
   * host is exactly aHost (without subdomain matching).
   *
   * @param aHost the host to match
   * @param aPattern origin attribute pattern in JSON format
   */
  void removeCookiesFromExactHost(in AUTF8String aHost, in AString aPattern);
};