to top
Android APIs
public class

TelephonyManager

extends Object
java.lang.Object
   ↳ android.telephony.TelephonyManager

Class Overview

Provides access to information about the telephony services on the device. Applications can use the methods in this class to determine telephony services and states, as well as to access some types of subscriber information. Applications can also register a listener to receive notification of telephony state changes.

You do not instantiate this class directly; instead, you retrieve a reference to an instance through Context.getSystemService(Context.TELEPHONY_SERVICE).

Note that access to some telephony information is permission-protected. Your application cannot access the protected information unless it has the appropriate permissions declared in its manifest file. Where permissions apply, they are noted in the the methods through which you access the protected information.

Summary

Constants
String ACTION_PHONE_STATE_CHANGED Broadcast intent action indicating that the call state (cellular) on the device has changed.
int CALL_STATE_IDLE Device call state: No activity.
int CALL_STATE_OFFHOOK Device call state: Off-hook.
int CALL_STATE_RINGING Device call state: Ringing.
int DATA_ACTIVITY_DORMANT Data connection is active, but physical link is down
int DATA_ACTIVITY_IN Data connection activity: Currently receiving IP PPP traffic.
int DATA_ACTIVITY_INOUT Data connection activity: Currently both sending and receiving IP PPP traffic.
int DATA_ACTIVITY_NONE Data connection activity: No traffic.
int DATA_ACTIVITY_OUT Data connection activity: Currently sending IP PPP traffic.
int DATA_CONNECTED Data connection state: Connected.
int DATA_CONNECTING Data connection state: Currently setting up a data connection.
int DATA_DISCONNECTED Data connection state: Disconnected.
int DATA_SUSPENDED Data connection state: Suspended.
String EXTRA_INCOMING_NUMBER The lookup key used with the ACTION_PHONE_STATE_CHANGED broadcast for a String containing the incoming phone number.
String EXTRA_STATE The lookup key used with the ACTION_PHONE_STATE_CHANGED broadcast for a String containing the new call state.
int NETWORK_TYPE_1xRTT Current network is 1xRTT
int NETWORK_TYPE_CDMA Current network is CDMA: Either IS95A or IS95B
int NETWORK_TYPE_EDGE Current network is EDGE
int NETWORK_TYPE_EHRPD Current network is eHRPD
int NETWORK_TYPE_EVDO_0 Current network is EVDO revision 0
int NETWORK_TYPE_EVDO_A Current network is EVDO revision A
int NETWORK_TYPE_EVDO_B Current network is EVDO revision B
int NETWORK_TYPE_GPRS Current network is GPRS
int NETWORK_TYPE_HSDPA Current network is HSDPA
int NETWORK_TYPE_HSPA Current network is HSPA
int NETWORK_TYPE_HSPAP Current network is HSPA+
int NETWORK_TYPE_HSUPA Current network is HSUPA
int NETWORK_TYPE_IDEN Current network is iDen
int NETWORK_TYPE_LTE Current network is LTE
int NETWORK_TYPE_UMTS Current network is UMTS
int NETWORK_TYPE_UNKNOWN Network type is unknown
int PHONE_TYPE_CDMA Phone radio is CDMA.
int PHONE_TYPE_GSM Phone radio is GSM.
int PHONE_TYPE_NONE No phone radio.
int PHONE_TYPE_SIP Phone is via SIP.
int SIM_STATE_ABSENT SIM card state: no SIM card is available in the device
int SIM_STATE_NETWORK_LOCKED SIM card state: Locked: requries a network PIN to unlock
int SIM_STATE_PIN_REQUIRED SIM card state: Locked: requires the user's SIM PIN to unlock
int SIM_STATE_PUK_REQUIRED SIM card state: Locked: requires the user's SIM PUK to unlock
int SIM_STATE_READY SIM card state: Ready
int SIM_STATE_UNKNOWN SIM card state: Unknown.
Fields
public static final String EXTRA_STATE_IDLE Value used with EXTRA_STATE corresponding to CALL_STATE_IDLE.
public static final String EXTRA_STATE_OFFHOOK Value used with EXTRA_STATE corresponding to CALL_STATE_OFFHOOK.
public static final String EXTRA_STATE_RINGING Value used with EXTRA_STATE corresponding to CALL_STATE_RINGING.
Public Methods
int getCallState()
Returns a constant indicating the call state (cellular) on the device.
CellLocation getCellLocation()
Returns the current location of the device.
int getDataActivity()
Returns a constant indicating the type of activity on a data connection (cellular).
int getDataState()
Returns a constant indicating the current data connection state (cellular).
String getDeviceId()
Returns the unique device ID, for example, the IMEI for GSM and the MEID or ESN for CDMA phones.
String getDeviceSoftwareVersion()
Returns the software version number for the device, for example, the IMEI/SV for GSM phones.
String getLine1Number()
Returns the phone number string for line 1, for example, the MSISDN for a GSM phone.
List<NeighboringCellInfo> getNeighboringCellInfo()
Returns the neighboring cell information of the device.
String getNetworkCountryIso()
Returns the ISO country code equivalent of the current registered operator's MCC (Mobile Country Code).
String getNetworkOperator()
Returns the numeric name (MCC+MNC) of current registered operator.
String getNetworkOperatorName()
Returns the alphabetic name of current registered operator.
int getNetworkType()
Returns a constant indicating the radio technology (network type) currently in use on the device for data transmission.
int getPhoneType()
Returns a constant indicating the device phone type.
String getSimCountryIso()
Returns the ISO country code equivalent for the SIM provider's country code.
String getSimOperator()
Returns the MCC+MNC (mobile country code + mobile network code) of the provider of the SIM.
String getSimOperatorName()
Returns the Service Provider Name (SPN).
String getSimSerialNumber()
Returns the serial number of the SIM, if applicable.
int getSimState()
Returns a constant indicating the state of the device SIM card.
String getSubscriberId()
Returns the unique subscriber ID, for example, the IMSI for a GSM phone.
String getVoiceMailAlphaTag()
Retrieves the alphabetic identifier associated with the voice mail number.
String getVoiceMailNumber()
Returns the voice mail number.
boolean hasIccCard()
boolean isNetworkRoaming()
Returns true if the device is considered roaming on the current network, for GSM purposes.
void listen(PhoneStateListener listener, int events)
Registers a listener object to receive notification of changes in specified telephony states.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_PHONE_STATE_CHANGED

Since: API Level 3

Broadcast intent action indicating that the call state (cellular) on the device has changed.

The EXTRA_STATE extra indicates the new call state. If the new state is RINGING, a second extra EXTRA_INCOMING_NUMBER provides the incoming phone number as a String.

Requires the READ_PHONE_STATE permission.

This was a sticky broadcast in version 1.0, but it is no longer sticky. Instead, use getCallState() to synchronously query the current call state.

Constant Value: "android.intent.action.PHONE_STATE"

public static final int CALL_STATE_IDLE

Since: API Level 1

Device call state: No activity.

Constant Value: 0 (0x00000000)

public static final int CALL_STATE_OFFHOOK

Since: API Level 1

Device call state: Off-hook. At least one call exists that is dialing, active, or on hold, and no calls are ringing or waiting.

Constant Value: 2 (0x00000002)

public static final int CALL_STATE_RINGING

Since: API Level 1

Device call state: Ringing. A new call arrived and is ringing or waiting. In the latter case, another call is already active.

Constant Value: 1 (0x00000001)

public static final int DATA_ACTIVITY_DORMANT

Since: API Level 4

Data connection is active, but physical link is down

Constant Value: 4 (0x00000004)

public static final int DATA_ACTIVITY_IN

Since: API Level 1

Data connection activity: Currently receiving IP PPP traffic.

Constant Value: 1 (0x00000001)

public static final int DATA_ACTIVITY_INOUT

Since: API Level 1

Data connection activity: Currently both sending and receiving IP PPP traffic.

Constant Value: 3 (0x00000003)

public static final int DATA_ACTIVITY_NONE

Since: API Level 1

Data connection activity: No traffic.

Constant Value: 0 (0x00000000)

public static final int DATA_ACTIVITY_OUT

Since: API Level 1

Data connection activity: Currently sending IP PPP traffic.

Constant Value: 2 (0x00000002)

public static final int DATA_CONNECTED

Since: API Level 1

Data connection state: Connected. IP traffic should be available.

Constant Value: 2 (0x00000002)

public static final int DATA_CONNECTING

Since: API Level 1

Data connection state: Currently setting up a data connection.

Constant Value: 1 (0x00000001)

public static final int DATA_DISCONNECTED

Since: API Level 1

Data connection state: Disconnected. IP traffic not available.

Constant Value: 0 (0x00000000)

public static final int DATA_SUSPENDED

Since: API Level 1

Data connection state: Suspended. The connection is up, but IP traffic is temporarily unavailable. For example, in a 2G network, data activity may be suspended when a voice call arrives.

Constant Value: 3 (0x00000003)

public static final String EXTRA_INCOMING_NUMBER

Since: API Level 3

The lookup key used with the ACTION_PHONE_STATE_CHANGED broadcast for a String containing the incoming phone number. Only valid when the new call state is RINGING.

Retrieve with getStringExtra(String).

Constant Value: "incoming_number"

public static final String EXTRA_STATE

Since: API Level 3

The lookup key used with the ACTION_PHONE_STATE_CHANGED broadcast for a String containing the new call state.

Constant Value: "state"

public static final int NETWORK_TYPE_1xRTT

Since: API Level 4

Current network is 1xRTT

Constant Value: 7 (0x00000007)

public static final int NETWORK_TYPE_CDMA

Since: API Level 4

Current network is CDMA: Either IS95A or IS95B

Constant Value: 4 (0x00000004)

public static final int NETWORK_TYPE_EDGE

Since: API Level 1

Current network is EDGE

Constant Value: 2 (0x00000002)

public static final int NETWORK_TYPE_EHRPD

Since: API Level 11

Current network is eHRPD

Constant Value: 14 (0x0000000e)

public static final int NETWORK_TYPE_EVDO_0

Since: API Level 4

Current network is EVDO revision 0

Constant Value: 5 (0x00000005)

public static final int NETWORK_TYPE_EVDO_A

Since: API Level 4

Current network is EVDO revision A

Constant Value: 6 (0x00000006)

public static final int NETWORK_TYPE_EVDO_B

Since: API Level 9

Current network is EVDO revision B

Constant Value: 12 (0x0000000c)

public static final int NETWORK_TYPE_GPRS

Since: API Level 1

Current network is GPRS

Constant Value: 1 (0x00000001)

public static final int NETWORK_TYPE_HSDPA

Since: API Level 5

Current network is HSDPA

Constant Value: 8 (0x00000008)

public static final int NETWORK_TYPE_HSPA

Since: API Level 5

Current network is HSPA

Constant Value: 10 (0x0000000a)

public static final int NETWORK_TYPE_HSPAP

Since: API Level 13

Current network is HSPA+

Constant Value: 15 (0x0000000f)

public static final int NETWORK_TYPE_HSUPA

Since: API Level 5

Current network is HSUPA

Constant Value: 9 (0x00000009)

public static final int NETWORK_TYPE_IDEN

Since: API Level 8

Current network is iDen

Constant Value: 11 (0x0000000b)

public static final int NETWORK_TYPE_LTE

Since: API Level 11

Current network is LTE

Constant Value: 13 (0x0000000d)

public static final int NETWORK_TYPE_UMTS

Since: API Level 1

Current network is UMTS

Constant Value: 3 (0x00000003)

public static final int NETWORK_TYPE_UNKNOWN

Since: API Level 1

Network type is unknown

Constant Value: 0 (0x00000000)

public static final int PHONE_TYPE_CDMA

Since: API Level 4

Phone radio is CDMA.

Constant Value: 2 (0x00000002)

public static final int PHONE_TYPE_GSM

Since: API Level 1

Phone radio is GSM.

Constant Value: 1 (0x00000001)

public static final int PHONE_TYPE_NONE

Since: API Level 1

No phone radio.

Constant Value: 0 (0x00000000)

public static final int PHONE_TYPE_SIP

Since: API Level 11

Phone is via SIP.

Constant Value: 3 (0x00000003)

public static final int SIM_STATE_ABSENT

Since: API Level 1

SIM card state: no SIM card is available in the device

Constant Value: 1 (0x00000001)

public static final int SIM_STATE_NETWORK_LOCKED

Since: API Level 1

SIM card state: Locked: requries a network PIN to unlock

Constant Value: 4 (0x00000004)

public static final int SIM_STATE_PIN_REQUIRED

Since: API Level 1

SIM card state: Locked: requires the user's SIM PIN to unlock

Constant Value: 2 (0x00000002)

public static final int SIM_STATE_PUK_REQUIRED

Since: API Level 1

SIM card state: Locked: requires the user's SIM PUK to unlock

Constant Value: 3 (0x00000003)

public static final int SIM_STATE_READY

Since: API Level 1

SIM card state: Ready

Constant Value: 5 (0x00000005)

public static final int SIM_STATE_UNKNOWN

Since: API Level 1

SIM card state: Unknown. Signifies that the SIM is in transition between states. For example, when the user inputs the SIM pin under PIN_REQUIRED state, a query for sim status returns this state before turning to SIM_STATE_READY.

Constant Value: 0 (0x00000000)

Fields

public static final String EXTRA_STATE_IDLE

Since: API Level 3

Value used with EXTRA_STATE corresponding to CALL_STATE_IDLE.

public static final String EXTRA_STATE_OFFHOOK

Since: API Level 3

Value used with EXTRA_STATE corresponding to CALL_STATE_OFFHOOK.

public static final String EXTRA_STATE_RINGING

Since: API Level 3

Value used with EXTRA_STATE corresponding to CALL_STATE_RINGING.

Public Methods

public int getCallState ()

Since: API Level 1

Returns a constant indicating the call state (cellular) on the device.

public CellLocation getCellLocation ()

Since: API Level 1

Returns the current location of the device. Return null if current location is not available.

Requires Permission: ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.

public int getDataActivity ()

Since: API Level 1

Returns a constant indicating the type of activity on a data connection (cellular).

public int getDataState ()

Since: API Level 1

Returns a constant indicating the current data connection state (cellular).

public String getDeviceId ()

Since: API Level 1

Returns the unique device ID, for example, the IMEI for GSM and the MEID or ESN for CDMA phones. Return null if device ID is not available.

Requires Permission: READ_PHONE_STATE

public String getDeviceSoftwareVersion ()

Since: API Level 1

Returns the software version number for the device, for example, the IMEI/SV for GSM phones. Return null if the software version is not available.

Requires Permission: READ_PHONE_STATE

public String getLine1Number ()

Since: API Level 1

Returns the phone number string for line 1, for example, the MSISDN for a GSM phone. Return null if it is unavailable.

Requires Permission: READ_PHONE_STATE

public List<NeighboringCellInfo> getNeighboringCellInfo ()

Since: API Level 3

Returns the neighboring cell information of the device.

Returns
  • List of NeighboringCellInfo or null if info unavailable.

    Requires Permission: (@link android.Manifest.permission#ACCESS_COARSE_UPDATES}

public String getNetworkCountryIso ()

Since: API Level 1

Returns the ISO country code equivalent of the current registered operator's MCC (Mobile Country Code).

Availability: Only when user is registered to a network. Result may be unreliable on CDMA networks (use getPhoneType() to determine if on a CDMA network).

public String getNetworkOperator ()

Since: API Level 1

Returns the numeric name (MCC+MNC) of current registered operator.

Availability: Only when user is registered to a network. Result may be unreliable on CDMA networks (use getPhoneType() to determine if on a CDMA network).

public String getNetworkOperatorName ()

Since: API Level 1

Returns the alphabetic name of current registered operator.

Availability: Only when user is registered to a network. Result may be unreliable on CDMA networks (use getPhoneType() to determine if on a CDMA network).

public int getPhoneType ()

Since: API Level 1

Returns a constant indicating the device phone type. This indicates the type of radio used to transmit voice calls.

public String getSimCountryIso ()

Since: API Level 1

Returns the ISO country code equivalent for the SIM provider's country code.

public String getSimOperator ()

Since: API Level 1

Returns the MCC+MNC (mobile country code + mobile network code) of the provider of the SIM. 5 or 6 decimal digits.

Availability: SIM state must be SIM_STATE_READY

See Also

public String getSimOperatorName ()

Since: API Level 1

Returns the Service Provider Name (SPN).

Availability: SIM state must be SIM_STATE_READY

See Also

public String getSimSerialNumber ()

Since: API Level 1

Returns the serial number of the SIM, if applicable. Return null if it is unavailable.

Requires Permission: READ_PHONE_STATE

public int getSimState ()

Since: API Level 1

public String getSubscriberId ()

Since: API Level 1

Returns the unique subscriber ID, for example, the IMSI for a GSM phone. Return null if it is unavailable.

Requires Permission: READ_PHONE_STATE

public String getVoiceMailAlphaTag ()

Since: API Level 1

Retrieves the alphabetic identifier associated with the voice mail number.

Requires Permission: READ_PHONE_STATE

public String getVoiceMailNumber ()

Since: API Level 1

Returns the voice mail number. Return null if it is unavailable.

Requires Permission: READ_PHONE_STATE

public boolean hasIccCard ()

Since: API Level 5

Returns
  • true if a ICC card is present

public boolean isNetworkRoaming ()

Since: API Level 1

Returns true if the device is considered roaming on the current network, for GSM purposes.

Availability: Only when user registered to a network.

public void listen (PhoneStateListener listener, int events)

Since: API Level 1

Registers a listener object to receive notification of changes in specified telephony states.

To register a listener, pass a PhoneStateListener and specify at least one telephony state of interest in the events argument. At registration, and when a specified telephony state changes, the telephony manager invokes the appropriate callback method on the listener object and passes the current (udpated) values.

To unregister a listener, pass the listener object and set the events argument to LISTEN_NONE (0).

Parameters
listener The PhoneStateListener object to register (or unregister)
events The telephony state(s) of interest to the listener, as a bitwise-OR combination of PhoneStateListener LISTEN_ flags.