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

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

public abstract class HotspotAuthenticationAgent
extends Object

Hotspot authentication agents serve as intermediaries between client applications and hotpost status listeners (HotspotStatusListener), initiating login/logout and monitoring the state of the client application's connections to various hotspots. 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.

Abstract methods

The following methods must be implemented by the client:

• login
• logout
• cancelLogin
• getSessionState

Final methods

The following methods manage listeners of the authentication agent:

• addListener
• removeListener
• notifyListeners

Additional methods

• probeNetwork - perform network probing. This method is not supported in the Hotspot API version 1.0.
• cancelProbeNetwork - cancel network probing. This method is not supported in the Hotspot API version 1.0.

Tip: Use HotspotClientRegistry.isFeatureSupported to check if probing feature is supported.

If the client wishes to use the methods above then it must implement HotspotStatusListener to use as a parameter.

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 byte	STATE_CANCELLING_LOGIN Client is attempting to cancel login.
	static byte	STATE_LOGGED_IN Client has logged in successfully.
	static byte	STATE_LOGGED_OUT Client is logged out.
	static byte	STATE_LOGGING_IN Client is attempting to login.
	static byte	STATE_LOGGING_OUT Client is attempting to logout.
	static byte	STATE_PROBING_NETWORK Client is probing a network.

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

Method Summary
	void	addListener(HotspotStatusListener listener) Adds a hotspot status listener.
	abstract void	cancelLogin(HotspotInfo hotspot) Cancels login to a hotspot.
	void	cancelProbeNetwork() Cancels network probing.
	abstract int	getSessionState() Retrieves the session state of the authentication agent.
	abstract void	login(HotspotInfo hotspot) Initiates login to a hotspot.
	abstract void	logout(HotspotInfo hotspot) Initiates logout from a hotspot.
	protected void	notifyListeners(AuthenticationStatusEvent event) This method must be used to update all listeners during any hotspot process.
	void	probeNetwork(HotspotInfo hotspot) Performs network probing.
	void	removeListener(HotspotStatusListener listener) Removes a hotspot status listener from the agent.

Methods inherited from class java.lang.Object

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

Field Detail

STATE_LOGGED_OUT

public static final byte STATE_LOGGED_OUT

Client is logged out. This should be the state when the client idles.

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

STATE_LOGGING_IN

public static final byte STATE_LOGGING_IN

Client is attempting to login.

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

STATE_LOGGED_IN

public static final byte STATE_LOGGED_IN

Client has logged in successfully.

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

STATE_LOGGING_OUT

public static final byte STATE_LOGGING_OUT

Client is attempting to logout.

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

STATE_CANCELLING_LOGIN

public static final byte STATE_CANCELLING_LOGIN

Client is attempting to cancel login.

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

STATE_PROBING_NETWORK

public static final byte STATE_PROBING_NETWORK

Client is probing a network.

This state is not supported in the Hotspot API version 1.0. Use HotspotClientRegistry.isFeatureSupported(byte) to check if network probing is supported.

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

HotspotAuthenticationAgent

public HotspotAuthenticationAgent()

Creates a new instance of HotspotAuthenticationAgent.

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

login

public abstract void login(HotspotInfo hotspot)

Initiates login to a hotspot.

When this method is called, it must set the hotspot authentication agent's session state to HotspotAuthenticationAgent.STATE_LOGGING_IN. After a successful login, the session state must be set to HotspotAuthenticationAgent.STATE_LOGGED_IN and the client must update its listeners using the notifyListeners method.

Parameters:

hotspot - currently associated hotspot information.

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

logout

public abstract void logout(HotspotInfo hotspot)

Initiates logout from a hotspot.

When this method is called, it must set the hotspot authentication agent's session state to HotspotAuthenticationAgent.STATE_LOGGING_OUT. After a successful logout, the session state must be set to HotspotAuthenticationAgent.STATE_LOGGED_OUT and the client must update its listeners using the notifyListeners method.

Parameters:

hotspot - currently associated hotspot information

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

getSessionState

public abstract int getSessionState()

Retrieves the session state of the authentication agent.

Returns:

One of the STATE_ constants defined 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

cancelLogin

public abstract void cancelLogin(HotspotInfo hotspot)

Cancels login to a hotspot.

When this method is called, the client must set the hotspot authentication agent's session state to HotspotAuthenticationAgent.STATE_CANCELLING_LOGIN. After a successful cancellation, the session state must be set to HotspotAuthenticationAgent.STATE_LOGGED_OUT and the client must update its listeners using the notifyListeners method.

Parameters:

hotspot - currently associated hotspot information.

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

probeNetwork

public void probeNetwork(HotspotInfo hotspot)

Performs network probing.

This method is not supported in the Hotspot API version 1.0. Use HotspotClientRegistry.isFeatureSupported(byte) to check if network probing is supported.

When this method is called, it must set the hotspot authentication agent's session state to HotspotAuthenticationAgent.STATE_PROBING_NETWORK. After probing is complete, the session state must be set to HotspotAuthenticationAgent.STATE_LOGGED_OUT.

Parameters:

hotspot - currently associated network

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

cancelProbeNetwork

public void cancelProbeNetwork()

Cancels network probing.

This method is not supported in the Hotspot API version 1.0. Use HotspotClientRegistry.isFeatureSupported(byte) to check if network probing is supported.

After cancellation is complete, the session state must be set to HotspotAuthenticationAgent.STATE_LOGGED_OUT.

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

addListener

public final void addListener(HotspotStatusListener listener)

Adds a hotspot status listener. Client must use notifyListeners when status is available.

Parameters:

listener - HotspotStatusListener listener for hotspot status updates.

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

notifyListeners

protected final void notifyListeners(AuthenticationStatusEvent event)

This method must be used to update all listeners during any hotspot process.

Parameters:

event - AuthenticationStatusEvent used to update listeners

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

removeListener

public final void removeListener(HotspotStatusListener listener)

Removes a hotspot status listener from the agent.

Parameters:

listener - HotspotStatusListener instance to be removed

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