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

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

• getClientName
• getSupportedNetworks

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:

• getMenuItems
• getSupportedURLs
• loadURL

Final methods

The following methods may be used but not overridden:

• HotspotClient.getHotspotCredentialsAgent()
• HotspotClient.getHotspotAuthenticationAgent()
• HotspotClient.getSupportedNetworkTypes()
• HotspotClient.setSupportedNetworkTypes(int)
• HotspotClient.enable(boolean)
• HotspotClient.isEnabled()

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
	static int	NETWORK_TYPE_AUTOMATIC The bit of the network types bitmask that indicates whether the hotspot client supports automatic login type networks.
	static int	NETWORK_TYPE_MANUAL The bit of the network types bitmask that indicates whether the hotspot client supports manual login type networks.
	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.
	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
	protected	HotspotClient(HotspotCredentialsAgent credentials, HotspotAuthenticationAgent authentication, int networkType) Protected constructor used to create a hotspot client.

Method Summary
	protected void	enable(boolean enable) Enables and disables the client.
	abstract String	getClientName() Retrieves the client's name.
	HotspotAuthenticationAgent	getHotspotAuthenticationAgent() Retrieves this client's HotspotAuthenticationAgent.
	HotspotCredentialsAgent	getHotspotCredentialsAgent() Retrieves this client's HotspotCredentialsAgent.
	ApplicationMenuItem[]	getMenuItems() Retrieves custom menu items from the client.
	int	getSupportedNetworkTypes() Retrieves a bitmask (int) that indicates which types of network are supported by the client.
	abstract HotspotInfo[]	getSupportedNetworks(WLANInfo.WLANAPInfo[] networks) Processes scanned networks against client's database and returns only those networks that are supported by the client.
	int	getSupportedURLs() Retrieves a bitmask (int) that indicates which URLs are available.
	boolean	isEnabled() Determines whether the client is enabled in the system or not.
	void	loadURL(int type) If the client supports one or more URLs then it must override this method.
	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.

• If the HotspotClient.URL_REGISTRATION bit of the bitmask is set, the client supports registration URL.
• If the HotspotClient.URL_FORGOT_PASSWORD bit of the bitmask is set, the client supports forgot password URL.

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.

• If the HotspotClient.NETWORK_TYPE_AUTOMATIC bit of the bitmask is set, the client supports automatic login networks.
• If the HotspotClient.NETWORK_TYPE_MANUAL bit of the bitmask is set, the client supports manual login networks.
• If the HotspotClient.NETWORK_TYPE_DEFAULT_TO_MANUAL bit of the bitmask is set then the profile which represents automatic login networks will be set to manual login type by default. The user has the ability to change it back to automatic, unlike just manual login networks type where the user is not allowed to change the profile to automatic. This bit will be ignored if NETWORK_TYPE_AUTOMATIC is not set.

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