net.rim.device.api.applicationcontrol
Class ApplicationPermissionsManager

java.lang.Object
  extended by 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:

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
Category: Signed  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.
Category: Signed  ApplicationPermissions getApplicationPermissions()
          Queries the application control database and returns the permissions of the calling application.
Category: Signed  ApplicationPermissions getApplicationPermissions(boolean ignoreFirewall)
          Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getApplicationPermissions() instead.
Category: Signed static ApplicationPermissionsManager getInstance()
          Returns the singleton instance of this class.
Category: Signed  int getMaxAllowable(int permission)
          Returns the least restrictive value that a permission can possibly have for the calling application.
Category: Signed  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.
Category: Signed  int getPermission(int permission)
          Queries the application control database and returns the value of a permission of the calling application.
Category: Signed  int getPermission(int permission, boolean ignoreFirewall)
          Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getPermission(int) instead.
Category: Signed  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.
Category: Signed  int getPermission(int permission, String domain, boolean ignoreFirewall)
          Deprecated. As of version 5.0. Use ApplicationPermissionsManager.getPermission(int,String) instead.
Category: Signed  boolean invokePermissionsRequest(ApplicationPermissions requestedPermissions)
          Request application control permissions for the calling application.
Category: Signed  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 it be assigned certain application control privileges by filling out an ApplicationPermissions object, then submitting it to this method. The user will be presented the application control screen, where they can review, and if they choose, save the supplied permissions. The screen will be placed on top of the calling application and will block the calling thread until the user finishes processing.

Checks will be performed against IT Policy, and the user will be prompted if the requested settings will not be allowed under the existing policy. (The application control screen does not allow them to save settings that conflict with the IT policy).

Note: If the calling application module is part of an application group, the requested permissions are applied to the ENTIRE group.

Parameters:
requestedPermissions - the permissions to request
Returns:
true if the user accepts all of the requested permissions, or false if the user or device policies reject at least one of the requested permissions
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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.