1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIPermissionManager.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,259 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/**
1.10 + * This file contains an interface to the Permission Manager,
1.11 + * used to persistenly store permissions for different object types (cookies,
1.12 + * images etc) on a site-by-site basis.
1.13 + *
1.14 + * This service broadcasts the following notification when the permission list
1.15 + * is changed:
1.16 + *
1.17 + * topic : "perm-changed" (PERM_CHANGE_NOTIFICATION)
1.18 + * broadcast whenever the permission list changes in some way. there
1.19 + * are four possible data strings for this notification; one
1.20 + * notification will be broadcast for each change, and will involve
1.21 + * a single permission.
1.22 + * subject: an nsIPermission interface pointer representing the permission object
1.23 + * that changed.
1.24 + * data : "deleted"
1.25 + * a permission was deleted. the subject is the deleted permission.
1.26 + * "added"
1.27 + * a permission was added. the subject is the added permission.
1.28 + * "changed"
1.29 + * a permission was changed. the subject is the new permission.
1.30 + * "cleared"
1.31 + * the entire permission list was cleared. the subject is null.
1.32 + */
1.33 +
1.34 +#include "nsISupports.idl"
1.35 +
1.36 +interface nsIURI;
1.37 +interface nsIObserver;
1.38 +interface nsIPrincipal;
1.39 +interface nsIDOMWindow;
1.40 +interface nsIPermission;
1.41 +interface nsISimpleEnumerator;
1.42 +
1.43 +[scriptable, uuid(c9fec678-f194-43c9-96b0-7bd9dbdd6bb0)]
1.44 +interface nsIPermissionManager : nsISupports
1.45 +{
1.46 + /**
1.47 + * Predefined return values for the testPermission method and for
1.48 + * the permission param of the add method
1.49 + * NOTE: UNKNOWN_ACTION (0) is reserved to represent the
1.50 + * default permission when no entry is found for a host, and
1.51 + * should not be used by consumers to indicate otherwise.
1.52 + */
1.53 + const uint32_t UNKNOWN_ACTION = 0;
1.54 + const uint32_t ALLOW_ACTION = 1;
1.55 + const uint32_t DENY_ACTION = 2;
1.56 + const uint32_t PROMPT_ACTION = 3;
1.57 +
1.58 + /**
1.59 + * Predefined expiration types for permissions. Permissions can be permanent
1.60 + * (never expire), expire at the end of the session, or expire at a specified
1.61 + * time. Permissions that expire at the end of a session may also have a
1.62 + * specified expiration time.
1.63 + */
1.64 + const uint32_t EXPIRE_NEVER = 0;
1.65 + const uint32_t EXPIRE_SESSION = 1;
1.66 + const uint32_t EXPIRE_TIME = 2;
1.67 +
1.68 + /**
1.69 + * Add permission information for a given URI and permission type. This
1.70 + * operation will cause the type string to be registered if it does not
1.71 + * currently exist. If a permission already exists for a given type, it
1.72 + * will be modified.
1.73 + *
1.74 + * @param uri the uri to add the permission for
1.75 + * @param type a case-sensitive ASCII string, identifying the consumer.
1.76 + * Consumers should choose this string to be unique, with
1.77 + * respect to other consumers.
1.78 + * @param permission an integer representing the desired action (e.g. allow
1.79 + * or deny). The interpretation of this number is up to the
1.80 + * consumer, and may represent different actions for different
1.81 + * types. Consumers may use one of the enumerated permission
1.82 + * actions defined above, for convenience.
1.83 + * NOTE: UNKNOWN_ACTION (0) is reserved to represent the
1.84 + * default permission when no entry is found for a host, and
1.85 + * should not be used by consumers to indicate otherwise.
1.86 + * @param expiretype a constant defining whether this permission should
1.87 + * never expire (EXPIRE_NEVER), expire at the end of the
1.88 + * session (EXPIRE_SESSION), or expire at a specified time
1.89 + * (EXPIRE_TIME).
1.90 + * @param expiretime an integer representation of when this permission
1.91 + * should be forgotten (milliseconds since Jan 1 1970 0:00:00).
1.92 + */
1.93 + void add(in nsIURI uri,
1.94 + in string type,
1.95 + in uint32_t permission,
1.96 + [optional] in uint32_t expireType,
1.97 + [optional] in int64_t expireTime);
1.98 +
1.99 + /**
1.100 + * Add permission information for a given principal.
1.101 + * It is internally calling the other add() method using the nsIURI from the
1.102 + * principal.
1.103 + * Passing a system principal will be a no-op because they will always be
1.104 + * granted permissions.
1.105 + */
1.106 + void addFromPrincipal(in nsIPrincipal principal, in string typed,
1.107 + in uint32_t permission,
1.108 + [optional] in uint32_t expireType,
1.109 + [optional] in int64_t expireTime);
1.110 +
1.111 + /**
1.112 + * Remove permission information for a given host string and permission type.
1.113 + * The host string represents the exact entry in the permission list (such as
1.114 + * obtained from the enumerator), not a URI which that permission might apply
1.115 + * to.
1.116 + *
1.117 + * @param host the host to remove the permission for
1.118 + * @param type a case-sensitive ASCII string, identifying the consumer.
1.119 + * The type must have been previously registered using the
1.120 + * add() method.
1.121 + */
1.122 + void remove(in AUTF8String host,
1.123 + in string type);
1.124 +
1.125 + /**
1.126 + * Remove permission information for a given principal.
1.127 + * This is internally calling remove() with the host from the principal's URI.
1.128 + * Passing system principal will be a no-op because we never add them to the
1.129 + * database.
1.130 + */
1.131 + void removeFromPrincipal(in nsIPrincipal principal, in string type);
1.132 +
1.133 + /**
1.134 + * Clear permission information for all websites.
1.135 + */
1.136 + void removeAll();
1.137 +
1.138 + /**
1.139 + * Test whether a website has permission to perform the given action.
1.140 + * @param uri the uri to be tested
1.141 + * @param type a case-sensitive ASCII string, identifying the consumer
1.142 + * @param return see add(), param permission. returns UNKNOWN_ACTION when
1.143 + * there is no stored permission for this uri and / or type.
1.144 + */
1.145 + uint32_t testPermission(in nsIURI uri,
1.146 + in string type);
1.147 +
1.148 + /**
1.149 + * Test whether the principal has the permission to perform a given action.
1.150 + * System principals will always have permissions granted.
1.151 + */
1.152 + uint32_t testPermissionFromPrincipal(in nsIPrincipal principal,
1.153 + in string type);
1.154 +
1.155 + /**
1.156 + * Test whether the principal associated with the window's document has the
1.157 + * permission to perform a given action. System principals will always
1.158 + * have permissions granted.
1.159 + */
1.160 + uint32_t testPermissionFromWindow(in nsIDOMWindow window,
1.161 + in string type);
1.162 +
1.163 + /**
1.164 + * Test whether a website has permission to perform the given action.
1.165 + * This requires an exact hostname match, subdomains are not a match.
1.166 + * @param uri the uri to be tested
1.167 + * @param type a case-sensitive ASCII string, identifying the consumer
1.168 + * @param return see add(), param permission. returns UNKNOWN_ACTION when
1.169 + * there is no stored permission for this uri and / or type.
1.170 + */
1.171 + uint32_t testExactPermission(in nsIURI uri,
1.172 + in string type);
1.173 +
1.174 + /**
1.175 + * See testExactPermission() above.
1.176 + * System principals will always have permissions granted.
1.177 + */
1.178 + uint32_t testExactPermissionFromPrincipal(in nsIPrincipal principal,
1.179 + in string type);
1.180 +
1.181 + /**
1.182 + * Test whether a website has permission to perform the given action
1.183 + * ignoring active sessions.
1.184 + * System principals will always have permissions granted.
1.185 + *
1.186 + * @param principal the principal
1.187 + * @param type a case-sensitive ASCII string, identifying the consumer
1.188 + * @param return see add(), param permission. returns UNKNOWN_ACTION when
1.189 + * there is no stored permission for this uri and / or type.
1.190 + */
1.191 + uint32_t testExactPermanentPermission(in nsIPrincipal principal,
1.192 + in string type);
1.193 +
1.194 + /**
1.195 + * Get the permission object associated with the given principal and action.
1.196 + * @param principal The principal
1.197 + * @param type A case-sensitive ASCII string identifying the consumer
1.198 + * @param exactHost If true, only the specific host will be matched,
1.199 + * @see testExactPermission. If false, subdomains will
1.200 + * also be searched, @see testPermission.
1.201 + * @returns The matching permission object, or null if no matching object
1.202 + * was found. No matching object is equivalent to UNKNOWN_ACTION.
1.203 + * @note Clients in general should prefer the test* methods unless they
1.204 + * need to know the specific stored details.
1.205 + * @note This method will always return null for the system principal.
1.206 + */
1.207 + nsIPermission getPermissionObject(in nsIPrincipal principal,
1.208 + in string type,
1.209 + in boolean exactHost);
1.210 +
1.211 + /**
1.212 + * Increment or decrement our "refcount" of an app id.
1.213 + *
1.214 + * We use this refcount to determine an app's lifetime. When an app's
1.215 + * refcount goes to 0, we clear the permissions given to the app which are
1.216 + * set to expire at the end of its session.
1.217 + */
1.218 + void addrefAppId(in unsigned long appId);
1.219 + void releaseAppId(in unsigned long appId);
1.220 +
1.221 + /**
1.222 + * Allows enumeration of all stored permissions
1.223 + * @return an nsISimpleEnumerator interface that allows access to
1.224 + * nsIPermission objects
1.225 + */
1.226 + readonly attribute nsISimpleEnumerator enumerator;
1.227 +
1.228 + /**
1.229 + * Remove all permissions associated with a given app id.
1.230 + * @param aAppId The appId of the app
1.231 + * @param aBrowserOnly Whether we should remove permissions associated with
1.232 + * a browser element (true) or all permissions (false).
1.233 + */
1.234 + void removePermissionsForApp(in unsigned long appId,
1.235 + in boolean browserOnly);
1.236 +
1.237 + /**
1.238 + * If the current permission is set to expire, reset the expiration time. If
1.239 + * there is no permission or the current permission does not expire, this
1.240 + * method will silently return.
1.241 + *
1.242 + * @param sessionExpiretime an integer representation of when this permission
1.243 + * should be forgotten (milliseconds since
1.244 + * Jan 1 1970 0:00:00), if it is currently
1.245 + * EXPIRE_SESSION.
1.246 + * @param sessionExpiretime an integer representation of when this permission
1.247 + * should be forgotten (milliseconds since
1.248 + * Jan 1 1970 0:00:00), if it is currently
1.249 + * EXPIRE_TIME.
1.250 + */
1.251 + void updateExpireTime(in nsIPrincipal principal,
1.252 + in string type,
1.253 + in boolean exactHost,
1.254 + in uint64_t sessionExpireTime,
1.255 + in uint64_t persistentExpireTime);
1.256 +};
1.257 +
1.258 +%{ C++
1.259 +#define NS_PERMISSIONMANAGER_CONTRACTID "@mozilla.org/permissionmanager;1"
1.260 +
1.261 +#define PERM_CHANGE_NOTIFICATION "perm-changed"
1.262 +%}
