netwerk/cookie/public/nsICookieManager2.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 2003
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsICookieManager.idl"
  39
  40 interface nsICookie2;
  41 interface nsIFile;
  42
  43 /**
  44  * Additions to the frozen nsICookieManager
  45  */
  46
  47 [scriptable, uuid(5047cab4-9cb2-4927-a4ab-77422bc3bc67)]
  48 interface nsICookieManager2 : nsICookieManager
  49 {
  50   /**
  51    * Add a cookie. nsICookieService is the normal way to do this. This
  52    * method is something of a backdoor.
  53    *
  54    * @param aDomain
  55    *        the host or domain for which the cookie is set. presence of a
  56    *        leading dot indicates a domain cookie; otherwise, the cookie
  57    *        is treated as a non-domain cookie. see RFC2109.
  58    * @param aPath
  59    *        path within the domain for which the cookie is valid
  60    * @param aName
  61    *        cookie name
  62    * @param aValue
  63    *        cookie data
  64    * @param aIsSecure
  65    *        true if the cookie should only be sent over a secure connection.
  66    * @param aIsHttpOnly
  67    *        true if the cookie should only be sent to, and can only be
  68    *        modified by, an http connection.
  69    * @param aIsSession
  70    *        true if the cookie should exist for the current session only.
  71    *        see aExpiry.
  72    * @param aExpiry
  73    *        expiration date, in seconds since midnight (00:00:00), January 1,
  74    *        1970 UTC. note that expiry time will also be honored for session cookies;
  75    *        in this way, the more restrictive of the two will take effect.
  76    */
  77   void add(in AUTF8String aDomain,
  78            in AUTF8String aPath,
  79            in ACString    aName,
  80            in ACString    aValue,
  81            in boolean     aIsSecure,
  82            in boolean     aIsHttpOnly,
  83            in boolean     aIsSession,
  84            in PRInt64     aExpiry);
  85
  86   /**
  87    * Find whether a given cookie already exists.
  88    *
  89    * @param aCookie
  90    *        the cookie to look for
  91    *
  92    * @return true if a cookie was found which matches the host, path, and name
  93    *         fields of aCookie
  94    */
  95   boolean cookieExists(in nsICookie2 aCookie);
  96
  97   /**
  98    * Count how many cookies would be returned to a given host, ignoring the
  99    * cookie flags isDomain, isSecure, and isHttpOnly. Thus, for a host
 100    * "weather.yahoo.com", host or domain cookies for "weather.yahoo.com" and
 101    * "yahoo.com" would be counted, while a cookie for "my.weather.yahoo.com"
 102    * would not.
 103    *
 104    * @param aHost
 105    *        the host string to look for, e.g. "google.com". this should consist
 106    *        of only the host portion of a URI, and should not contain a leading
 107    *        dot, a port, etc.
 108    *
 109    * @return the number of cookies found.
 110    */
 111   unsigned long countCookiesFromHost(in ACString aHost);
 112
 113   /**
 114    * Import an old-style cookie file. Imported cookies will be added to the
 115    * existing database. If the database contains any cookies the same as those
 116    * being imported (i.e. domain, name, and path match), they will be replaced.
 117    *
 118    * @param aCookieFile the file to import, usually cookies.txt
 119    */
 120   void importCookies(in nsIFile aCookieFile);
 121 };