1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/cookie/nsICookieManager2.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,132 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsICookieManager.idl"
1.10 +
1.11 +interface nsICookie2;
1.12 +interface nsIFile;
1.13 +
1.14 +/**
1.15 + * Additions to the frozen nsICookieManager
1.16 + */
1.17 +
1.18 +[scriptable, uuid(daf0caa7-b431-4b4d-ba51-08c179bb9dfe)]
1.19 +interface nsICookieManager2 : nsICookieManager
1.20 +{
1.21 + /**
1.22 + * Add a cookie. nsICookieService is the normal way to do this. This
1.23 + * method is something of a backdoor.
1.24 + *
1.25 + * @param aHost
1.26 + * the host or domain for which the cookie is set. presence of a
1.27 + * leading dot indicates a domain cookie; otherwise, the cookie
1.28 + * is treated as a non-domain cookie (see RFC2109). The host string
1.29 + * will be normalized to ASCII or ACE; any trailing dot will be
1.30 + * stripped. To be a domain cookie, the host must have at least two
1.31 + * subdomain parts (e.g. '.foo.com', not '.com'), otherwise an
1.32 + * exception will be thrown. An empty string is acceptable
1.33 + * (e.g. file:// URI's).
1.34 + * @param aPath
1.35 + * path within the domain for which the cookie is valid
1.36 + * @param aName
1.37 + * cookie name
1.38 + * @param aValue
1.39 + * cookie data
1.40 + * @param aIsSecure
1.41 + * true if the cookie should only be sent over a secure connection.
1.42 + * @param aIsHttpOnly
1.43 + * true if the cookie should only be sent to, and can only be
1.44 + * modified by, an http connection.
1.45 + * @param aIsSession
1.46 + * true if the cookie should exist for the current session only.
1.47 + * see aExpiry.
1.48 + * @param aExpiry
1.49 + * expiration date, in seconds since midnight (00:00:00), January 1,
1.50 + * 1970 UTC. note that expiry time will also be honored for session cookies;
1.51 + * in this way, the more restrictive of the two will take effect.
1.52 + */
1.53 + void add(in AUTF8String aHost,
1.54 + in AUTF8String aPath,
1.55 + in ACString aName,
1.56 + in ACString aValue,
1.57 + in boolean aIsSecure,
1.58 + in boolean aIsHttpOnly,
1.59 + in boolean aIsSession,
1.60 + in int64_t aExpiry);
1.61 +
1.62 + /**
1.63 + * Find whether a given cookie already exists.
1.64 + *
1.65 + * @param aCookie
1.66 + * the cookie to look for
1.67 + *
1.68 + * @return true if a cookie was found which matches the host, path, and name
1.69 + * fields of aCookie
1.70 + */
1.71 + boolean cookieExists(in nsICookie2 aCookie);
1.72 +
1.73 + /**
1.74 + * Count how many cookies exist within the base domain of 'aHost'.
1.75 + * Thus, for a host "weather.yahoo.com", the base domain would be "yahoo.com",
1.76 + * and any host or domain cookies for "yahoo.com" and its subdomains would be
1.77 + * counted.
1.78 + *
1.79 + * @param aHost
1.80 + * the host string to search for, e.g. "google.com". this should consist
1.81 + * of only the host portion of a URI. see @add for a description of
1.82 + * acceptable host strings.
1.83 + *
1.84 + * @return the number of cookies found.
1.85 + */
1.86 + unsigned long countCookiesFromHost(in AUTF8String aHost);
1.87 +
1.88 + /**
1.89 + * Returns an enumerator of cookies that exist within the base domain of
1.90 + * 'aHost'. Thus, for a host "weather.yahoo.com", the base domain would be
1.91 + * "yahoo.com", and any host or domain cookies for "yahoo.com" and its
1.92 + * subdomains would be returned.
1.93 + *
1.94 + * @param aHost
1.95 + * the host string to search for, e.g. "google.com". this should consist
1.96 + * of only the host portion of a URI. see @add for a description of
1.97 + * acceptable host strings.
1.98 + *
1.99 + * @return an nsISimpleEnumerator of nsICookie2 objects.
1.100 + *
1.101 + * @see countCookiesFromHost
1.102 + */
1.103 + nsISimpleEnumerator getCookiesFromHost(in AUTF8String aHost);
1.104 +
1.105 + /**
1.106 + * Import an old-style cookie file. Imported cookies will be added to the
1.107 + * existing database. If the database contains any cookies the same as those
1.108 + * being imported (i.e. domain, name, and path match), they will be replaced.
1.109 + *
1.110 + * @param aCookieFile the file to import, usually cookies.txt
1.111 + */
1.112 + void importCookies(in nsIFile aCookieFile);
1.113 +
1.114 + /**
1.115 + * Returns an enumerator of all cookies that are related to a specific app.
1.116 + *
1.117 + * If the onlyBrowserELement parameter is set to true, only cookies part of
1.118 + * a browser element inside the app will be returned. If set to false, all
1.119 + * cookies will be returned, regardless of their browserElement flag.
1.120 + *
1.121 + * This method assumes that appId is a valid app id. It should not be a
1.122 + * special value like UNKNOWN_APP_ID or NO_APP_ID.
1.123 + */
1.124 + nsISimpleEnumerator getCookiesForApp(in unsigned long appId, in boolean onlyBrowserElement);
1.125 +
1.126 + /**
1.127 + * Remove all the cookies associated with the app with the id aAppId.
1.128 + *
1.129 + * If onlyBrowserElement is set to true, the method will only remove the
1.130 + * cookies marked as part of a browser element inside the app.
1.131 + *
1.132 + * Special app id values are not allowed (NO_APP_ID or UNKNOWN_APP_ID for example).
1.133 + */
1.134 + void removeCookiesForApp(in unsigned long appId, in boolean onlyBrowserElement);
1.135 +};
