netwerk/base/nsIPermissionManager.idl

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