SHOW Signed
 

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:

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:
JDE 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)
          Queries the application control database and returns the permissions of the calling application.
 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)
          Queries the application control database and returns the value of a permission of the calling application.
 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)
          Queries the application control database and returns the value of a permission of the calling application for a particular domain.
 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

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.
Since:
JDE 4.5.0
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.

getApplicationPermissions

public ApplicationPermissions getApplicationPermissions()
Queries the application control database and returns the permissions of the calling application.

Note that this method returns to the caller the permissions of the calling application while taking in to account the effects the current state of the firewall may have. The following permissions are typically only checked when the firewall is enabled:

If the firewall is disabled, then these permissions have an implied setting of "allow" and is what would be returned by this method.
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
Since:
JDE 4.2.1
See Also:
getApplicationPermissions(boolean)
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.

getApplicationPermissions

public ApplicationPermissions getApplicationPermissions(boolean ignoreFirewall)
Queries the application control database and returns the permissions of the calling application.

Note that this method provides the caller the ability to retrieve the "raw" permissions of the calling application ignoring the effects the current state of the firewall may have. The following permissions are typically only checked when the firewall is enabled:

If the firewall is disabled, then these permissions have an implied setting of "allow" and is what would be returned by getApplicationPermissions(). This method, however, will only do so if the ignoreFirewall parameter is false.
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 if desired; never returns null
Since:
JDE 4.7.0
See Also:
getApplicationPermissions()
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.

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.
Since:
JDE 4.2.1
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.

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 restrive 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 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 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.
Since:
JDE 4.2.1
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.

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 getMaxAllowable(int) and 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.
Since:
JDE 4.2.1
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.

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 getPermission(int, String) and specifying null for domain. See Per-Domain Permissions for details about domain-specific permissions.

Note that this method returns to the caller the permission setting while taking in to account the effects the current state of the firewall may have. The following permissions are typically only checked when the firewall is enabled:

If the firewall is disabled, then these permissions have an implied setting of "allow" and is what would be returned by this method.
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 accounting for the effects of the firewall state; 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.
Since:
JDE 4.2.1
See Also:
getPermission(int, boolean)
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.

getPermission

public int getPermission(int permission,
                         boolean ignoreFirewall)
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 getPermission(int, String) and specifying null for domain. See Per-Domain Permissions for details about domain-specific permissions.

Note that this method provides the caller the ability to retrieve the "raw" permission setting ignoring the effects the current state of the firewall may have. The following permissions are typically only checked when the firewall is enabled:

If the firewall is disabled, then these permissions have an implied setting of "allow" and is what would be returned by getPermission(int). This method, however, will only do so if the ignoreFirewall parameter is false.
Parameters:
permission - the permission whose value to get; must be equal to one of the permissions constants defined in the ApplicationPermissions class
ignoreFirewall - if true, then the state of the firewall will be ignored when determining the current setting for the specified permission so that the "raw" setting is returned
Returns:
the value of the specified permission of the calling application retrieved from the application control database, accounting for the state of the firewall if desired; 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
Since:
JDE 4.7.0
See Also:
getPermission(int)
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.

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.

Note that this method returns to the caller the permission setting while taking in to account the effects the current state of the firewall may have. The following permissions are typically only checked when the firewall is enabled:

If the firewall is disabled, then these permissions have an implied setting of "allow" and is what would be returned by this method.
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
Since:
JDE 4.2.1
See Also:
getPermission(int, String, boolean)
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.

getPermission

public int getPermission(int permission,
                         String domain,
                         boolean ignoreFirewall)
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.

Note that this method provides the caller the ability to retrieve the "raw" permission setting ignoring the effects the current state of the firewall may have. The following permissions are typically only checked when the firewall is enabled:

If the firewall is disabled, then these permissions have an implied setting of "allow" and is what would be returned by getPermission(int, String). This method, however, will only do so if the ignoreFirewall parameter is false.
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 - if true, then the state of the firewall will be ignored when determining the current setting for the specified permission so that the "raw" setting is returned
Returns:
the value of the specified permission of the calling application for the specified domain retrieved from the application control database, accounting for the state of the firewall if desired; will be equal to one of VALUE_ constants defined in ApplicationPermissions
Throws:
IllegalArgumentException - if permission is not a valid value
Since:
JDE 4.7.0
See Also:
getPermission(int, String)
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.

invokePermissionsRequest

public boolean invokePermissionsRequest(ApplicationPermissions requestedPermissions)
Request application control permissions for the calling application.

An application can request it be assigned certain application control privlages 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 app 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
Since:
JDE 4.2.1
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.

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
Since:
JDE 4.5.0
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.



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.