net.rim.device.api.userauthenticator
Class SecurityUIManager

java.lang.Object
  net.rim.device.api.userauthenticator.SecurityUIManager

public final class SecurityUIManager
extends Object

This manager class provides simple user-interface services to user authenticators.

Typically, applications are not allowed to interact with the device's user in any way while the device is locked. User authenticators may have a compelling reason to do so, however; this class provides a way for user authenticators to perform interactions with the device's user from the lock screen.

Note: a user authenticator need only make use of a security UI manager if it does not implement the PasswordFrameworkProvider interface. If it does implement that interface, then it will piggy-back on the security framework's standard device password interaction with the user. However, the user authenticator can always make use of the security ui manager provided by the security framework if it wants additional interaction with the device's user.

The security framework provides the user authenticator with a security UI manager object through its invocation of several user authenticator methods. The security UI manager reference passed in is only usable during the execution of those methods; as soon as those methods return, the security framework renders the manager object unusable (thus, there's no point for the authenticator to hold on to a reference to a security UI manager: they are intended only for temporary use).

UserAuthenticator.initializeImpl(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)

When the user or the policy activates the user authenticator, the framework will initialize it, passing in a security UI manager the authenticator can use for any interaction it must do with the UI.

UserAuthenticator.verifyPolicySettingsImpl(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)

When a policy change occurs, there may be details in the policy settings that affect the security framework; for example, a challenge response before communicating with the authenticator might now be mandated. Should a user authenticator's status have changed, it might want to communicate this change to the user, and so the framework will pass in a security UI manager when invoking verifyPolicySettings.

UserAuthenticator.authenticateImpl(net.rim.device.api.userauthenticator.SecurityUIManager, net.rim.device.api.util.DataBuffer, net.rim.device.api.userauthenticator.UserAuthenticatorContextObject)

Whenever a user must authenticate with the user authenticator, the security framework will pass in a security UI manager to the authenticate method.

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 5.0.0

Field Summary
	static int	CANCEL Indication of the dialog is closing because it was canceled
	static int	CLOSE Indication that the dialog closed in the normal way

Method Summary
	void	dismissDialog(int reason) Dismiss the dialog created by SecurityUIManager.showDialog(net.rim.device.api.ui.Manager, boolean).
	int	showDialog(Manager manager, boolean cancelAllowed) Present a dialog to the user.

Methods inherited from class java.lang.Object

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

Field Detail

CLOSE

public static int CLOSE

Indication that the dialog closed in the normal way

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 5.0.0

CANCEL

public static int CANCEL

Indication of the dialog is closing because it was canceled

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 5.0.0

Method Detail

showDialog

public int showDialog(Manager manager,
                      boolean cancelAllowed)

Present a dialog to the user.

To use this method, the invoker may provide any dialog for this manager to show to the user.

Parameters:

manager - UI manager containing the fields and layout for the dialog to show the user.

cancelAllowed - True if the user can close this dialog by Canceling; otherwise, false.

Returns:

SecurityUIManager.CLOSE if the dialog terminated by a simple close; otherwise, SecurityUIManager.CANCEL, if the user closes the dialog by Canceling it.

Throws:

IllegalStateException - when trying to use a disabled SecurityUIManager.

IllegalArgumentException - when the manager passed in 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 5.0.0

dismissDialog

public void dismissDialog(int reason)

Dismiss the dialog created by SecurityUIManager.showDialog(net.rim.device.api.ui.Manager, boolean).

Parameters:

reason - Close reason value (SecurityUIManager.CLOSE or SecurityUIManager.CANCEL).

Throws:

IllegalStateException - when trying to use a disabled SecurityUIManager.

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 5.0.0