net.rim.device.api.system
Class CoverageInfo

java.lang.Object
  net.rim.device.api.system.CoverageInfo

public class CoverageInfo
extends Object

Provides information on the type of coverage that is currently available to a BlackBerry device over all supported Wireless Access Families (WAFs), as well as serial bypass, and Bluetooth®. The CoverageStatusListener listener interface receives notifications of changes in this aggregate coverage status.

Before a device is considered to be in sufficient coverage for a connection type, the following two conditions must be met:

1. the device has sufficient radio coverage or a serial bypass connection (such as a USB or Bluetooth connection) for that connection type
2. all service book records required for that connection type are routable

Note that being in coverage for a connection type is not a guarantee that such a connection attempt will succeed. For example, if the device is not properly provisioned for a connection type, then connection attempts of that type fail even though there might be sufficient coverage. Also, unresponsive destination servers can cause connection attempts to fail even though the device may have sufficient coverage for the connection is it attempting.

For more information on Bluetooth serial bypass, visit www.blackberry.com/go/developerkb and search for the keyword ServiceRouting API.

See Also:

CoverageStatusListener, RadioInfo

Since:

BlackBerry API 4.2.0

Field Summary
static int	COVERAGE_BIS_B Flag indicating the device has sufficient coverage for HTTP over IPPP via Public MDS connection type.
static int	COVERAGE_DIRECT Flag indicating the device has sufficient coverage for the following connection types: Direct HTTP / TCP via WiFi, wireless service provider IP gateway, or HTTP over WAP via WAP Gateway Direct User Datagram Protocol (UDP) via wireless service provider, ASP gateway or via WiFi
static int	COVERAGE_MDS Flag indicating the device has sufficient coverage for HTTP over IPPP via BlackBerry Enterprise Server/BlackBerry MDS connection type.
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 over all supported WAFs as well as serial bypass/Bluetooth.
static int	getCoverageStatus(int wafs, boolean considerSerialBypass) Retrieves the current coverage status over the specified WAFs and/or serial bypass/Bluetooth.
static boolean	isCoverageSufficient(int coverageType) Determines whether or not the device currently has the type of coverage specified by coverageType, over any available routes.
static boolean	isCoverageSufficient(int coverageType, int wafs, boolean considerSerialBypass) Determines whether or not the device currently has the type of coverage specified by coverageType, over the provided WAFs and/or serial bypass/Bluetooth.
static boolean	isOutOfCoverage() Determines whether or not the device is completely out of coverage over all available routes.
static boolean	isOutOfCoverage(int wafs, boolean considerSerialBypass) Determines whether or not the device is completely out of coverage over the provided WAFs and/or serial bypass/Bluetooth.
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.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

COVERAGE_DIRECT

public static final int COVERAGE_DIRECT

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

• Direct HTTP / TCP via WiFi, wireless service provider IP gateway, or HTTP over WAP via WAP Gateway
• Direct User Datagram Protocol (UDP) via wireless service provider, ASP gateway or via WiFi

See Also:

Constant Field Values

Since:

BlackBerry API 4.5.0

COVERAGE_MDS

public static final int COVERAGE_MDS

Flag indicating the device has sufficient coverage for HTTP over IPPP via BlackBerry Enterprise Server/BlackBerry MDS connection type.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

COVERAGE_BIS_B

public static final int COVERAGE_BIS_B

Flag indicating the device has sufficient coverage for HTTP over IPPP via Public MDS connection type.

See Also:

Constant Field Values

Since:

BlackBerry API 4.6.0

Method Detail

addListener

public static void addListener(CoverageStatusListener listener)

Adds a listener for changes in coverage status. The listener notifications are 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:

BlackBerry API 4.2.0

addListener

public static void addListener(Application app,
                               CoverageStatusListener listener)

Adds a listener for changes in coverage status. The listener notifications are 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:

BlackBerry API 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:

BlackBerry API 4.2.0

removeListener

public static void removeListener(Application app,
                                  CoverageStatusListener listener)

Removes listener from the provided application's list of listeners. If the 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 is to no longer process the notifications sent to listener.

listener - Listener for changes in coverage status.

Throws:

NullPointerException - if app is null.

Since:

BlackBerry API 4.2.0

getCoverageStatus

public static int getCoverageStatus()

Retrieves the current coverage status over all supported WAFs as well as serial bypass/Bluetooth. To obtain the coverage status over a restricted set of routes, use CoverageInfo.getCoverageStatus(int,boolean).

Returns:

A bitmask of COVERAGE_* flags.

Since:

BlackBerry API 4.2.0

getCoverageStatus

public static int getCoverageStatus(int wafs,
                                    boolean considerSerialBypass)

Retrieves the current coverage status over the specified WAFs and/or serial bypass/Bluetooth.

Parameters:

wafs - A bitmask of RadioInfo.WAF_* flags representing the WAFs that should be considered when checking the current coverage status.

considerSerialBypass - If true, the serial bypass/Bluetooth should be considered when checking the current coverage status, if false it should not.

Returns:

A bitmask of COVERAGE_* flags.

Since:

BlackBerry API 4.2.1

isCoverageSufficient

public static boolean isCoverageSufficient(int coverageType)

Determines whether or not the device currently has the type of coverage specified by coverageType, over any available routes. To obtain the coverage status over a restricted set of routes, use CoverageInfo.isCoverageSufficient(int,int,boolean). If coverageType is COVERAGE_NONE, this method always returns false.

Parameters:

coverageType - One of the COVERAGE_* flags.

Returns:

true if the device has the type of coverage specified by coverageType over some available route; false otherwise.

Throws:

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

Since:

BlackBerry API 4.2.0

isCoverageSufficient

public static boolean isCoverageSufficient(int coverageType,
                                           int wafs,
                                           boolean considerSerialBypass)

Determines whether or not the device currently has the type of coverage specified by coverageType, over the provided WAFs and/or serial bypass/Bluetooth. If coverageType is COVERAGE_NONE, this method always returns false.

Parameters:

coverageType - One of the COVERAGE_* flags.

wafs - A bitmask of RadioInfo.WAF_* flags representing the set of WAFs to consider when determining coverage.

considerSerialBypass - If true, the serial bypass/Bluetooth should be considered when checking the current coverage status, if false it should not.

Returns:

true if the device has the type of coverage specified by coverageType over the specified WAFs; false otherwise.

Throws:

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

Since:

BlackBerry API 4.2.1

isOutOfCoverage

public static boolean isOutOfCoverage()

Determines whether or not the device is completely out of coverage over all available routes. To obtain the out-of-coverage status over a restricted set of routes, use CoverageInfo.isOutOfCoverage(int,boolean).

Returns:

true if the device does not have sufficient coverage for any connection types over any available routes; false otherwise.

Since:

BlackBerry API 4.2.0

isOutOfCoverage

public static boolean isOutOfCoverage(int wafs,
                                      boolean considerSerialBypass)

Determines whether or not the device is completely out of coverage over the provided WAFs and/or serial bypass/Bluetooth.

Parameters:

wafs - Bitmask of RadioInfo.WAF_* constants representing the set of WAFs to consider for being out of coverage.

considerSerialBypass - If true, consider serial bypass/Bluetooth for determining if the device is out of coverage, if false it should not.

Returns:

true if the device does not have sufficient coverage for any connection types over the provided WAFs and serial bypass/Bluetooth; false otherwise.

Since:

BlackBerry API 4.2.1