1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/cookie/nsICookieService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,178 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
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 "nsISupports.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIPrompt;
1.13 +interface nsIChannel;
1.14 +
1.15 +/**
1.16 + * nsICookieService
1.17 + *
1.18 + * Provides methods for setting and getting cookies in the context of a
1.19 + * page load. See nsICookieManager for methods to manipulate the cookie
1.20 + * database directly. This separation of interface is mainly historical.
1.21 + *
1.22 + * This service broadcasts the notifications detailed below when the cookie
1.23 + * list is changed, or a cookie is rejected.
1.24 + *
1.25 + * NOTE: observers of these notifications *must* not attempt to change profile
1.26 + * or switch into or out of private browsing mode from within the
1.27 + * observer. Doing so will cause undefined behavior. Mutating the cookie
1.28 + * list (e.g. by calling methods on nsICookieService and friends) is
1.29 + * allowed, but beware that there may be pending notifications you haven't
1.30 + * seen yet -- for instance, a "batch-deleted" notification will likely be
1.31 + * immediately followed by "added". You may check the state of the cookie
1.32 + * list to determine if this is the case.
1.33 + *
1.34 + * topic : "cookie-changed"
1.35 + * broadcast whenever the cookie list changes in some way. see
1.36 + * explanation of data strings below.
1.37 + * subject: see below.
1.38 + * data : "deleted"
1.39 + * a cookie was deleted. the subject is an nsICookie2 representing
1.40 + * the deleted cookie.
1.41 + * "added"
1.42 + * a cookie was added. the subject is an nsICookie2 representing
1.43 + * the added cookie.
1.44 + * "changed"
1.45 + * a cookie was changed. the subject is an nsICookie2 representing
1.46 + * the new cookie. (note that host, path, and name are invariant
1.47 + * for a given cookie; other parameters may change.)
1.48 + * "batch-deleted"
1.49 + * a set of cookies was purged (typically, because they have either
1.50 + * expired or because the cookie list has grown too large). The subject
1.51 + * is an nsIArray of nsICookie2's representing the deleted cookies.
1.52 + * Note that the array could contain a single cookie.
1.53 + * "cleared"
1.54 + * the entire cookie list was cleared. the subject is null.
1.55 + * "reload"
1.56 + * the entire cookie list should be reloaded. the subject is null.
1.57 + *
1.58 + * topic : "cookie-rejected"
1.59 + * broadcast whenever a cookie was rejected from being set as a
1.60 + * result of user prefs.
1.61 + * subject: an nsIURI interface pointer representing the URI that attempted
1.62 + * to set the cookie.
1.63 + * data : none.
1.64 + *
1.65 + * topic : "third-party-cookie-accepted"
1.66 + * broadcast whenever a third party cookie was accepted
1.67 + * subject: an nsIURI interface pointer representing the URI that attempted
1.68 + * to set the cookie.
1.69 + * data : the referrer, or "?" if unknown
1.70 + *
1.71 + * topic : "third-party-cookie-rejected"
1.72 + * broadcast whenever a third party cookie was rejected
1.73 + * subject: an nsIURI interface pointer representing the URI that attempted
1.74 + * to set the cookie.
1.75 + * data : the referrer, or "?" if unknown
1.76 + */
1.77 +[scriptable, uuid(2aaa897a-293c-4d2b-a657-8c9b7136996d)]
1.78 +interface nsICookieService : nsISupports
1.79 +{
1.80 + /*
1.81 + * Get the complete cookie string associated with the URI.
1.82 + *
1.83 + * @param aURI
1.84 + * The URI of the document for which cookies are being queried.
1.85 + * file:// URIs (i.e. with an empty host) are allowed, but any other
1.86 + * scheme must have a non-empty host. A trailing dot in the host
1.87 + * is acceptable, and will be stripped. This argument must not be null.
1.88 + * @param aChannel
1.89 + * the channel used to load the document. this parameter should not
1.90 + * be null, otherwise the cookies will not be returned if third-party
1.91 + * cookies have been disabled by the user. (the channel is used
1.92 + * to determine the originating URI of the document; if it is not
1.93 + * provided, the cookies will be assumed third-party.)
1.94 + *
1.95 + * @return the resulting cookie string
1.96 + */
1.97 + string getCookieString(in nsIURI aURI, in nsIChannel aChannel);
1.98 +
1.99 + /*
1.100 + * Get the complete cookie string associated with the URI.
1.101 + *
1.102 + * This function is NOT redundant with getCookieString, as the result
1.103 + * will be different based on httponly (see bug 178993)
1.104 + *
1.105 + * @param aURI
1.106 + * The URI of the document for which cookies are being queried.
1.107 + * file:// URIs (i.e. with an empty host) are allowed, but any other
1.108 + * scheme must have a non-empty host. A trailing dot in the host
1.109 + * is acceptable, and will be stripped. This argument must not be null.
1.110 + * @param aFirstURI
1.111 + * the URI that the user originally typed in or clicked on to initiate
1.112 + * the load of the document referenced by aURI.
1.113 + * @param aChannel
1.114 + * the channel used to load the document. this parameter should not
1.115 + * be null, otherwise the cookies will not be returned if third-party
1.116 + * cookies have been disabled by the user. (the channel is used
1.117 + * to determine the originating URI of the document; if it is not
1.118 + * provided, the cookies will be assumed third-party.)
1.119 + *
1.120 + * @return the resulting cookie string
1.121 + */
1.122 + string getCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIChannel aChannel);
1.123 +
1.124 + /*
1.125 + * Set the cookie string associated with the URI.
1.126 + *
1.127 + * @param aURI
1.128 + * The URI of the document for which cookies are being queried.
1.129 + * file:// URIs (i.e. with an empty host) are allowed, but any other
1.130 + * scheme must have a non-empty host. A trailing dot in the host
1.131 + * is acceptable, and will be stripped. This argument must not be null.
1.132 + * @param aPrompt
1.133 + * the prompt to use for all user-level cookie notifications. This is
1.134 + * presently ignored and can be null. (Prompt information is determined
1.135 + * from the channel if necessary.)
1.136 + * @param aCookie
1.137 + * the cookie string to set.
1.138 + * @param aChannel
1.139 + * the channel used to load the document. this parameter should not
1.140 + * be null, otherwise the cookies will not be set if third-party
1.141 + * cookies have been disabled by the user. (the channel is used
1.142 + * to determine the originating URI of the document; if it is not
1.143 + * provided, the cookies will be assumed third-party.)
1.144 + */
1.145 + void setCookieString(in nsIURI aURI, in nsIPrompt aPrompt, in string aCookie, in nsIChannel aChannel);
1.146 +
1.147 + /*
1.148 + * Set the cookie string and expires associated with the URI.
1.149 + *
1.150 + * This function is NOT redundant with setCookieString, as the result
1.151 + * will be different based on httponly (see bug 178993)
1.152 + *
1.153 + * @param aURI
1.154 + * The URI of the document for which cookies are being queried.
1.155 + * file:// URIs (i.e. with an empty host) are allowed, but any other
1.156 + * scheme must have a non-empty host. A trailing dot in the host
1.157 + * is acceptable, and will be stripped. This argument must not be null.
1.158 + * @param aFirstURI
1.159 + * the URI that the user originally typed in or clicked on to initiate
1.160 + * the load of the document referenced by aURI.
1.161 + * @param aPrompt
1.162 + * the prompt to use for all user-level cookie notifications. This is
1.163 + * presently ignored and can be null. (Prompt information is determined
1.164 + * from the channel if necessary.)
1.165 + * @param aCookie
1.166 + * the cookie string to set.
1.167 + * @param aServerTime
1.168 + * the current time reported by the server, if available. This should
1.169 + * be the string from the Date header in an HTTP response. If the
1.170 + * string is empty or null, server time is assumed to be the current
1.171 + * local time. If provided, it will be used to calculate the expiry
1.172 + * time of the cookie relative to the server's local time.
1.173 + * @param aChannel
1.174 + * the channel used to load the document. this parameter should not
1.175 + * be null, otherwise the cookies will not be set if third-party
1.176 + * cookies have been disabled by the user. (the channel is used
1.177 + * to determine the originating URI of the document; if it is not
1.178 + * provided, the cookies will be assumed third-party.)
1.179 + */
1.180 + void setCookieStringFromHttp(in nsIURI aURI, in nsIURI aFirstURI, in nsIPrompt aPrompt, in string aCookie, in string aServerTime, in nsIChannel aChannel);
1.181 +};
