1 /* ***** BEGIN LICENSE BLOCK *****
2 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
3 *
4 * The contents of this file are subject to the Mozilla Public License Version
5 * 1.1 (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
7 * http://www.mozilla.org/MPL/
8 *
9 * Software distributed under the License is distributed on an "AS IS" basis,
10 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11 * for the specific language governing rights and limitations under the
12 * License.
13 *
14 * The Original Code is cookie manager code.
15 *
16 * The Initial Developer of the Original Code is
17 * Michiel van Leeuwen (mvl@exedo.nl).
18 * Portions created by the Initial Developer are Copyright (C) 2003
19 * the Initial Developer. All Rights Reserved.
20 *
21 * Contributor(s):
22 * Daniel Witte <dwitte@stanford.edu>
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 "nsISupports.idl"
39
40 interface nsICookie2;
41 interface nsIURI;
42 interface nsIChannel;
43
44 typedef long nsCookieAccess;
45
46 /**
47 * An interface to test for cookie permissions
48 */
49 [scriptable, uuid(4b1a775d-f6d3-4389-be2e-9dfbaf2ab47b)]
50 interface nsICookiePermission : nsISupports
51 {
52 /**
53 * nsCookieAccess values
54 */
55 const nsCookieAccess ACCESS_DEFAULT = 0;
56 const nsCookieAccess ACCESS_ALLOW = 1;
57 const nsCookieAccess ACCESS_DENY = 2;
58
59 /**
60 * additional values for nsCookieAccess, which are not directly used by
61 * any methods on this interface, but are nevertheless convenient to define
62 * here. these may be relocated somewhere else if we ever consider freezing
63 * this interface.
64 */
65 const nsCookieAccess ACCESS_SESSION = 8;
66
67 /**
68 * setAccess
69 *
70 * this method is called to block cookie access for the given URI. this
71 * may result in other URIs being blocked as well (e.g., URIs which share
72 * the same host name).
73 *
74 * @param aURI
75 * the URI to block
76 * @param aAccess
77 * the new cookie access for the URI.
78 */
79 void setAccess(in nsIURI aURI,
80 in nsCookieAccess aAccess);
81
82 /**
83 * canAccess
84 *
85 * this method is called to test whether or not the given URI/channel may
86 * access the cookie database, either to set or get cookies.
87 *
88 * @param aURI
89 * the URI trying to access cookies
90 * @param aChannel
91 * the channel corresponding to aURI
92 *
93 * @return one of the following nsCookieAccess values:
94 * ACCESS_DEFAULT, ACCESS_ALLOW, or ACCESS_DENY
95 */
96 nsCookieAccess canAccess(in nsIURI aURI,
97 in nsIChannel aChannel);
98
99 /**
100 * canSetCookie
101 *
102 * this method is called to test whether or not the given URI/channel may
103 * set a specific cookie. this method is always preceded by a call to
104 * canAccess. it may modify the isSession and expiry attributes of the
105 * cookie via the aIsSession and aExpiry parameters, in order to limit
106 * or extend the lifetime of the cookie. this is useful, for instance, to
107 * downgrade a cookie to session-only if it fails to meet certain criteria.
108 *
109 * @param aURI
110 * the URI trying to set the cookie
111 * @param aChannel
112 * the channel corresponding to aURI
113 * @param aCookie
114 * the cookie being added to the cookie database
115 * @param aIsSession
116 * when canSetCookie is invoked, this is the current isSession attribute
117 * of the cookie. canSetCookie may leave this value unchanged to
118 * preserve this attribute of the cookie.
119 * @param aExpiry
120 * when canSetCookie is invoked, this is the current expiry time of
121 * the cookie. canSetCookie may leave this value unchanged to
122 * preserve this attribute of the cookie.
123 *
124 * @return true if the cookie can be set.
125 */
126 boolean canSetCookie(in nsIURI aURI,
127 in nsIChannel aChannel,
128 in nsICookie2 aCookie,
129 inout boolean aIsSession,
130 inout PRInt64 aExpiry);
131
132 /**
133 * getOriginatingURI
134 *
135 * determines the originating URI for a load given a channel, for third-party
136 * cookie blocking. this is done by leveraging the loadgroup of the channel to
137 * find the root content docshell, and the URI associated with its principal.
138 * if the root content docshell or its principal's URI cannot be obtained,
139 * this method will throw.
140 *
141 * @param aChannel
142 * the channel for the load trying to get or set cookies
143 *
144 * @return the originating URI.
145 */
146 nsIURI getOriginatingURI(in nsIChannel aChannel);
147 };
148
149 %{ C++
150 /**
151 * The nsICookiePermission implementation is an XPCOM service registered
152 * under the ContractID:
153 */
154 #define NS_COOKIEPERMISSION_CONTRACTID "@mozilla.org/cookie/permission;1"
155 %}