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

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

public final class HotspotClientRegistry
extends Object

The HotspotClientRegistry allows client applications to add themselves to and remove themselves from the system which controls the device's Wi-Fi radio.

To register with the system, a client application must be able to provide its own HotspotClient implementation and ApplicationDescriptor. Note that one of the client's classes must extend Application in order to generate a valid ApplicationDescriptor. The Application instance must also call Application.enterEventDispatcher() to receive commands from the system.

Overview of Hotspot API

Configuration and Registration

• The client must extend the following classes: HotspotClient, HotspotAuthenticationAgent, and Application.
• The client may also extend HotspotCredentialsAgent to implement its credentials database or use system's implementation.
• If client wishes to implement its own database, it may still use system's implementation by calling HotspotCredentialsAgent.getSystemHotspotCredentialsAgent().
• When creating the implementation of HotspotClient, the client must call the super's constructor with instances of HotspotCredentialsAgent and HotspotAuthenticationAgent.
• Once the HotspotClient is created, it can be register using HotspotClientRegistry.add(net.rim.device.api.wlan.hotspot.HotspotClient, net.rim.device.api.system.ApplicationDescriptor) method.
• At this point, the system will notify the user that new client is registered and wait for user to invoke the installation wizard.
• During the installation, the wizard will collect user credentials (if they are visible and mutable) and then create 1 or 2 Wi-Fi profiles representing the client based on the supported network types (HotspotClient.getSupportedNetworkTypes() is used to determine the supported types).
• The client may set credentials or credential permission control at any point using the methods available in HotspotCredentialsAgent

Matching Supported Networks and Associating

When Wi-Fi radio is scanning, the following sequence occurs:

1. The system detects access points and packages each result into WLANInfo.WLANAPInfo.
2. The system passes an array of WLANAPInfo to the hotspot client application using HotspotClient.getSupportedNetworks(net.rim.device.api.system.WLANInfo.WLANAPInfo[]). Note: In Hotspot API 1.0., only open security type (no layer 2 security) APs will be passed to the hotspot clients.
3. The client matches the networks against its database and returns an array of matched APs, which is an array of HotspotInfo.
   The order of the returned networks by the client defines the order of preference for usage.
4. The client may configure additional properties in HotspotInfo for the hotspot (see class' documentation).
5. Based on Wi-Fi profiles prioritization, the system will decide when to associate to a supported network.

Authenticating into a Hotspot

After successful association, the following flow takes place:

1. The system will add a listener using HotspotAuthenticationAgent.addListener(net.rim.device.api.wlan.hotspot.HotspotStatusListener).
2. If the network is manual login type and the profile was recently used, then HotspotAuthenticationAgent.verifySessionStatus(net.rim.device.api.wlan.hotspot.HotspotInfo) will be invoked. This will prevent from notifying the user with a login notification if the session is still logged in after re-entering the coverage zone.
3. When it is time to login, HotspotAuthenticationAgent.login(net.rim.device.api.wlan.hotspot.HotspotInfo) will be invoked.
4. In the case where canceling login is required, HotspotAuthenticationAgent.cancelLogin(net.rim.device.api.wlan.hotspot.HotspotInfo) will be invoked.
5. In the case where logout is required, HotspotAuthenticationAgent.logout(net.rim.device.api.wlan.hotspot.HotspotInfo) will be invoked.
6. The client must update the status of hotspot operations using HotspotAuthenticationAgent.notifyListeners(net.rim.device.api.wlan.hotspot.AuthenticationStatusEvent).
7. After a successful logout, the system will remove the listener from HotspotAuthenticationAgent.

Note: Network probing functions are not supported in the Hotspot API version 1.0. Use HotspotClientRegistry.isFeatureSupported(byte) to check if probing feature is supported.

User Interface Interactions:

If a client wishes to have custom menu items, then it may override the HotspotClient.getMenuItems() method.

For credentials control (what the user can see and modify), the client may set the permissions using a bitmask in HotspotCredentialsAgent.setCredentialsControlPreference(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.

Since:

BlackBerry API 5.0.0

Field Summary
	static byte	NETWORK_DELAY_FEATURE Used by HotspotClientRegistry.isFeatureSupported(byte) to determine whether delayed login into the network is supported.
	static byte	PROBING_FEATURE Used by HotspotClientRegistry.isFeatureSupported(byte) to determine whether network probing is supported.

Method Summary
	static void	add(HotspotClient client, ApplicationDescriptor application) Registers a hotspot client with the device's operating system.
	static int	getMajorAPIVersion() Returns the Hotspot API's major version number.
	static int	getMinorAPIVersion() Returns the Hotspot API's minor version number.
	static boolean	isFeatureSupported(byte feature) Determines whether a given feature is supported by the Hotspot API.
	static void	remove(HotspotClient client) Removes a client from the registry.

Methods inherited from class java.lang.Object

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

Field Detail

PROBING_FEATURE

public static final byte PROBING_FEATURE

Used by HotspotClientRegistry.isFeatureSupported(byte) to determine whether network probing is supported. if the network probing is not supported, HotspotInfo.PROBE_NETWORK_FLAG is used to determine whether or not the network needs probing. The probing feature is not supported in version 1.0.

HotspotAuthenticationAgent.probeNetwork and HotspotAuthenticationAgent.cancelProbeNetwork are used to start/stop probing. During probing, the client is expected to update the status using the STATUS_PROBE_ constants in HotspotStatusListener.

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

NETWORK_DELAY_FEATURE

public static final byte NETWORK_DELAY_FEATURE

Used by HotspotClientRegistry.isFeatureSupported(byte) to determine whether delayed login into the network is supported.

To use this feature, HotspotInfo.PROPERTY_LOGIN_DELAY should be set to the desired delay time before the system attempts to login to any automatic login networks' hotspots.

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

Method Detail

add

public static void add(HotspotClient client,
                       ApplicationDescriptor application)
                throws IllegalArgumentException,
                       UnsupportedOperationException

Registers a hotspot client with the device's operating system.

Parameters:

client - implementation of HotspotClient abstract class.

application - ApplicationDescriptor of the client application.

Throws:

IllegalArgumentException - thrown when ApplicationDescriptor is invalid.

UnsupportedOperationException - thrown when API is not active.

ControlledAccessException - thrown when the calling process does not have the necessary privileges.

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

remove

public static void remove(HotspotClient client)
                   throws IllegalArgumentException,
                          UnsupportedOperationException

Removes a client from the registry. Any client data on the device associated with the client is also removed.

Parameters:

client - implementation of HotspotClient abstract class.

Throws:

IllegalArgumentException - thrown when hotspot client is not registered.

UnsupportedOperationException - thrown when API is not active.

ControlledAccessException - thrown when the calling process does not have the necessary privileges.

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

getMajorAPIVersion

public static int getMajorAPIVersion()

Returns the Hotspot API's major version number.

Returns:

version major version of the Hotspot API.

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

getMinorAPIVersion

public static int getMinorAPIVersion()

Returns the Hotspot API's minor version number.

Returns:

version minor version of the Hotspot API.

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

isFeatureSupported

public static boolean isFeatureSupported(byte feature)

Determines whether a given feature is supported by the Hotspot API.

Parameters:

feature - one of the FEATURE_ constants defined in this class.

Returns:

true if the feature is supported by the Hotspot API, false otherwise.

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