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 over all supported Wireless Access Families (WAFs), as well as serial bypass and Bluetooth. A listener interface is provided for receiving notifications of changes in this aggregate 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.

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

Since:
JDE 4.2.0
See Also:
CoverageStatusListener, RadioInfo

Field Summary
static int COVERAGE_BIS_B
          Flag indicating the device has sufficient coverage for the following connection types: HTTP over IPPP via Public MDS.
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 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 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_BIS_B

public static final int COVERAGE_BIS_B
Flag indicating the device has sufficient coverage for the following connection types:
  • HTTP over IPPP via Public MDS.
Since:
JDE 4.6.0

COVERAGE_DIRECT

public static final 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 carrier IP gateway;
  • Direct UDP via carrier or ASP gateway.
Since:
JDE 4.5.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

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
Method Detail

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

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

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 getCoverageStatus(int,boolean).
Returns:
A bitmask of COVERAGE_* flags.
Since:
JDE 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 - Whether or not serial bypass/Bluetooth should be considered when checking the current coverage status.
Returns:
A bitmask of COVERAGE_* flags.
Since:
JDE 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 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; otherwise false.
Throws:
IllegalArgumentException - if coverageType is not one of the COVERAGE_* flags.
Since:
JDE 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 - True to consider serial bypass/Bluetooth connections when determining coverage; false otherwise.
Returns:
True if the device has the type of coverage specified by coverageType, over the specified routes; otherwise false.
Throws:
IllegalArgumentException - if coverageType is not one of the COVERAGE_* flags.
Since:
JDE 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 isOutOfCoverage(int,boolean).
Returns:
True if the device does not have sufficient coverage for any connection types over any available routes; otherwise false.
Since:
JDE 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 - True to consider serial bypass/Bluetooth for being out of coverage.
Returns:
True if the device does not have sufficient coverage for any connection types over the provided WAFs and/or serial bypass/Bluetooth; otherwise false.
Since:
JDE 4.2.1

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

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



Copyright 1999-2008 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.