The Tor Browser: netwerk/base/public/nsIPermissionManager.idl@b8a032363ba2 (annotated)

netwerk/base/public/nsIPermissionManager.idl@b8a032363ba2 (annotated)

netwerk/base/public/nsIPermissionManager.idl

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 /**
  * This file contains an interface to the Permission Manager,
  * used to persistenly store permissions for different object types (cookies,
  * images etc) on a site-by-site basis.
  *
  * This service broadcasts the following notification when the permission list
  * is changed:
  *
  * topic  : "perm-changed" (PERM_CHANGE_NOTIFICATION)
  *          broadcast whenever the permission list changes in some way. there
  *          are four possible data strings for this notification; one
  *          notification will be broadcast for each change, and will involve
  *          a single permission.
  * subject: an nsIPermission interface pointer representing the permission object
  *          that changed.
  * data   : "deleted"
  *          a permission was deleted. the subject is the deleted permission.
  *          "added"
  *          a permission was added. the subject is the added permission.
  *          "changed"
  *          a permission was changed. the subject is the new permission.
  *          "cleared"
  *          the entire permission list was cleared. the subject is null.
  */
 #include "nsISupports.idl"
 interface nsIURI;
 interface nsIObserver;
 interface nsIPrincipal;
 interface nsIDOMWindow;
 interface nsIPermission;
 interface nsISimpleEnumerator;
 [scriptable, uuid(c9fec678-f194-43c9-96b0-7bd9dbdd6bb0)]
 interface nsIPermissionManager : nsISupports
 {
   /**
    * Predefined return values for the testPermission method and for
    * the permission param of the add method
    * NOTE: UNKNOWN_ACTION (0) is reserved to represent the
    * default permission when no entry is found for a host, and
    * should not be used by consumers to indicate otherwise.
    */
   const uint32_t UNKNOWN_ACTION = 0;
   const uint32_t ALLOW_ACTION = 1;
   const uint32_t DENY_ACTION = 2;
   const uint32_t PROMPT_ACTION = 3;
   /**
    * Predefined expiration types for permissions.  Permissions can be permanent
    * (never expire), expire at the end of the session, or expire at a specified
    * time. Permissions that expire at the end of a session may also have a
    * specified expiration time.
    */
   const uint32_t EXPIRE_NEVER = 0;
   const uint32_t EXPIRE_SESSION = 1;
   const uint32_t EXPIRE_TIME = 2;
   /**
    * Add permission information for a given URI and permission type. This
    * operation will cause the type string to be registered if it does not
    * currently exist. If a permission already exists for a given type, it
    * will be modified.
    *
    * @param uri         the uri to add the permission for
    * @param type        a case-sensitive ASCII string, identifying the consumer.
    *                    Consumers should choose this string to be unique, with
    *                    respect to other consumers.
    * @param permission  an integer representing the desired action (e.g. allow
    *                    or deny). The interpretation of this number is up to the
    *                    consumer, and may represent different actions for different
    *                    types. Consumers may use one of the enumerated permission
    *                    actions defined above, for convenience.
    *                    NOTE: UNKNOWN_ACTION (0) is reserved to represent the
    *                    default permission when no entry is found for a host, and
    *                    should not be used by consumers to indicate otherwise.
    * @param expiretype  a constant defining whether this permission should
    *                    never expire (EXPIRE_NEVER), expire at the end of the
    *                    session (EXPIRE_SESSION), or expire at a specified time
    *                    (EXPIRE_TIME).
    * @param expiretime  an integer representation of when this permission
    *                    should be forgotten (milliseconds since Jan 1 1970 0:00:00).
    */
   void add(in nsIURI uri,
            in string type,
            in uint32_t permission,
            [optional] in uint32_t expireType,
            [optional] in int64_t expireTime);
   /**
    * Add permission information for a given principal.
    * It is internally calling the other add() method using the nsIURI from the
    * principal.
    * Passing a system principal will be a no-op because they will always be
    * granted permissions.
    */
   void addFromPrincipal(in nsIPrincipal principal, in string typed,
                         in uint32_t permission,
                         [optional] in uint32_t expireType,
                         [optional] in int64_t expireTime);
   /**
    * Remove permission information for a given host string and permission type.
    * The host string represents the exact entry in the permission list (such as
    * obtained from the enumerator), not a URI which that permission might apply
    * to.
    *
    * @param host   the host to remove the permission for
    * @param type   a case-sensitive ASCII string, identifying the consumer.
    *               The type must have been previously registered using the
    *               add() method.
    */
   void remove(in AUTF8String host,
               in string type);
   /**
    * Remove permission information for a given principal.
    * This is internally calling remove() with the host from the principal's URI.
    * Passing system principal will be a no-op because we never add them to the
    * database.
    */
   void removeFromPrincipal(in nsIPrincipal principal, in string type);
   /**
    * Clear permission information for all websites.
    */
   void removeAll();
   /**
    * Test whether a website has permission to perform the given action.
    * @param uri     the uri to be tested
    * @param type    a case-sensitive ASCII string, identifying the consumer
    * @param return  see add(), param permission. returns UNKNOWN_ACTION when
    *                there is no stored permission for this uri and / or type.
    */
   uint32_t testPermission(in nsIURI uri,
                           in string type);
   /**
    * Test whether the principal has the permission to perform a given action.
    * System principals will always have permissions granted.
    */
   uint32_t testPermissionFromPrincipal(in nsIPrincipal principal,
                                        in string type);
   /**
    * Test whether the principal associated with the window's document has the
    * permission to perform a given action.  System principals will always
    * have permissions granted.
    */
   uint32_t testPermissionFromWindow(in nsIDOMWindow window,
                                     in string type);
   /**
    * Test whether a website has permission to perform the given action.
    * This requires an exact hostname match, subdomains are not a match.
    * @param uri     the uri to be tested
    * @param type    a case-sensitive ASCII string, identifying the consumer
    * @param return  see add(), param permission. returns UNKNOWN_ACTION when
    *                there is no stored permission for this uri and / or type.
    */
   uint32_t testExactPermission(in nsIURI uri,
                                in string type);
   /**
    * See testExactPermission() above.
    * System principals will always have permissions granted.
    */
   uint32_t testExactPermissionFromPrincipal(in nsIPrincipal principal,
                                             in string type);
   /**
    * Test whether a website has permission to perform the given action
    * ignoring active sessions.
    * System principals will always have permissions granted.
    *
    * @param principal the principal
    * @param type      a case-sensitive ASCII string, identifying the consumer
    * @param return    see add(), param permission. returns UNKNOWN_ACTION when
    *                  there is no stored permission for this uri and / or type.
    */
   uint32_t testExactPermanentPermission(in nsIPrincipal principal,
                                         in string type);
   /**
    * Get the permission object associated with the given principal and action.
    * @param principal The principal
    * @param type      A case-sensitive ASCII string identifying the consumer
    * @param exactHost If true, only the specific host will be matched,
    *                  @see testExactPermission. If false, subdomains will
    *                  also be searched, @see testPermission.
    * @returns The matching permission object, or null if no matching object
    *          was found. No matching object is equivalent to UNKNOWN_ACTION.
    * @note Clients in general should prefer the test* methods unless they
    *       need to know the specific stored details.
    * @note This method will always return null for the system principal.
    */
   nsIPermission getPermissionObject(in nsIPrincipal principal,
                                     in string type,
                                     in boolean exactHost);
    /**
     * Increment or decrement our "refcount" of an app id.
     *
     * We use this refcount to determine an app's lifetime.  When an app's
     * refcount goes to 0, we clear the permissions given to the app which are
     * set to expire at the end of its session.
     */
    void addrefAppId(in unsigned long appId);
    void releaseAppId(in unsigned long appId);
   /**
    * Allows enumeration of all stored permissions
    * @return an nsISimpleEnumerator interface that allows access to
    *         nsIPermission objects
    */
   readonly attribute nsISimpleEnumerator enumerator;
   /**
    * Remove all permissions associated with a given app id.
    * @param aAppId       The appId of the app
    * @param aBrowserOnly Whether we should remove permissions associated with
    *                     a browser element (true) or all permissions (false).
    */
   void removePermissionsForApp(in unsigned long appId,
                                in boolean browserOnly);
   /**
    * If the current permission is set to expire, reset the expiration time. If
    * there is no permission or the current permission does not expire, this
    * method will silently return.
    *
    * @param sessionExpiretime  an integer representation of when this permission
    *                           should be forgotten (milliseconds since
    *                           Jan 1 1970 0:00:00), if it is currently
    *                           EXPIRE_SESSION.
    * @param sessionExpiretime  an integer representation of when this permission
    *                           should be forgotten (milliseconds since
    *                           Jan 1 1970 0:00:00), if it is currently
    *                           EXPIRE_TIME.
    */
   void updateExpireTime(in nsIPrincipal principal,
                         in string type,
                         in boolean exactHost,
                         in uint64_t sessionExpireTime,
                         in uint64_t persistentExpireTime);
 };
 %{ C++
 #define NS_PERMISSIONMANAGER_CONTRACTID "@mozilla.org/permissionmanager;1"
 #define PERM_CHANGE_NOTIFICATION "perm-changed"
 %}

The Tor Browser / annotate

netwerk/base/public/nsIPermissionManager.idl@b8a032363ba2 (annotated)

netwerk/base/public/nsIPermissionManager.idl