Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

This article needs a technical review. How you can help.

The nsIPermissionManager interface is used to persistently store permissions for different object types (cookies, images, and so on) on a site-by-site basis.

Please add a summary to this article.
  Last changed in Gecko 16 (Firefox 16 / Thunderbird 16 / SeaMonkey 2.13)

Inherits from: nsISupports

Method overview

void add(in nsIURI uri, in string type, in PRUint32 permission, [optional] in PRUint32 expireType, [optional] in PRInt64 expireTime);
void addFromPrincipal(in nsIPrincipal principal, in string type, in PRUint32 permission, [optional] in PRUint32 expireType, [optional] in PRInt64 expireTime);
void remove(in AUTF8String host, in string type);

void removeFromPrincipal(in nsIPrincipal principal, in string type);

void removePermission(in nsIPermission perm);

void removeAllSince(in int64_t since);

void removeAll();
PRUint32 testExactPermission(in nsIURI uri, in string type);
PRUint32 testExactPermissionFromPrincipal(in nsIPrincipal principal, in string type);
PRUint32 testPermission(in nsIURI uri, in string type);
PRUint32 testPermissionFromPrincipal(in nsIPrincipal principal, in string type);

Attributes

Attribute Type Description
enumerator nsISimpleEnumerator Enumerates all stored permissions. Allows access to nsIPermission objects. Read only.

Constants

Permission type constants

Constant Value Description
UNKNOWN_ACTION 0 Default permission when no entry is found for a host. It should not be used by consumers.
ALLOW_ACTION 1 Permission is allowed.
DENY_ACTION 2 Permission is denied.
PROMPT_ACTION 3 Prompt user if the permission is allowed.

Permission expiration constants

Constant Value Description
EXPIRE_NEVER 0 Permission never expires.
EXPIRE_SESSION 1 Permission expires at end of session.
EXPIRE_TIME 2 Permission expires at a specified time.

Methods

add()

Add permission information and permission type for a given URI. If the permission already exists for a given type, it will be modified.

void add(
  in nsIURI uri,
  in string type,
  in PRUint32 permission,
  [optional] in PRUint32 expireType,
  [optional] in PRInt64 expireTime
);
Parameters
uri
The URI to add the permission for.
type
A unique, case-sensitive ASCII string identifying the consumer. Consumers should choose this string to be unique, with respect to other consumers.
permission
An integer specifying the permission. See nsIPermissionManager.Permission_type_constants.
expireType
Expiration type of the permission. See nsIPermissionManager.Permission_expiration_constants.
expireTime
Time (in milliseconds since Jan 1 1970 0:00:00) representing expiration of this permission.

addFromPrincipal()

Add permission information and permission type for a given principal. If the permission already exists for a given type, it will be modified. It is internally calling add() method using the nsIURI from the principal.

void addFromPrincipal(
  in nsIPrincipal principal,
  in string type,
  in PRUint32 permission,
  [optional] in PRUint32 expireType,
  [optional] in PRInt64 expireTime
);
Parameters
principal
The principal to add the permission for.
type
A unique, case-sensitive ASCII string identifying the consumer. Consumers should choose this string to be unique, with respect to other consumers.
permission
An integer specifying the permission. See nsIPermissionManager.Permission_type_constants.
expireType
Expiration type of the permission. See nsIPermissionManager.Permission_expiration_constants.
expireTime
Time (in milliseconds since Jan 1 1970 0:00:00) representing expiration of this permission.

remove()

Remove permission information for a given host string and permission type.

void remove(
  in nsIURI uri,
  in string type
);
Parameters
nsIURI
The uri whose permission will be removed.
type
A case-sensitive ASCII string, identifying the type of the permission to be removed. This must have been previously registered using the add() method.

removeFromPrincipal()

Remove permission information for a given principal and permission type.

void removeFromPrincipal(
  in nsIPrincipal principal,
  in string type
);
Parameters
principal
The principal whose permission will be removed.
type
A case-sensitive ASCII string, identifying the type of the permission to be removed. This must have been previously registered using the add() method.

removePermission()

Remove a given permission from the stored permissions.

void removePermission(
  in nsIPermission perm
);
Parameters
nsIPermission
The permission which will be removed.

removeAllSince()

Remove permission information for a given host string and permission type.

void remove(
  in int64_t since
);
Parameters
since
Epoch timestamp. Permission information stored after this timestamp will be removed.

removeAll()

Remove permission information for all URIs.

void removeAll();
Parameters

None.

testExactPermission()

Checks if a URI is permitted to perform an action. This requires an exact hostname match, subdomains are not a match.

PRUint32 testExactPermission(
  in nsIURI uri,
  in string type
);
Parameters
uri
The URI to be tested.
type
A case-sensitive ASCII string, identifying the consumer.
Return value

A PRUint32 representing the permission, or UNKNOWN_ACTION if no permission exists.

testExactPermissionFromPrincipal()

Checks if a principal is permitted to perform an action. See testExactPermission().

PRUint32 testExactPermissionFromPrincipal(
  in nsIPrincipal principal,
  in string type
);
Parameters
principal
The principal to be tested.
type
A case-sensitive ASCII string, identifying the consumer.
Return value

A PRUint32 representing the permission, or UNKNOWN_ACTION if no permission exists.

testPermission()

Checks if a URI is permitted to perform an action.

PRUint32 testPermission(
  in nsIURI uri,
  in string type
);
Parameters
uri
The URI to be tested.
type
A case-sensitive ASCII string, identifying the consumer.
Return value

A PRUint32 representing the permission, or UNKNOWN_ACTION if no permission exists.

testPermissionFromPrincipal()

Checks if a principal is permitted to perform an action.

PRUint32 testPermissionFromPrincipal(
  in nsIPrincipal principal,
  in string type
);
Parameters
principal
The principal to be tested.
type
A case-sensitive ASCII string, identifying the consumer.
Return value

A PRUint32 representing the permission, or UNKNOWN_ACTION if no permission exists.

Remarks

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.

data : "deleted" a permission was deleted. The subject is the deleted nsIPermission.

data : "added" a permission was added. The subject is the added nsIPermission.

data : "changed" a permission was changed. The subject is the new nsIPermission.

data : "cleared" the entire permission list was cleared. The subject is null.

See also

Document Tags and Contributors

 Contributors to this page: Aryx, Jorge.villalobos, freaktechnik, Sheppy, mnoorenberghe, trevorh, Hashem
 Last updated by: Aryx,