net.rim.device.api.system
Class RadioInfo

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

public final class RadioInfo
extends Object

Provides access to information about the status of the radio.


Field Summary
static int BAND_CDMA_1900
          Represents the 1900 MHz CDMA band.
static int BAND_CDMA_800
          Represents the 800 MHz CDMA band.
static int BAND_DATATAC_800
          Deprecated. DataTAC is no longer supported.
static int BAND_GSM_1800
          Represents the 1800 MHz GSM band.
static int BAND_GSM_1900
          Represents the 1900 MHz GSM band.
static int BAND_GSM_850
          Represents the 850 MHz GSM band.
static int BAND_GSM_900
          Represents the 900 MHz GSM band.
static int BAND_IDEN_800
          Represents the 800 MHz iDEN band.
static int BAND_MOBITEX_900
          Deprecated. Mobitex is no longer supported.
static int BAND_UMTS_2100
          Represents the 2100 MHz UMTS band.
static int LEVEL_NO_COVERAGE
          Radio has no coverage.
static int NETWORK_802_11
          802.11 network.
static int NETWORK_CDMA
          CDMA network.
static int NETWORK_DATATAC
          Deprecated. DataTAC is no longer supported.
static int NETWORK_GPRS
          GPRS network.
static int NETWORK_IDEN
          iDEN network.
static int NETWORK_MOBITEX
          Deprecated. Mobitex is no longer supported.
static int NETWORK_NONE
          No radio network supported.
static int NETWORK_SERVICE_DATA
          Network is providing data service.
static int NETWORK_SERVICE_DIRECT_CONNECT
          Network is providing direct connect service.
static int NETWORK_SERVICE_E911_CALLBACK_MODE
          Device is in E911 callback mode.
static int NETWORK_SERVICE_EDGE
          Device is in EDGE coverage.
static int NETWORK_SERVICE_EMERGENCY_ONLY
          Network is providing emergency service only.
static int NETWORK_SERVICE_EVDO
          Deprecated. NETWORK_SERVICE_EVDO is no longer supported. NETWORK_SERVICE_EVDO is replaced by NETWORK_SERVICE_EVDO_REV0.
static int NETWORK_SERVICE_EVDO_ONLY
          Deprecated. NETWORK_SERVICE_EVDO_ONLY is no longer supported. NETWORK_SERVICE_EVDO_ONLY is replaced by NETWORK_SERVICE_EVDO_REV0_ONLY.
static int NETWORK_SERVICE_GAN
          Device is in GAN mode.
static int NETWORK_SERVICE_IN_CITY_ZONE
          Device is in the 'city' zone.
static int NETWORK_SERVICE_IN_HOME_ZONE
          Device is in the 'home' zone.
static int NETWORK_SERVICE_MODEM_MODE_ENABLED
          Device is in modem (only) mode.
static int NETWORK_SERVICE_ROAMING
          Device is roaming.
static int NETWORK_SERVICE_ROAMING_OFF_CAMPUS
          Device is roaming onto another network campus.
static int NETWORK_SERVICE_SUPPRESS_ROAMING
          The roaming indicator should be suppressed.
static int NETWORK_SERVICE_UMTS
          Device is in UMTS coverage.
static int NETWORK_SERVICE_VOICE
          Network is providing voice service.
static int NETWORK_UMTS
          UMTS network
static int STATE_LOWBATT
          Radio is on but cannot function because of low battery.
static int STATE_OFF
          Radio is off.
static int STATE_ON
          Radio is on.
static int STATE_RELOAD_REQUIRED
          Radio off and requires reloading.
static int STATE_SERVICE_REQUIRED
          Radio is off and requires service.
static int STATE_TURNING_OFF
          Radio is in process of turning off.
static int STATE_TURNING_ON
          Radio is in process of turning on.
static int WAF_3GPP
          3GPP Wireless Access Family.
static int WAF_CDMA
          CDMA Wireless Access Family.
static int WAF_IDEN
          iDEN Wireless Access Family.
static int WAF_WLAN
          WLAN Wireless Access Family.
 
Method Summary
static boolean areWAFsSupported(int WAFs)
          Determines if any of the provided Wireless Access Families are supported by the device.
static int calculateNetworkId(int mcc, int mnc)
          Calculate the network ID value given the MCC and MNC in decimal value representation.
static String getAccessPointName(int apnId)
          Gets the access point name from the given identifier.
static int getAccessPointNumber(String name)
          Retrieves the access point number for the specified name.
static int getAccessPointNumber(String data, int offset, int length)
          Retrieves the access point number for the specified name.
static int getActiveWAFs()
          Retrieves the currently active Wireless Access Families.
static int getCurrentNetworkIndex()
          Retrieves the index of the current network.
static String getCurrentNetworkName()
          Retrieve the name of the carrier network on which the device is currently registered.
static int getEnabledWAFs()
          Retrieves the currently enabled Wireless Access Families.
static byte[] getIPAddress(int apnId)
          Retrieves the IP address for the specified access point name identifier.
static int getMCC(int index)
          Retrieves Mobile Country Code for this network.
static int getMNC(int index)
          Retrieves Mobile Network Code for the specified network.
static String getNetworkCountryCode(int index)
          Retrieves the country code (i.e. country initials) of the specified network.
static int getNetworkId(int index)
          Retrieves the Id of the specified network.
static String getNetworkName(int index)
          Retrieves the name of the specified network.
static int getNetworkService()
          Retrieves currently available network services.
static int getNetworkService(int waf)
          Retrieves currently available network services.
static long getNetworkTime(long deviceTime)
          Determine the current network time, as calculated using an offset from the current device time.
static int getNetworkType()
          Retrieves the network type.
static int getNumberOfNetworks()
          Retrieves the number of available networks.
static long getNumberOfPacketsReceived()
          Retrieves the number of IP bytes received by the radio.
static long getNumberOfPacketsSent()
          Retrieves the number of IP bytes sent by the radio.
static int getSignalLevel()
          Retrieves current signal strength.
static int getSignalLevel(int WAF)
          Retrieves current signal level for the specified Wireless Access Family.
static int getState()
          Checks the radio state.
static int getSupportedBands()
          Retrieves the network bands which are supported by the device.
static int getSupportedWAFs()
          Retrieves the Wireless Access Families that are supported by the device.
static boolean isDataServiceOperational()
          Indicates whether the radio can perform data services at this time.
static boolean isDataServiceSuspended()
          Indicates whether data services are temporarily suspended at the present time.
static boolean isPDPContextActive(int apnId)
          Indicates if the PDP context for the specified APN is active.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BAND_CDMA_1900

public static final int BAND_CDMA_1900
Represents the 1900 MHz CDMA band.
Since:
JDE 3.6.0

BAND_CDMA_800

public static final int BAND_CDMA_800
Represents the 800 MHz CDMA band.
Since:
JDE 3.6.0

BAND_DATATAC_800

public static final int BAND_DATATAC_800
Deprecated. DataTAC is no longer supported.

Represents the 800 MHz Datatac band.
Since:
JDE 3.6.0

BAND_GSM_1800

public static final int BAND_GSM_1800
Represents the 1800 MHz GSM band.
Since:
JDE 3.6.0

BAND_GSM_1900

public static final int BAND_GSM_1900
Represents the 1900 MHz GSM band.
Since:
JDE 3.6.0

BAND_GSM_850

public static final int BAND_GSM_850
Represents the 850 MHz GSM band.
Since:
JDE 3.7.0

BAND_GSM_900

public static final int BAND_GSM_900
Represents the 900 MHz GSM band.
Since:
JDE 3.6.0

BAND_IDEN_800

public static final int BAND_IDEN_800
Represents the 800 MHz iDEN band.
Since:
JDE 3.6.0

BAND_MOBITEX_900

public static final int BAND_MOBITEX_900
Deprecated. Mobitex is no longer supported.

Represents the 900 MHz Mobitex band.
Since:
JDE 3.6.0

BAND_UMTS_2100

public static final int BAND_UMTS_2100
Represents the 2100 MHz UMTS band.
Since:
JDE 4.2.1

LEVEL_NO_COVERAGE

public static final int LEVEL_NO_COVERAGE
Radio has no coverage.

NETWORK_802_11

public static final int NETWORK_802_11
802.11 network.
Since:
JDE 4.0.2

NETWORK_CDMA

public static final int NETWORK_CDMA
CDMA network.

NETWORK_DATATAC

public static final int NETWORK_DATATAC
Deprecated. DataTAC is no longer supported.

DataTAC network.

NETWORK_GPRS

public static final int NETWORK_GPRS
GPRS network.

NETWORK_IDEN

public static final int NETWORK_IDEN
iDEN network.

NETWORK_MOBITEX

public static final int NETWORK_MOBITEX
Deprecated. Mobitex is no longer supported.

Mobitex network.

NETWORK_NONE

public static final int NETWORK_NONE
No radio network supported.
Since:
JDE 4.1.0

NETWORK_SERVICE_DATA

public static final int NETWORK_SERVICE_DATA
Network is providing data service.

NETWORK_SERVICE_DIRECT_CONNECT

public static final int NETWORK_SERVICE_DIRECT_CONNECT
Network is providing direct connect service.
Since:
JDE 3.6.0

NETWORK_SERVICE_E911_CALLBACK_MODE

public static final int NETWORK_SERVICE_E911_CALLBACK_MODE
Device is in E911 callback mode.
Since:
JDE 3.6.0

NETWORK_SERVICE_EDGE

public static final int NETWORK_SERVICE_EDGE
Device is in EDGE coverage.
Since:
JDE 4.1.0

NETWORK_SERVICE_EMERGENCY_ONLY

public static final int NETWORK_SERVICE_EMERGENCY_ONLY
Network is providing emergency service only.

NETWORK_SERVICE_EVDO

public static final int NETWORK_SERVICE_EVDO
Deprecated. NETWORK_SERVICE_EVDO is no longer supported. NETWORK_SERVICE_EVDO is replaced by NETWORK_SERVICE_EVDO_REV0.

Device is in EV-DO coverage with 1X.
Since:
JDE 4.0.2

NETWORK_SERVICE_EVDO_ONLY

public static final int NETWORK_SERVICE_EVDO_ONLY
Deprecated. NETWORK_SERVICE_EVDO_ONLY is no longer supported. NETWORK_SERVICE_EVDO_ONLY is replaced by NETWORK_SERVICE_EVDO_REV0_ONLY.

Device is in EV-DO coverage only, No 1X
Since:
JDE 4.2.0

NETWORK_SERVICE_GAN

public static final int NETWORK_SERVICE_GAN
Device is in GAN mode.
Since:
JDE 4.2.1

NETWORK_SERVICE_IN_CITY_ZONE

public static final int NETWORK_SERVICE_IN_CITY_ZONE
Device is in the 'city' zone.
Since:
JDE 3.6.0

NETWORK_SERVICE_IN_HOME_ZONE

public static final int NETWORK_SERVICE_IN_HOME_ZONE
Device is in the 'home' zone.
Since:
JDE 3.6.0

NETWORK_SERVICE_MODEM_MODE_ENABLED

public static final int NETWORK_SERVICE_MODEM_MODE_ENABLED
Device is in modem (only) mode.
Since:
JDE 4.0.2

NETWORK_SERVICE_ROAMING

public static final int NETWORK_SERVICE_ROAMING
Device is roaming.

NETWORK_SERVICE_ROAMING_OFF_CAMPUS

public static final int NETWORK_SERVICE_ROAMING_OFF_CAMPUS
Device is roaming onto another network campus.

NETWORK_SERVICE_SUPPRESS_ROAMING

public static final int NETWORK_SERVICE_SUPPRESS_ROAMING
The roaming indicator should be suppressed.
Since:
JDE 3.7.0

NETWORK_SERVICE_UMTS

public static final int NETWORK_SERVICE_UMTS
Device is in UMTS coverage.
Since:
JDE 4.2.0

NETWORK_SERVICE_VOICE

public static final int NETWORK_SERVICE_VOICE
Network is providing voice service.

NETWORK_UMTS

public static final int NETWORK_UMTS
UMTS network
Since:
JDE 4.2.0

STATE_LOWBATT

public static final int STATE_LOWBATT
Radio is on but cannot function because of low battery.

STATE_OFF

public static final int STATE_OFF
Radio is off.

STATE_ON

public static final int STATE_ON
Radio is on.

STATE_RELOAD_REQUIRED

public static final int STATE_RELOAD_REQUIRED
Radio off and requires reloading.
Since:
JDE 4.0.0

STATE_SERVICE_REQUIRED

public static final int STATE_SERVICE_REQUIRED
Radio is off and requires service.

STATE_TURNING_OFF

public static final int STATE_TURNING_OFF
Radio is in process of turning off.

STATE_TURNING_ON

public static final int STATE_TURNING_ON
Radio is in process of turning on.

WAF_3GPP

public static final int WAF_3GPP
3GPP Wireless Access Family.
Since:
JDE 4.2.1

WAF_CDMA

public static final int WAF_CDMA
CDMA Wireless Access Family.
Since:
JDE 4.2.1

WAF_IDEN

public static final int WAF_IDEN
iDEN Wireless Access Family.
Since:
JDE 4.2.1

WAF_WLAN

public static final int WAF_WLAN
WLAN Wireless Access Family.
Since:
JDE 4.2.1
Method Detail

areWAFsSupported

public static boolean areWAFsSupported(int WAFs)
Determines if any of the provided Wireless Access Families are supported by the device.
Parameters:
WAFs - A bitfield of WAF_* flags indicating the Wireless Access Families to check for support.
Returns:
True if any of the provided Wireless Access Families are supported; otherwise false.
Since:
JDE 4.2.1

calculateNetworkId

public static int calculateNetworkId(int mcc,
                                     int mnc)
Calculate the network ID value given the MCC and MNC in decimal value representation.

If the provided values are out of range, such as negative numbers or greater than 0xFFF, then the returned value is undefined.

For example, after the code below executes the variable hexNetworkId will have value 0x02600310.

    int mcc = 310
    int mnc = 260
    int hexNetworkId = RadioInfo.calculateNetworkId(mcc, mnc);
 
Parameters:
mcc - Decimal value of MCC
mnc - Decimal value of MNC
Returns:
Network Id representation of MCC and MNC (i.e. 0x0MNC0MCC).
Since:
JDE 4.2.1

getAccessPointName

public static String getAccessPointName(int apnId)
                                 throws RadioException
Gets the access point name from the given identifier.
Parameters:
apnId - The access point name identifier.
Returns:
The access point name.
Throws:
RadioException - If a radio error occurs or if the provided value for apnId is invalid.
Since:
JDE 4.1.0

getAccessPointNumber

public static int getAccessPointNumber(String name)
                                throws RadioException
Retrieves the access point number for the specified name.
Parameters:
name - The access point name.
Returns:
The access point name identifier.
Throws:
RadioException - If a radio error occurs.
Since:
JDE 4.1.0

getAccessPointNumber

public static int getAccessPointNumber(String data,
                                       int offset,
                                       int length)
                                throws RadioException
Retrieves the access point number for the specified name.
Parameters:
data - The String containing the access point name.
offset - The start offset of the access point name.
length - The length of the access point name.
Returns:
The access point name identifier.
Throws:
RadioException - If a radio error occurs or if invalid parameters passed.
Since:
JDE 4.1.0

getActiveWAFs

public static int getActiveWAFs()
Retrieves the currently active Wireless Access Families.
Returns:
A bitfield of WAF_* flags indicating the currently active Wireless Access Families.
Since:
JDE 4.2.1

getCurrentNetworkIndex

public static int getCurrentNetworkIndex()
Retrieves the index of the current network.
Returns:
The current network index, from 0 to getNumberOfNetworks() - 1.
Since:
JDE 4.1.0

getCurrentNetworkName

public static String getCurrentNetworkName()
Retrieve the name of the carrier network on which the device is currently registered.
Returns:
The name of the carrier network, or null if the device is not registered on any network
Since:
JDE 4.2.0

getEnabledWAFs

public static int getEnabledWAFs()

Retrieves the currently enabled Wireless Access Families. Enabled WAFs are those permitted to be active on multiple WAF devices where not all WAFs are active at the same time.

E.g. Global mode enables CDMA and GSM but only one of these WAFs may be active depending on availability of network.

Returns:
A bitfield of WAF_* flags indicating the currently enabled Wireless Access Families.
Since:
JDE 4.3.0

getIPAddress

public static byte[] getIPAddress(int apnId)
Retrieves the IP address for the specified access point name identifier.
Parameters:
apnId - The access point name identifier.
Returns:
The IP address in network byte order (the highest order byte of the address is in address[0]).
Since:
JDE 4.1.0

getMCC

public static int getMCC(int index)
Retrieves Mobile Country Code for this network.
Parameters:
index - The network index, from 0 to getNumberOfNetworks() - 1.
Returns:
MCC for this network.
Since:
JDE 4.2.0

getMNC

public static int getMNC(int index)
Retrieves Mobile Network Code for the specified network.
Parameters:
index - The network index, from 0 to getNumberOfNetworks() - 1.
Returns:
MNC for this network.
Since:
JDE 4.2.0

getNetworkCountryCode

public static String getNetworkCountryCode(int index)
Retrieves the country code (i.e. country initials) of the specified network.
Parameters:
index - The network index, from 0 to getNumberOfNetworks() - 1.
Returns:
The network country code, or null if unknown.
Throws:
IllegalArgumentException - if the index parameter is out of bounds.
Since:
JDE 4.2.1

getNetworkId

public static int getNetworkId(int index)
Retrieves the Id of the specified network.
Parameters:
index - The network index, from 0 to getNumberOfNetworks() - 1.
Returns:
The network Id.
Throws:
IllegalArgumentException - if index is less than zero or is greater than the number of existing networks: (RadioInfo.getNumberOfNetworks() - 1).
Since:
JDE 4.1.0

getNetworkName

public static String getNetworkName(int index)
Retrieves the name of the specified network.
Parameters:
index - The network index, from 0 to getNumberOfNetworks() - 1.
Returns:
The network name.
Since:
JDE 4.2.1

getNetworkService

public static int getNetworkService()
Retrieves currently available network services.
Returns:
Combination of the NETWORK_SERVICE_* flags.

getNetworkService

public static int getNetworkService(int waf)
Retrieves currently available network services.
Returns:
Combination of the NETWORK_SERVICE_* flags.
Since:
JDE 4.5.0

getNetworkTime

public static long getNetworkTime(long deviceTime)
Determine the current network time, as calculated using an offset from the current device time. The quality of this information is network dependent.
Parameters:
deviceTime - current time in milliseconds
Returns:
A time in milliseconds corresponding to the network reported time normalized to the local time zone.
Since:
JDE 4.1.0

getNetworkType

public static int getNetworkType()
Retrieves the network type.
Returns:
Network type; one of NETWORK_GPRS, NETWORK_UMTS, NETWORK_CDMA, NETWORK_IDEN, NETWORK_802_11.

getNumberOfNetworks

public static int getNumberOfNetworks()
Retrieves the number of available networks.
Returns:
The number of available networks.
Since:
JDE 4.2.0

getNumberOfPacketsReceived

public static long getNumberOfPacketsReceived()
Retrieves the number of IP bytes received by the radio.
Returns:
Number of bytes received by the radio, or -1 if this feature is not supported.
Since:
JDE 4.0.0

getNumberOfPacketsSent

public static long getNumberOfPacketsSent()
Retrieves the number of IP bytes sent by the radio.
Returns:
Number of bytes sent by the radio, or -1 if this feature is not supported.
Since:
JDE 4.0.0

getSignalLevel

public static int getSignalLevel()
Retrieves current signal strength.
Returns:
Signal level in dBm (typically between -121 dBm and -40 dBm) or LEVEL_NO_COVERAGE if the radio is out of coverage.

getSignalLevel

public static int getSignalLevel(int WAF)
Retrieves current signal level for the specified Wireless Access Family. If WAF is not one of the WAF_* constants, then WAF_3GPP is assumed.
Parameters:
WAF - The Wireless Access Family whose signal level is to be retrieved. Must be one of the WAF_* constants, otherwise WAF_3GPP is assumed.
Returns:
Signal level in dBm (typically between -121 dBm and -40 dBm) or LEVEL_NO_COVERAGE if the radio is out of coverage.
Since:
JDE 4.2.1

getState

public static int getState()
Checks the radio state.
Returns:
One of the following radio states:

getSupportedBands

public static int getSupportedBands()
Retrieves the network bands which are supported by the device.
Returns:
The network band supported by the device.
Since:
JDE 3.6.0

getSupportedWAFs

public static int getSupportedWAFs()
Retrieves the Wireless Access Families that are supported by the device.
Returns:
A bitfield of WAF_* flags indicating the Wireless Access Families supported by the device.
Since:
JDE 4.2.1

isDataServiceOperational

public static boolean isDataServiceOperational()
Indicates whether the radio can perform data services at this time.
Returns:
true if data service requests can be performed.
Since:
JDE 4.2.0

isDataServiceSuspended

public static boolean isDataServiceSuspended()
Indicates whether data services are temporarily suspended at the present time. Data services are suspended on class B networks when the phone is active.
Returns:
true if data services are suspended
Since:
JDE 4.2.0

isPDPContextActive

public static boolean isPDPContextActive(int apnId)
Indicates if the PDP context for the specified APN is active.
Parameters:
apnId - The access point name identifier.
Returns:
true if the PDP context for the specified APN is active.
Since:
JDE 4.1.0



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