manager.rst (3705B)
1 Permission Manager 2 ================== 3 4 The Firefox permission manager offers a simple way to store user preferences 5 (“permissions” or “exceptions”) on a per-origin basis. On the most basic level, 6 a permission consists of the following: 7 8 1. The **origin** for which the permission applicable. This could for example be 9 https://example.com. 10 2. The permission **type**. This can be an arbitrary string, for example “geo” 11 to allow geolocation access on the specified site. 12 3. The permission **value**. Unless specified otherwise, this value is either 13 ``0`` (“Undefined”), ``1`` (“Allow”), ``2`` (“Deny”) or ``3`` (“Prompt the user”). 14 15 For storing arbitrary preferences per origin instead of just permission values, 16 the `content pref service 17 <https://searchfox.org/mozilla-central/source/dom/interfaces/base/nsIContentPrefService2.idl>`__ 18 offers a good alternative to the permission manager. There also exists the `site 19 permission manager 20 <https://searchfox.org/mozilla-central/source/browser/modules/SitePermissions.sys.mjs>`__, 21 which builds on top of the regular permission manager, and makes temporary 22 permissions that are not stored to disk, and user interfaces easier. 23 24 Interfacing with the Permission Manager 25 --------------------------------------- 26 27 The permission manager can be accessed through the ``nsIPermissionManager`` 28 interface. This interface is available through the 29 ``@mozilla.org/permissionmanager;1`` service, or through the quick 30 ``Services.perms`` getter in JavaScript. Below is a list of the most common 31 methods, and examples on how to use them with JavaScript. For a full list of 32 signatures, see `nsIPermissionManager.idl 33 <https://searchfox.org/mozilla-central/source/netwerk/base/nsIPermissionManager.idl>`__. 34 35 ``testExactPermissionFromPrincipal`` 36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 37 38 Returns any possible stored permission value for a given origin and permission 39 type. To also find permission values if the given origin is a subdomain of the 40 permission's origin, use the otherwise identical ``testPermissionFromPrincipal`` 41 method. 42 43 .. code:: js 44 45 // Only construct the principal yourself if you can't get from somewhere else 46 // (e.g. gBrowser.contentPrincipal) directly. 47 let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin( 48 "https://example.org" 49 ); 50 51 let perm = Services.perms.testExactPermissionFromPrincipal(principal, "geo"); 52 if (perm == Services.perms.ALLOW_ACTION) { 53 // Do things 54 } 55 56 57 ``addFromPrincipal`` 58 ~~~~~~~~~~~~~~~~~~~~ 59 60 Adds a permission to the permission manager for a given origin, permission type 61 and value. Optionally, the permission can be configured to expire after the 62 current browsing session ends, or to expire on a given UNIX timestamp in 63 milliseconds. 64 65 .. code:: js 66 67 let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin( 68 "https://example.org" 69 ); 70 71 // Never expires 72 Services.perms.addFromPrincipal(principal, "geo", Services.perms.ALLOW_ACTION); 73 74 // Expires after the current session 75 Services.perms.addFromPrincipal( 76 principal, 77 "geo", 78 Services.perms.ALLOW_ACTION, 79 Services.perms.EXPIRE_SESSION 80 ); 81 82 // Expires in 24 hours 83 Services.perms.addFromPrincipal( 84 principal, 85 "geo", 86 Services.perms.ALLOW_ACTION, 87 Services.perms.EXPIRE_TIME, 88 Date.now() + 1000 * 60 * 60 * 24 89 ); 90 91 92 ``removeFromPrincipal`` 93 ~~~~~~~~~~~~~~~~~~~~~~~ 94 95 Removes a permission from the permission manager for a given origin and 96 permission type. 97 98 .. code:: js 99 100 let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin( 101 "https://example.org" 102 ); 103 104 Services.perms.removeFromPrincipal(principal, "geo");