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


Copyright 1999-2006 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.