nsIPermissionManager.idl (12138B)
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/. */ 5 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. 10 * 11 * This service broadcasts the following notification when the permission list 12 * is changed: 13 * 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. 29 */ 30 31 #include "nsISupports.idl" 32 33 interface nsIPrincipal; 34 interface nsIPermission; 35 36 [scriptable, builtinclass, uuid(4dcb3851-eba2-4e42-b236-82d2596fca22)] 37 interface nsIPermissionManager : nsISupports 38 { 39 /** 40 * Predefined return values for the testPermission method and for 41 * the permission param of the add method 42 * NOTES: 43 * 44 * UNKNOWN_ACTION (0) is reserved to represent the 45 * default permission when no entry is found for a host, and 46 * should not be used by consumers to indicate otherwise. 47 * If no other entries are found, it translates into "prompt" 48 * in the permissions.query() API. 49 * 50 * PROMPT_ACTION (3) is not persisted for most permissions. 51 * Except for camera and microphone, where persisting it means 52 * "Always Ask" (the user leaves "☐ Remember this decision" 53 * unchecked in the permission grant). It translates into 54 * "granted" in permissions.query() to prevent websites from 55 * asking users to escalate permissions further. 56 * 57 * MAX_VALID_ACTION is the highest value (used to validate prefs) 58 */ 59 const uint32_t UNKNOWN_ACTION = 0; 60 const uint32_t ALLOW_ACTION = 1; 61 const uint32_t DENY_ACTION = 2; 62 const uint32_t PROMPT_ACTION = 3; 63 const uint32_t MAX_VALID_ACTION = 3; 64 65 /** 66 * Predefined expiration types for permissions. Permissions can be permanent 67 * (never expire), expire at the end of the session, or expire at a specified 68 * time. Permissions that expire at the end of a session may also have a 69 * specified expiration time. 70 * 71 * EXPIRE_POLICY is a special expiration status. It is set when the permission 72 * is set by reading an enterprise policy. These permissions cannot be overridden. 73 */ 74 const uint32_t EXPIRE_NEVER = 0; 75 const uint32_t EXPIRE_SESSION = 1; 76 const uint32_t EXPIRE_TIME = 2; 77 const uint32_t EXPIRE_POLICY = 3; 78 79 80 /** 81 * Get all custom permissions for a given nsIPrincipal. This will return an 82 * enumerator of all permissions which are not set to default and which 83 * belong to the matching principal of the given nsIPrincipal. 84 * 85 * @param principal the URI to get all permissions for 86 */ 87 Array<nsIPermission> getAllForPrincipal(in nsIPrincipal principal); 88 89 /** 90 * Get all custom permissions of a specific type, specified with a prefix 91 * string. This will return an array of all permissions which are not set to 92 * default. Also the passed type argument is either equal to or a prefix of 93 * the type of the returned permissions. 94 * 95 * @param prefix the type prefix string 96 */ 97 Array<nsIPermission> getAllWithTypePrefix(in ACString prefix); 98 99 100 /** 101 * Get all custom permissions whose type exactly match one of the types defined 102 * in the passed array argument. 103 * This will return an array of all permissions which are not set to default. 104 * 105 * @param types an array of case-sensitive ASCII strings, identifying the 106 * permissions to be matched. 107 */ 108 Array<nsIPermission> getAllByTypes(in Array<ACString> types); 109 110 /** 111 * Get all custom permissions of a specific type and that were modified after 112 * the specified date. This will return an array of all permissions which are 113 * not set to default. 114 * 115 * @param type a case-sensitive ASCII string, identifying the permission. 116 * @param since a unix timestamp representing the number of milliseconds from 117 * Jan 1, 1970 00:00:00 UTC. 118 */ 119 Array<nsIPermission> getAllByTypeSince(in ACString type, in int64_t since); 120 121 /** 122 * Add permission information for a given principal. 123 * It is internally calling the other add() method using the nsIURI from the 124 * principal. 125 * Passing a system principal will be a no-op because they will always be 126 * granted permissions. 127 */ 128 void addFromPrincipal(in nsIPrincipal principal, in ACString type, 129 in uint32_t permission, 130 [optional] in uint32_t expireType, 131 [optional] in int64_t expireTime); 132 133 /** 134 * Test method to add a permission for a given principal with custom modification time. 135 */ 136 void testAddFromPrincipalByTime(in nsIPrincipal principal, in ACString type, 137 in uint32_t permission, 138 in int64_t modificationTime 139 ); 140 141 /** 142 * Add permanent permission information for a given principal in private 143 * browsing. 144 * 145 * Normally permissions in private browsing are cleared at the end of the 146 * session, this method allows you to override this behavior and set 147 * permanent permissions. 148 * 149 * WARNING: setting permanent permissions _will_ leak data in private 150 * browsing. Only use if you understand the consequences and trade-offs. If 151 * you are unsure, |addFromPrincipal| is very likely what you want to use 152 * instead. 153 */ 154 void addFromPrincipalAndPersistInPrivateBrowsing(in nsIPrincipal principal, 155 in ACString type, 156 in uint32_t permission); 157 158 /** 159 * Add temporary default permission information for a given principal. 160 * This permission will be cleared at the end of the session, will not be 161 * stored on disk, and will not be set if a conflicting (non-default) 162 * permission already exists. 163 * 164 * This function shouldn't be used by regular permission manager consumers and 165 * is only expected to be called by the RemotePermissionService.sys.mjs for 166 * the purpose of importing default permissions from remote settings. 167 */ 168 void addDefaultFromPrincipal(in nsIPrincipal principal, 169 in ACString type, 170 in uint32_t permission); 171 172 /** 173 * Remove permission information for a given principal. 174 * This is internally calling remove() with the host from the principal's URI. 175 * Passing system principal will be a no-op because we never add them to the 176 * database. 177 */ 178 void removeFromPrincipal(in nsIPrincipal principal, in ACString type); 179 180 /** 181 * Remove the given permission from the permission manager. 182 * 183 * @param perm a permission obtained from the permission manager. 184 */ 185 void removePermission(in nsIPermission perm); 186 187 /** 188 * Clear permission information for all websites. 189 */ 190 void removeAll(); 191 192 /** 193 * Clear all permission information added since the specified time. 194 */ 195 void removeAllSince(in int64_t since); 196 197 /** 198 * Clear all permissions of the passed type. 199 */ 200 void removeByType(in ACString type); 201 202 /** 203 * Clear all permissions not of the passed types. 204 */ 205 void removeAllExceptTypes(in Array<ACString> typeExceptions); 206 207 /** 208 * Clear all permissions of the passed type added since the specified time. 209 * @param type a case-sensitive ASCII string, identifying the permission. 210 * @param since a unix timestamp representing the number of milliseconds from 211 * Jan 1, 1970 00:00:00 UTC. 212 */ 213 void removeByTypeSince(in ACString type, in int64_t since); 214 215 /** 216 * Clear all permissions of the passed types added since the specified time. 217 * @param since a unix timestamp representing the number of milliseconds from 218 * Jan 1, 1970 00:00:00 UTC. 219 * @param typeExceptions a array of case-sensitive ASCII strings, identifying 220 * the types to not remove. 221 */ 222 void removeAllSinceWithTypeExceptions(in int64_t since, in Array<ACString> typeExceptions); 223 224 /** 225 * Test whether the principal has the permission to perform a given action. 226 * System principals will always have permissions granted. 227 * This function will perform a pref lookup to permissions.default.<type> 228 * if the specific permission type is part of the whitelist for that functionality. 229 */ 230 uint32_t testPermissionFromPrincipal(in nsIPrincipal principal, 231 in ACString type); 232 233 /** 234 * Test whether the principal has the permission to perform a given action. 235 * This requires an exact hostname match. Subdomain principals do not match 236 * permissions of base domains. 237 * System principals will always have permissions granted. 238 * This function will perform a pref lookup to permissions.default.<type> 239 * if the specific permission type is part of the whitelist for that functionality. 240 */ 241 uint32_t testExactPermissionFromPrincipal(in nsIPrincipal principal, 242 in ACString type); 243 244 /** 245 * Test whether a website has permission to perform the given action 246 * ignoring active sessions. 247 * System principals will always have permissions granted. 248 * This function will perform a pref lookup to permissions.default.<type> 249 * if the specific permission type is part of the whitelist for that functionality. 250 * 251 * @param principal the principal 252 * @param type a case-sensitive ASCII string, identifying the consumer 253 * @param return see add(), param permission. returns UNKNOWN_ACTION when 254 * there is no stored permission for this uri and / or type. 255 */ 256 uint32_t testExactPermanentPermission(in nsIPrincipal principal, 257 in ACString type); 258 259 /** 260 * Get the permission object associated with the given principal and action. 261 * @param principal The principal 262 * @param type A case-sensitive ASCII string identifying the consumer 263 * @param exactHost If true, only the specific host will be matched. 264 * If false, base domains of the principal will also 265 * be searched. 266 * @returns The matching permission object, or null if no matching object 267 * was found. No matching object is equivalent to UNKNOWN_ACTION. 268 * @note Clients in general should prefer the test* methods unless they 269 * need to know the specific stored details. 270 * @note This method will always return null for the system principal. 271 */ 272 nsIPermission getPermissionObject(in nsIPrincipal principal, 273 in ACString type, 274 in boolean exactHost); 275 276 /** 277 * Returns all stored permissions. 278 * @return an array of nsIPermission objects 279 */ 280 readonly attribute Array<nsIPermission> all; 281 282 /** 283 * Remove all permissions that will match the origin pattern. 284 * @param patternAsJSON Origin pattern to match. 285 * @param typeInclusions Types to include in search. If empty, includes all types. 286 * @param typeExceptions Types to skip in search. 287 */ 288 void removePermissionsWithAttributes(in AString patternAsJSON, in Array<ACString> typeInclusions, in Array<ACString> typeExceptions); 289 }; 290 291 %{ C++ 292 #define NS_PERMISSIONMANAGER_CONTRACTID "@mozilla.org/permissionmanager;1" 293 294 #define PERM_CHANGE_NOTIFICATION "perm-changed" 295 %}