Backed out 2 changesets (bug 1816628) for causing OS X mochitests-plain failures...
[gecko.git] / netwerk / base / nsIPermissionManager.idl
blobf234958010d4d70fdd33c2323485f5fedc8ca36a
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 /**
7 * This file contains an interface to the Permission Manager,
8 * used to persistenly store permissions for different object types (cookies,
9 * images etc) on a site-by-site basis.
11 * This service broadcasts the following notification when the permission list
12 * is changed:
14 * topic : "perm-changed" (PERM_CHANGE_NOTIFICATION)
15 * broadcast whenever the permission list changes in some way. there
16 * are four possible data strings for this notification; one
17 * notification will be broadcast for each change, and will involve
18 * a single permission.
19 * subject: an nsIPermission interface pointer representing the permission object
20 * that changed.
21 * data : "deleted"
22 * a permission was deleted. the subject is the deleted permission.
23 * "added"
24 * a permission was added. the subject is the added permission.
25 * "changed"
26 * a permission was changed. the subject is the new permission.
27 * "cleared"
28 * the entire permission list was cleared. the subject is null.
31 #include "nsISupports.idl"
33 interface nsIPrincipal;
34 interface nsIPermission;
36 [scriptable, builtinclass, uuid(4dcb3851-eba2-4e42-b236-82d2596fca22)]
37 interface nsIPermissionManager : nsISupports
39 /**
40 * Predefined return values for the testPermission method and for
41 * the permission param of the add method
42 * NOTE: UNKNOWN_ACTION (0) is reserved to represent the
43 * default permission when no entry is found for a host, and
44 * should not be used by consumers to indicate otherwise.
46 const uint32_t UNKNOWN_ACTION = 0;
47 const uint32_t ALLOW_ACTION = 1;
48 const uint32_t DENY_ACTION = 2;
49 const uint32_t PROMPT_ACTION = 3;
51 /**
52 * Predefined expiration types for permissions. Permissions can be permanent
53 * (never expire), expire at the end of the session, or expire at a specified
54 * time. Permissions that expire at the end of a session may also have a
55 * specified expiration time.
57 * EXPIRE_POLICY is a special expiration status. It is set when the permission
58 * is set by reading an enterprise policy. These permissions cannot be overridden.
60 const uint32_t EXPIRE_NEVER = 0;
61 const uint32_t EXPIRE_SESSION = 1;
62 const uint32_t EXPIRE_TIME = 2;
63 const uint32_t EXPIRE_POLICY = 3;
66 /**
67 * Get all custom permissions for a given nsIPrincipal. This will return an
68 * enumerator of all permissions which are not set to default and which
69 * belong to the matching principal of the given nsIPrincipal.
71 * @param principal the URI to get all permissions for
73 Array<nsIPermission> getAllForPrincipal(in nsIPrincipal principal);
75 /**
76 * Get all custom permissions of a specific type, specified with a prefix
77 * string. This will return an array of all permissions which are not set to
78 * default. Also the passed type argument is either equal to or a prefix of
79 * the type of the returned permissions.
81 * @param prefix the type prefix string
83 Array<nsIPermission> getAllWithTypePrefix(in ACString prefix);
86 /**
87 * Get all custom permissions whose type exactly match one of the types defined
88 * in the passed array argument.
89 * This will return an array of all permissions which are not set to default.
91 * @param types an array of case-sensitive ASCII strings, identifying the
92 * permissions to be matched.
94 Array<nsIPermission> getAllByTypes(in Array<ACString> types);
96 /**
97 * Get all custom permissions of a specific type and that were modified after
98 * the specified date. This will return an array of all permissions which are
99 * not set to default.
101 * @param type a case-sensitive ASCII string, identifying the permission.
102 * @param since a unix timestamp representing the number of milliseconds from
103 * Jan 1, 1970 00:00:00 UTC.
105 Array<nsIPermission> getAllByTypeSince(in ACString type, in int64_t since);
108 * Add permission information for a given principal.
109 * It is internally calling the other add() method using the nsIURI from the
110 * principal.
111 * Passing a system principal will be a no-op because they will always be
112 * granted permissions.
114 void addFromPrincipal(in nsIPrincipal principal, in ACString type,
115 in uint32_t permission,
116 [optional] in uint32_t expireType,
117 [optional] in int64_t expireTime);
120 * Add permanent permission information for a given principal in private
121 * browsing.
123 * Normally permissions in private browsing are cleared at the end of the
124 * session, this method allows you to override this behavior and set
125 * permanent permissions.
127 * WARNING: setting permanent permissions _will_ leak data in private
128 * browsing. Only use if you understand the consequences and trade-offs. If
129 * you are unsure, |addFromPrincipal| is very likely what you want to use
130 * instead.
132 void addFromPrincipalAndPersistInPrivateBrowsing(in nsIPrincipal principal,
133 in ACString type,
134 in uint32_t permission);
137 * Remove permission information for a given principal.
138 * This is internally calling remove() with the host from the principal's URI.
139 * Passing system principal will be a no-op because we never add them to the
140 * database.
142 void removeFromPrincipal(in nsIPrincipal principal, in ACString type);
145 * Remove the given permission from the permission manager.
147 * @param perm a permission obtained from the permission manager.
149 void removePermission(in nsIPermission perm);
152 * Clear permission information for all websites.
154 void removeAll();
157 * Clear all permission information added since the specified time.
159 void removeAllSince(in int64_t since);
162 * Clear all permissions of the passed type.
164 void removeByType(in ACString type);
167 * Clear all permissions of the passed type added since the specified time.
168 * @param type a case-sensitive ASCII string, identifying the permission.
169 * @param since a unix timestamp representing the number of milliseconds from
170 * Jan 1, 1970 00:00:00 UTC.
172 void removeByTypeSince(in ACString type, in int64_t since);
175 * Test whether the principal has the permission to perform a given action.
176 * System principals will always have permissions granted.
177 * This function will perform a pref lookup to permissions.default.<type>
178 * if the specific permission type is part of the whitelist for that functionality.
180 uint32_t testPermissionFromPrincipal(in nsIPrincipal principal,
181 in ACString type);
184 * Test whether the principal has the permission to perform a given action.
185 * This requires an exact hostname match. Subdomain principals do not match
186 * permissions of base domains.
187 * System principals will always have permissions granted.
188 * This function will perform a pref lookup to permissions.default.<type>
189 * if the specific permission type is part of the whitelist for that functionality.
191 uint32_t testExactPermissionFromPrincipal(in nsIPrincipal principal,
192 in ACString type);
195 * Test whether a website has permission to perform the given action
196 * ignoring active sessions.
197 * System principals will always have permissions granted.
198 * This function will perform a pref lookup to permissions.default.<type>
199 * if the specific permission type is part of the whitelist for that functionality.
201 * @param principal the principal
202 * @param type a case-sensitive ASCII string, identifying the consumer
203 * @param return see add(), param permission. returns UNKNOWN_ACTION when
204 * there is no stored permission for this uri and / or type.
206 uint32_t testExactPermanentPermission(in nsIPrincipal principal,
207 in ACString type);
210 * Get the permission object associated with the given principal and action.
211 * @param principal The principal
212 * @param type A case-sensitive ASCII string identifying the consumer
213 * @param exactHost If true, only the specific host will be matched.
214 * If false, base domains of the principal will also
215 * be searched.
216 * @returns The matching permission object, or null if no matching object
217 * was found. No matching object is equivalent to UNKNOWN_ACTION.
218 * @note Clients in general should prefer the test* methods unless they
219 * need to know the specific stored details.
220 * @note This method will always return null for the system principal.
222 nsIPermission getPermissionObject(in nsIPrincipal principal,
223 in ACString type,
224 in boolean exactHost);
227 * Returns all stored permissions.
228 * @return an array of nsIPermission objects
230 readonly attribute Array<nsIPermission> all;
233 * Remove all permissions that will match the origin pattern.
235 void removePermissionsWithAttributes(in AString patternAsJSON);
238 %{ C++
239 #define NS_PERMISSIONMANAGER_CONTRACTID "@mozilla.org/permissionmanager;1"
241 #define PERM_CHANGE_NOTIFICATION "perm-changed"