firefox-dev 11.0+build1-0ubuntu4 / usr / share / idl / firefox / nsIPermissionManager.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/**
 * 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"
#include "nsISimpleEnumerator.idl"

interface nsIURI;
interface nsIObserver;

[scriptable, uuid(0b83f9d5-3f96-41b6-91aa-ff3a7e4880d7)]
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 PRUint32 UNKNOWN_ACTION = 0;
  const PRUint32 ALLOW_ACTION = 1;
  const PRUint32 DENY_ACTION = 2;

  /**
   * Predefined expiration types for permissions.  Permissions can be permanent
   * (never expire), expire at the end of the session, or expire at a specified
   * time.
   */
  const PRUint32 EXPIRE_NEVER = 0;
  const PRUint32 EXPIRE_SESSION = 1;
  const PRUint32 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 PRUint32 permission,
           [optional] in PRUint32 expireType,
           [optional] in PRInt64 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);

  /**
   * 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.
   */
  PRUint32 testPermission(in nsIURI uri,
                          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.
   */
  PRUint32 testExactPermission(in nsIURI uri,
                               in string type);

  /**
   * Allows enumeration of all stored permissions
   * @return an nsISimpleEnumerator interface that allows access to
   *         nsIPermission objects
   */
  readonly attribute nsISimpleEnumerator enumerator;
};

%{ C++
#define NS_PERMISSIONMANAGER_CONTRACTID "@mozilla.org/permissionmanager;1"

#define PERM_CHANGE_NOTIFICATION "perm-changed"
%}