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

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

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
Category: Signed static byte NETWORK_DELAY_FEATURE
          Used by HotspotClientRegistry.isFeatureSupported(byte) to determine whether delayed login into the network is supported.
Category: Signed static byte PROBING_FEATURE
          Used by HotspotClientRegistry.isFeatureSupported(byte) to determine whether network probing is supported.
 
Method Summary
Category: Signed static void add(HotspotClient client, ApplicationDescriptor application)
          Registers a hotspot client with the device's operating system.
Category: Signed static int getMajorAPIVersion()
          Returns the Hotspot API's major version number.
Category: Signed static int getMinorAPIVersion()
          Returns the Hotspot API's minor version number.
Category: Signed  boolean isFeatureSupported(byte feature)
          Determines whether a given feature is supported by the Hotspot API.
Category: Signed 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 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





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.