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

java.lang.Object
  extended by net.rim.device.api.wlan.hotspot.HotspotClient

public abstract class HotspotClient
extends Object

Classes that extend the abstract class HotspotClient can register with the HotspotClientRegistry class and manage connections between the application to which they belong and the system that controls the device's Wi-Fi radio.

Abstract methods

Classes that extend HotspotClient must implement the following methods: Constructors of classes that extend HotspotClient must call the super (HotspotClient) constructor with an instance of HotspotCredentialsAgent and an instance of HotspotAuthenticationAgent.

Optional overrides

The following methods may be overridden:

Final methods

The following methods may be used but not overridden: For more information, please refer to the 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
Category: Signed static int NETWORK_TYPE_AUTOMATIC
          The bit of the network types bitmask that indicates whether the hotspot client supports automatic login type networks.
Category: Signed static int NETWORK_TYPE_MANUAL
          The bit of the network types bitmask that indicates whether the hotspot client supports manual login type networks.
Category: Signed static int URL_FORGOT_PASSWORD
          This URL type is used to construct the bitmask in getAvailableURLs and passed into loadURL when the user clicks the forgot password button.
Category: Signed static int URL_REGISTRATION
          This URL type is used to construct the bitmask in getAvailableURLs and passed into loadURL when the user clicks the sign-up button.
 
Constructor Summary
Category: Signed protected HotspotClient(HotspotCredentialsAgent credentials, HotspotAuthenticationAgent authentication, int networkType)
          Protected constructor used to create a hotspot client.
 
Method Summary
Category: Signed protected  void enable(boolean enable)
          Enables and disables the client.
Category: Signed abstract  String getClientName()
          Retrieves the client's name.
Category: Signed  HotspotAuthenticationAgent getHotspotAuthenticationAgent()
          Retrieves this client's HotspotAuthenticationAgent.
Category: Signed  HotspotCredentialsAgent getHotspotCredentialsAgent()
          Retrieves this client's HotspotCredentialsAgent.
Category: Signed  ApplicationMenuItem[] getMenuItems()
          Retrieves custom menu items from the client.
Category: Signed  int getSupportedNetworkTypes()
          Retrieves a bitmask (int) that indicates which types of network are supported by the client.
Category: Signed abstract  HotspotInfo[] getSupportedNetworks(WLANInfo.WLANAPInfo[] networks)
          Processes scanned networks against client's database and returns only those networks that are supported by the client.
Category: Signed  int getSupportedURLs()
          Retrieves a bitmask (int) that indicates which URLs are available.
Category: Signed  boolean isEnabled()
          Determines whether the client is enabled in the system or not.
Category: Signed  void loadURL(int type)
          If the client supports one or more URLs then it must override this method.
Category: Signed protected  boolean setSupportedNetworkTypes(int type)
          Sets supported network types.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

NETWORK_TYPE_AUTOMATIC

public static final int NETWORK_TYPE_AUTOMATIC
The bit of the network types bitmask that indicates whether the hotspot client supports automatic login type networks.

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_TYPE_MANUAL

public static final int NETWORK_TYPE_MANUAL
The bit of the network types bitmask that indicates whether the hotspot client supports manual login type networks.

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

URL_REGISTRATION

public static final int URL_REGISTRATION
This URL type is used to construct the bitmask in getAvailableURLs and passed into loadURL when the user clicks the sign-up button.

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

URL_FORGOT_PASSWORD

public static final int URL_FORGOT_PASSWORD
This URL type is used to construct the bitmask in getAvailableURLs and passed into loadURL when the user clicks the forgot password button.

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

HotspotClient

protected HotspotClient(HotspotCredentialsAgent credentials,
                        HotspotAuthenticationAgent authentication,
                        int networkType)
                 throws IllegalArgumentException
Protected constructor used to create a hotspot client. This constructor must be called when initializing the client.

Parameters:
credentials - implementation of HotspotCredentialsAgent.
authentication - implementation of of HotspotAuthenticationAgent.
networkType - bitmask that indicates which network types are supported, constructed using NETWORK_TYPE_ constants.
Throws:
IllegalArgumentException - HotspotCredentialsAgent or HotspotAuthenticationAgent is null, or networkType is 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


Method Detail

getSupportedURLs

public int getSupportedURLs()
Retrieves a bitmask (int) that indicates which URLs are available.

By default, this method returns 0.

Returns:
int bitmask indicating supported URLs constructed by using the URL_ constants.
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

loadURL

public void loadURL(int type)
If the client supports one or more URLs then it must override this method. The type is one of the URL_ constants.

It is highly recommended that the client uses a URL where the user cannot complete login, so that the user will be forced to use the Wi-Fi credentials screen to enter credentials to be updated in the client.

Parameters:
type - one of the URL_ type constants
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

getSupportedNetworkTypes

public final int getSupportedNetworkTypes()
Retrieves a bitmask (int) that indicates which types of network are supported by the client.

Returns:
int bitmask indicating supported networks
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

getMenuItems

public ApplicationMenuItem[] getMenuItems()
Retrieves custom menu items from the client.

By default, this method returns null.

Returns:
array of ApplicationMenuItem objects to be used when user opens client's menu.
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

getSupportedNetworks

public abstract HotspotInfo[] getSupportedNetworks(WLANInfo.WLANAPInfo[] networks)
                                            throws HotspotException
Processes scanned networks against client's database and returns only those networks that are supported by the client. The order of the returned networks defines the order of preference for usage.

Parameters:
networks - array of scanned networks
Returns:
array of supported hotspots or a null if it does not support any of the networks.
Throws:
HotspotException - with HotspotException#DATABASE_UNAVAILABLE flag if database is unavailable or with HotspotException#HOTSPOT_CLIENT_DISABLED flag if client is disabled.
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

getClientName

public abstract String getClientName()
Retrieves the client's name.

During installation, client's name will be as the profile name. If a profile with the same name already exists in the database, then the new profile name will be enumerated.

Returns:
profile name of the client.
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

setSupportedNetworkTypes

protected final boolean setSupportedNetworkTypes(int type)
Sets supported network types.

Parameters:
type - bitmask for supported networks. The bitmask must be constructed using NETWORK_TYPE_ constants.
Returns:
true if update has been performed, or false if update cannot be performed.
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

enable

protected final void enable(boolean enable)
Enables and disables the client. When the client is disabled, the system does not prompt the client for supported network.

By default, the client is enabled.

Parameters:
enabled - true to enable client and false to disable client.
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

isEnabled

public final boolean isEnabled()
Determines whether the client is enabled in the system or not.

Returns:
true if the client is enabled and false if the client is disabled.
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

getHotspotAuthenticationAgent

public final HotspotAuthenticationAgent getHotspotAuthenticationAgent()
Retrieves this client's HotspotAuthenticationAgent.

Returns:
instance of HotspotAuthenticationAgent used to initialize the 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

getHotspotCredentialsAgent

public final HotspotCredentialsAgent getHotspotCredentialsAgent()
Retrieves this client's HotspotCredentialsAgent.

Returns:
instance of HotspotCredentialsAgent used to initialize the 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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal