net.rim.device.api.system
Class CoverageInfo

java.lang.Object
  extended by 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: HTTP over WAP via WAP gateway Direct HTTP / TCP via wireless service provider IP gateway Direct User Datagram Protocol (UDP) via wireless service provider or ASP gateway
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:

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.