net.rim.device.api.system
Class CoverageInfo

java.lang.Object
  |
  +--net.rim.device.api.system.CoverageInfo

public class CoverageInfo

extends Object

Provides information on what type of coverage is currently available to a BlackBerry device, taking into account radio coverage, serial bypass and Bluetooth coverage, and any required service book records. A listener interface is provided for receiving notifications of changes in coverage status.

The following two conditions must be true before a device is considered to be in sufficient coverage for a connection type:

1. The device has sufficient radio/serial bypass/Bluetooth coverage for that connection type.
2. All service book records required for that connection type are routable.

Since:

JDE 4.2.0

See Also:

CoverageStatusListener

Field Summary

static int	COVERAGE_CARRIER Flag indicating the device has sufficient coverage for the following connection types: HTTP over WAP via WAP gateway; Direct HTTP / TCP via carrier IP gateway; Direct UDP via carrier or ASP gateway.
static int	COVERAGE_MDS Flag indicating the device has sufficient coverage for the following connection types: HTTP over IPPP via BES/MDS.
static int	COVERAGE_NONE Flag indicating the device does not have sufficient coverage for any connection types.

Method Summary

static void	addListener(Application app, CoverageStatusListener listener) Adds a listener for changes in coverage status.
static void	addListener(CoverageStatusListener listener) Adds a listener for changes in coverage status.
static int	getCoverageStatus() Retrieves the current coverage status.
static boolean	isCoverageSufficient(int coverageType) Determines whether or not the device has the type of coverage specified by coverageType.
static boolean	isOutOfCoverage() Determines whether or not the device is completely out of coverage.
static void	removeListener(Application app, CoverageStatusListener listener) Removes listener from the provided application's list of listeners.
static void	removeListener(CoverageStatusListener listener) Removes listener from the calling application's list of listeners.

Methods inherited from class java.lang.Object

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

Field Detail

COVERAGE_NONE

public static final int COVERAGE_NONE

Flag indicating the device does not have sufficient coverage for any connection types.

Since:

JDE 4.2.0

COVERAGE_CARRIER

public static final int COVERAGE_CARRIER

Flag indicating the device has sufficient coverage for the following connection types:

• HTTP over WAP via WAP gateway;
• Direct HTTP / TCP via carrier IP gateway;
• Direct UDP via carrier or ASP gateway.

Since:

JDE 4.2.0

COVERAGE_MDS

public static final int COVERAGE_MDS

Flag indicating the device has sufficient coverage for the following connection types:

• HTTP over IPPP via BES/MDS.

Since:

JDE 4.2.0

Method Detail

addListener

public static void addListener(CoverageStatusListener listener)

Adds a listener for changes in coverage status. The listener notifications will be processed by the calling application's event thread. If the calling application has already registered listener, then this method does nothing.

Parameters:

listener - Listener for changes in coverage status.

Throws:

NullPointerException - if listener is null.

IllegalStateException - if this method is called when there is no Application object in the calling process.

Since:

JDE 4.2.0

addListener

public static void addListener(Application app,
                               CoverageStatusListener listener)

Adds a listener for changes in coverage status. The listener notifications will be processed by the provided application's event thread. If the provided application has already registered listener, then this method does nothing.

Parameters:

app - The application whose event thread will process the notifications sent to listener.

listener - Listener for changes in coverage status.

Throws:

NullPointerException - if app or listener is null.

Since:

JDE 4.2.0

removeListener

public static void removeListener(CoverageStatusListener listener)

Removes listener from the calling application's list of listeners. If listener is null or is not on the calling application's list of listeners, then this method does nothing.

Parameters:

listener - Listener for changes in coverage status.

Throws:

IllegalStateException - If this method is called when there is no Application object in the calling process.

Since:

JDE 4.2.0

removeListener

public static void removeListener(Application app,
                                  CoverageStatusListener listener)

Removes listener from the provided application's list of listeners. If listener is null or is not on the provided application's list of listeners, then this method does nothing.

Parameters:

app - The application whose event thread will no longer process the notifications sent to listener.

listener - Listener for changes in coverage status.

Throws:

NullPointerException - if app is null.

Since:

JDE 4.2.0

getCoverageStatus

public static int getCoverageStatus()

Retrieves the current coverage status.

Note that a COVERAGE_* flag being set in the return value of this method is not a guarantee that a connection of that type will succeed. For example, it is possible for the device to lose coverage between the invocation of this method and a subsequent connection attempt, or for a destination server to be unresponsive.

Returns:

A bitwise OR of one or more of the COVERAGE_* flags.

Since:

JDE 4.2.0

isCoverageSufficient

public static boolean isCoverageSufficient(int coverageType)

Determines whether or not the device has the type of coverage specified by coverageType. If coverageType is COVERAGE_NONE, this method always returns false.

Note that a return value of true for a given COVERAGE_* flag is not a guarantee that a connection of that type will succeed. For example, it is possible for the device to lose coverage between the invocation of this method and a subsequent connection attempt, or for a destination server to be unresponsive.

Parameters:

coverageType - One of the COVERAGE_* flags.

Returns:

True if the device has the type of coverage specified by coverageType; otherwise false.

Throws:

IllegalArgumentException - if coverageType is not one of the COVERAGE_* flags.

Since:

JDE 4.2.0

isOutOfCoverage

public static boolean isOutOfCoverage()

Determines whether or not the device is completely out of coverage.

Returns:

True if the device does not have sufficient coverage for any connection types; otherwise false.

Since:

JDE 4.2.0