net.rim.device.api.applicationcontrol
Class ApplicationPermissionsManager

java.lang.Object
  net.rim.device.api.applicationcontrol.ApplicationPermissionsManager

public final class ApplicationPermissionsManager
extends Object

Allows applications to query the application control database to get their permissions and request additional permissions.

These settings can also be set manually by the user, through the options application.

Per-Domain Permissions

Some permissions can be set on a per-domain basis as well as globally. Appropriate methods therefore are overloaded to accept a "domain" parameter to handle these cases. If such permissions are specified to the overloaded versions that do not have a "domain" parameter then they will relate to the default settings for domains.

The set of permissions that can be set on a per-domain basis are:

• ApplicationPermissions.PERMISSION_BROWSER_FILTER
• ApplicationPermissions.PERMISSION_INTERNET
• ApplicationPermissions.PERMISSION_SERVER_NETWORK

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.1

Method Summary
	void	addReasonProvider(ApplicationDescriptor appDesc, ReasonProvider provider) Adds a ReasonProvider to the currently running application which will allow descriptive Strings to be added to the application permissions dialog.
	ApplicationPermissions	getApplicationPermissions() Queries the application control database and returns the permissions of the calling application.
	ApplicationPermissions	getApplicationPermissions(boolean ignoreFirewall) Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getApplicationPermissions() instead.
	static ApplicationPermissionsManager	getInstance() Returns the singleton instance of this class.
	int	getMaxAllowable(int permission) Returns the least restrictive value that a permission can possibly have for the calling application.
	int	getMaxAllowable(int permission, String domain) Returns the least restrictive value that a permission can possibly have for a particular domain for the calling application.
	int	getPermission(int permission) Queries the application control database and returns the value of a permission of the calling application.
	int	getPermission(int permission, boolean ignoreFirewall) Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getPermission(int) instead.
	int	getPermission(int permission, String domain) Queries the application control database and returns the value of a permission of the calling application for a particular domain.
	int	getPermission(int permission, String domain, boolean ignoreFirewall) Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getPermission(int,String) instead.
	boolean	invokePermissionsRequest(ApplicationPermissions requestedPermissions) Request application control permissions for the calling application.
	void	removeReasonProvider(ReasonProvider provider) Removes a ReasonProvider from the currently running application.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static ApplicationPermissionsManager getInstance()

Returns the singleton instance of this class. This method will return the same object for each invocation within each application.

Returns:

the singleton instance of this class; never returns null.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.1

getPermission

public int getPermission(int permission)

Queries the application control database and returns the value of a permission of the calling application.

For permissions that can be set on a per-domain basis, invoking this method with such permissions is equivalent to invoking ApplicationPermissionsManager.getPermission(int, String) and specifying null for domain. See Per-Domain Permissions for details about domain-specific permissions.

Parameters:

permission - the permission whose value to get; must be equal to one of the permissions constants defined in the ApplicationPermissions class.

Returns:

the value of the specified permission of the calling application retrieved from the application control database; will be equal to one of ApplicationPermissions.VALUE_ALLOW, ApplicationPermissions.VALUE_PROMPT, or ApplicationPermissions.VALUE_DENY.

Throws:

IllegalArgumentException - if permission is not equal to one of the permissions constants defined in the ApplicationPermissions class.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.1

getPermission

public int getPermission(int permission,
                         boolean ignoreFirewall)

Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getPermission(int) instead.

Queries the application control database and returns the value of a permission of the calling application.

For permissions that can be set on a per-domain basis, invoking this method with such permissions is equivalent to invoking ApplicationPermissionsManager.getPermission(int, String) and specifying null for domain. See Per-Domain Permissions for details about domain-specific permissions.

Parameters:

permission - the permission whose value to get; must be equal to one of the permissions constants defined in the ApplicationPermissions class.

ignoreFirewall - This parameter is ignored. Previous versions used this parameter to indicate whether the firewall on/off state should be consulted when determining the current setting for the specified permission. Permissions are now always enforced irrespective of the state of the firewall, so this parameter is not used.

Returns:

the value of the specified permission of the calling application retrieved from the application control database; will be equal to one of ApplicationPermissions.VALUE_ALLOW, ApplicationPermissions.VALUE_PROMPT, or ApplicationPermissions.VALUE_DENY.

Throws:

IllegalArgumentException - if permission is not equal to one of the permissions constants defined in the ApplicationPermissions class.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.7.0

getPermission

public int getPermission(int permission,
                         String domain)

Queries the application control database and returns the value of a permission of the calling application for a particular domain.

See Per-Domain Permissions for details about domain-specific permissions.

Parameters:

permission - the permission whose value to get; valid values are any of the PERMISSION_ constants defined in ApplicationPermissions that can be set on a per-domain basis

domain - the domain to query; if null get the default value for domains that do not have permissions explicitly set for them

Returns:

the value of the specified permission of the calling application for the specified domain retrieved from the application control database accounting for the effects of the firewall state; will be equal to one of VALUE_ constants defined in ApplicationPermissions

Throws:

IllegalArgumentException - if permission is not a valid value

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.1

getPermission

public int getPermission(int permission,
                         String domain,
                         boolean ignoreFirewall)

Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getPermission(int,String) instead.

Queries the application control database and returns the value of a permission of the calling application for a particular domain.

See Per-Domain Permissions for details about domain-specific permissions.

Parameters:

permission - the permission whose value to get; valid values are any of the PERMISSION_ constants defined in ApplicationPermissions that can be set on a per-domain basis

domain - the domain to query; if null get the default value for domains that do not have permissions explicitly set for them

ignoreFirewall - This parameter is ignored. Previous versions used this parameter to indicate whether the firewall on/off state should be consulted when determining the current setting for the specified permission. Permissions are now always enforced irrespective of the state of the firewall, so this parameter is not used.

Returns:

the value of the specified permission of the calling application for the specified domain retrieved from the application control database accounting for the effects of the firewall state; will be equal to one of VALUE_ constants defined in ApplicationPermissions

Throws:

IllegalArgumentException - if permission is not a valid value

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.7.0

getApplicationPermissions

public ApplicationPermissions getApplicationPermissions()

Queries the application control database and returns the permissions of the calling application.

Returns:

an ApplicationPermissions object containing the value to which each permission is set in the application control database for the calling application accounting for the firewall state; never returns null

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.1

getApplicationPermissions

public ApplicationPermissions getApplicationPermissions(boolean ignoreFirewall)

Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getApplicationPermissions() instead.

Queries the application control database and returns the permissions of the calling application.

Parameters:

ignoreFirewall - This parameter is ignored. Previous versions used this parameter to indicate whether the firewall on/off state should be consulted when determining the current setting for the specified permission. Permissions are now always enforced irrespective of the state of the firewall, so this parameter is not used.

Returns:

an ApplicationPermissions object containing the value to which each permission is set in the application control database for the calling application accounting for the firewall state; never returns null

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.7.0

getMaxAllowable

public int getMaxAllowable(int permission)

Returns the least restrictive value that a permission can possibly have for the calling application.

The system administrator is able to set a "maximum" value for each permission. The user is not able to set any permission to be less restrictive than the maximum enforced by the system administrator. This method allows applications to determine if it is even possible to obtain desired permissions and take appropriate action. Requesting a permission via ApplicationPermissionsManager.invokePermissionsRequest(net.rim.device.api.applicationcontrol.ApplicationPermissions) that is less restrictive than that allowed by the system administrator will always return false.

For permissions that can be set on a per-domain basis, invoking this method with such permissions is equivalent to invoking ApplicationPermissionsManager.getMaxAllowable(int, String) and specifying null for domain.

See Per-Domain Permissions for details about domain-specific permissions.

See Permission Values for details about the relative restrictiveness of the various values.

Parameters:

permission - the permission whose maximum value to get; valid values are any of the PERMISSION_ constants defined in ApplicationPermissions.

Returns:

the least restrictive value (see Permission Values for details) of the specified permission of the calling application allowed by the system administrator; will be equal to one of the VALUE_ constants defined in ApplicationPermissions.

Throws:

IllegalArgumentException - if permission is not a valid value.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.1

getMaxAllowable

public int getMaxAllowable(int permission,
                           String domain)

Returns the least restrictive value that a permission can possibly have for a particular domain for the calling application. See the documentation of ApplicationPermissionsManager.getMaxAllowable(int) and ApplicationPermissionsManager.getPermission(int, String) for more information.

See Permission Values for details about the relative restrictiveness of the various values.

See Per-Domain Permissions for details about domain-specific permissions.

Parameters:

permission - the permission whose maximum value to get; valid values are any of the PERMISSION_ constants defined in ApplicationPermissions that can be set on a per-domain basis.

domain - the domain to query; if null get the default value for domains that do not have permissions explicitly set for them.

Returns:

the least restrictive value (see Permission Values for details) of the specified permission of the calling application for the specified domain; will be equal to one of the VALUE_ constants defined in the ApplicationPermissions class.

Throws:

IllegalArgumentException - if permission is not a valid value.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.1

addReasonProvider

public void addReasonProvider(ApplicationDescriptor appDesc,
                              ReasonProvider provider)

Adds a ReasonProvider to the currently running application which will allow descriptive Strings to be added to the application permissions dialog.

Note: the ApplicationDescriptor added must belong to a module found on the triggering call stack to ensure the ReasonProvider will be queried. This check is performed at the time of callback and not the time of addition. The query will be serviced within the ApplicationDescriptor.

Note: duplicate providers are only added once.

Parameters:

appDesc - The ApplicationDescriptor used to service the ReasonProvider

provider - The ReasonProvider to add

Throws:

IllegalArgumentException - if either appDesc or provider are null, or if appDesc is invalid.

See Also:

ReasonProvider

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

removeReasonProvider

public void removeReasonProvider(ReasonProvider provider)

Removes a ReasonProvider from the currently running application.

Parameters:

provider - The ReasonProvider to remove

Throws:

IllegalArgumentException - if provider is null

See Also:

ReasonProvider

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

invokePermissionsRequest

public boolean invokePermissionsRequest(ApplicationPermissions requestedPermissions)

Request application control permissions for the calling application.

An application can request that it be assigned application control permissions by constructing and populating an ApplicationPermissions object and then submitting it by invoking this method. If the application does not already hold all the permissions it requests, the user is presented a screen where they can approve all, some, or none of the supplied application control permissions. The screen is pushed to the top of the display stack and blocks the calling thread until the user finishes processing.

If the current IT Policy settings do not permit some of the requested permissions, then the device ignores those permissions. The request continues with the remaining permissions, and the method returns false.

Any permissions that are approved are applied to the calling application module and all its dependencies.

Parameters:

requestedPermissions - Object containing the permissions to request; must not be null.

Returns:

true if every requested permission is granted to the application (either the application already held all the requested permissions or the user approved all of the requested permissions); false otherwise.

Throws:

NullPointerException - if requestedPermissions is null.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.2.1