net.rim.device.api.wlan.hotspot
Class HotspotCredentialsAgent

java.lang.Object
  net.rim.device.api.wlan.hotspot.HotspotCredentialsAgent

All Implemented Interfaces:

Persistable

public abstract class HotspotCredentialsAgent
extends Object
implements Persistable

HotspotCredentialsAgent is an abstract class that must be extended by the class that manages a hotspot client's credentials. The client must pass an instance of this class to its HotspotClient.HotspotClient(net.rim.device.api.wlan.hotspot.HotspotCredentialsAgent, net.rim.device.api.wlan.hotspot.HotspotAuthenticationAgent, int) constructor. The client can either extend this class itself or use system's implementation by calling HotspotCredentialsAgent.getSystemHotspotCredentialsAgent().

Abstract methods

Classes that extend HotspotCredentialsAgent must implement the following methods:

• HotspotCredentialsAgent.getCredentialsControlPreference()
• HotspotCredentialsAgent.getPassword()
• HotspotCredentialsAgent.getUsername()
• HotspotCredentialsAgent.setCredentialsControlPreference(int)
• HotspotCredentialsAgent.setPassword(java.lang.String)
• HotspotCredentialsAgent.setUsername(java.lang.String)

Additional methods

• The client may override HotspotCredentialsAgent.validateCredentials(java.lang.String, java.lang.String). Default implementation will return valid credentials for any input.
• The client may use HotspotCredentialsAgent.getSystemHotspotCredentialsAgent() to retrieve new instance of system's implementation.

For more information, please refer to API overview section provided in HotspotClientRegistry.

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	PREFERENCE_DEFAULT The default setting of the credentials agent's preferences bitmask.
	static int	PREFERENCE_HIDDEN_PASSWORD When this bit of the preferences bitmask is set, the password field is invisible.
	static int	PREFERENCE_HIDDEN_USERNAME When this bit of the preferences bitmask is set, the username field is invisible.
	static int	PREFERENCE_IMMUTABLE_PASSWORD When this bit of the preferences bitmask is set, the user is not allowed to modify their password.
	static int	PREFERENCE_IMMUTABLE_USERNAME When this bit of the preferences bitmask is set, the user is not allowed to modify their username.

Constructor Summary
	HotspotCredentialsAgent() Creates a new instance of HotspotCredentialsAgent.

Method Summary
	abstract int	getCredentialsControlPreference() Returns the credentials agent's preferences bitmask (int), which indicates which credentials the user may see and which they can modify.
	abstract String	getPassword() Retrieves the password for login.
	static HotspotCredentialsAgent	getSystemHotspotCredentialsAgent() Retrieves new instance of the system implementation of this abstract class.
	abstract String	getUsername() Retrieves the user's username for login.
	protected abstract void	setCredentialsControlPreference(int control) Sets the credentials agent's preferences bitmask, which indicates which credentials the user may see and which they can modify.
	abstract void	setPassword(String password) Sets a new password.
	abstract void	setUsername(String username) Sets a new username.
	boolean	validateCredentials(String username, String password) Validates the credentials entered into the UI by the user.

Methods inherited from class java.lang.Object

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

Field Detail

PREFERENCE_DEFAULT

public static final int PREFERENCE_DEFAULT

The default setting of the credentials agent's preferences bitmask. This setting causes the user's username and password to be both visible and mutable.

See Also:

Constant Field Values

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

PREFERENCE_IMMUTABLE_USERNAME

public static final int PREFERENCE_IMMUTABLE_USERNAME

When this bit of the preferences bitmask is set, the user is not allowed to modify their username.

See Also:

Constant Field Values

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

PREFERENCE_IMMUTABLE_PASSWORD

public static final int PREFERENCE_IMMUTABLE_PASSWORD

When this bit of the preferences bitmask is set, the user is not allowed to modify their password.

See Also:

Constant Field Values

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

PREFERENCE_HIDDEN_USERNAME

public static final int PREFERENCE_HIDDEN_USERNAME

When this bit of the preferences bitmask is set, the username field is invisible.

See Also:

Constant Field Values

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

PREFERENCE_HIDDEN_PASSWORD

public static final int PREFERENCE_HIDDEN_PASSWORD

When this bit of the preferences bitmask is set, the password field is invisible.

See Also:

Constant Field Values

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

Constructor Detail

HotspotCredentialsAgent

public HotspotCredentialsAgent()

Creates a new instance of HotspotCredentialsAgent.

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

getUsername

public abstract String getUsername()
                            throws HotspotException

Retrieves the user's username for login.

Returns:

username to be used for login.

Throws:

HotspotException - thrown with HotspotException#CREDENTIALS_STORAGE_UNAVAILABLE when the credentials storage is unavailable.

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

getPassword

public abstract String getPassword()
                            throws HotspotException

Retrieves the password for login.

Returns:

password to be used for login.

Throws:

HotspotException - thrown with HotspotException#CREDENTIALS_STORAGE_UNAVAILABLE when the credentials storage is unavailable.

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

getCredentialsControlPreference

public abstract int getCredentialsControlPreference()

Returns the credentials agent's preferences bitmask (int), which indicates which credentials the user may see and which they can modify.

By default, the user can both see and modify their username and password.

Returns:

bitmask for permitted credentials control using PREFERENCE_ constants in this 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 5.0.0

setCredentialsControlPreference

protected abstract void setCredentialsControlPreference(int control)

Sets the credentials agent's preferences bitmask, which indicates which credentials the user may see and which they can modify.

The parameter must be a bitmask assembled using the PREFERENCE_ constants:

• If the HotspotCredentialsAgent.PREFERENCE_IMMUTABLE_USERNAME bit is set then the user will not be allow to modify the username.
• If the HotspotCredentialsAgent.PREFERENCE_IMMUTABLE_PASSWORD bit is set then the user will not be allow to modify the password.
• If the HotspotCredentialsAgent.PREFERENCE_HIDDEN_USERNAME bit is set then the user interface will not show the username field to the user.
• If the HotspotCredentialsAgent.PREFERENCE_HIDDEN_PASSWORD bit is set then the user interface will not show the password field to the user.

HotspotCredentialsAgent.PREFERENCE_DEFAULT may be used for default credentials bitmask.

The resulting credentials preferences bitmask can be retrieved using HotspotCredentialsAgent.getCredentialsControlPreference().

Parameters:

control - bitmask for permitted credentials control.

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

validateCredentials

public boolean validateCredentials(String username,
                                   String password)

Validates the credentials entered into the UI by the user. By default, this method always returns true.

The client may require the user's credentials to be in a specific format (i.e. email for username). Credentials will be updated through the UI only if they are valid.

Parameters:

username - new username.

password - new password.

Returns:

true if credentials are valid, false if credentials are invalid.

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

setUsername

public abstract void setUsername(String username)
                          throws HotspotException

Sets a new username.

Parameters:

username - new username.

Throws:

HotspotException - thrown with HotspotException#CREDENTIALS_STORAGE_UNAVAILABLE when the credentials storage is unavailable.

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

setPassword

public abstract void setPassword(String password)
                          throws HotspotException

Sets a new password.

Parameters:

password - new password.

Throws:

HotspotException - thrown with HotspotException#CREDENTIALS_STORAGE_UNAVAILABLE when if the credentials storage is unavailable.

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

getSystemHotspotCredentialsAgent

public static HotspotCredentialsAgent getSystemHotspotCredentialsAgent()

Retrieves new instance of the system implementation of this abstract class.

Returns:

system's implementation of this abstract class, or null if Wi-Fi framework is not on the device.

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