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.
String ACTION_RESPOND_VIA_MESSAGE The Phone app sends this intent when a user opts to respond-via-message during an incoming call.
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
List<CellInfo> getAllCellInfo()
Returns all observed cell information from all radios on the device including the primary and neighboring cells.
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 getGroupIdLevel1()
Returns the Group Identifier Level1 for a GSM phone.
String getLine1Number()
Returns the phone number string for line 1, for example, the MSISDN for a GSM phone.
String getMmsUAProfUrl()
Returns the MMS user agent profile URL.
String getMmsUserAgent()
Returns the MMS user agent.
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()
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

Added in 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 String ACTION_RESPOND_VIA_MESSAGE

Added in API level 18

The Phone app sends this intent when a user opts to respond-via-message during an incoming call. By default, the device's default SMS app consumes this message and sends a text message to the caller. A third party app can also provide this functionality by consuming this Intent with a Service and sending the message using its own messaging system.

The intent contains a URI (available from getData()) describing the recipient, using either the sms:, smsto:, mms:, or mmsto: URI schema. Each of these URI schema carry the recipient information the same way: the path part of the URI contains the recipient's phone number or a comma-separated set of phone numbers if there are multiple recipients. For example, smsto:2065551234.

The intent may also contain extras for the message text (in EXTRA_TEXT) and a message subject (in EXTRA_SUBJECT).

Note: The intent-filter that consumes this Intent needs to be in a Service that requires the permission SEND_RESPOND_VIA_MESSAGE.

For example, the service that receives this intent can be declared in the manifest file with an intent filter like this:

 <!-- Service that delivers SMS messages received from the phone "quick response" -->
 <service android:name=".HeadlessSmsSendService"
          android:permission="android.permission.SEND_RESPOND_VIA_MESSAGE"
          android:exported="true" >
   <intent-filter>
     <action android:name="android.intent.action.RESPOND_VIA_MESSAGE" />
     <category android:name="android.intent.category.DEFAULT" />
     <data android:scheme="sms" />
     <data android:scheme="smsto" />
     <data android:scheme="mms" />
     <data android:scheme="mmsto" />
   </intent-filter>
 </service>

Output: nothing.

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

public static final int CALL_STATE_IDLE

Added in API level 1

Device call state: No activity.

Constant Value: 0 (0x00000000)

public static final int CALL_STATE_OFFHOOK

Added in 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

Added in 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

Added in API level 4

Data connection is active, but physical link is down

Constant Value: 4 (0x00000004)

public static final int DATA_ACTIVITY_IN

Added in API level 1

Data connection activity: Currently receiving IP PPP traffic.

Constant Value: 1 (0x00000001)

public static final int DATA_ACTIVITY_INOUT

Added in 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

Added in API level 1

Data connection activity: No traffic.

Constant Value: 0 (0x00000000)

public static final int DATA_ACTIVITY_OUT

Added in API level 1

Data connection activity: Currently sending IP PPP traffic.

Constant Value: 2 (0x00000002)

public static final int DATA_CONNECTED

Added in API level 1

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

Constant Value: 2 (0x00000002)

public static final int DATA_CONNECTING

Added in API level 1

Data connection state: Currently setting up a data connection.

Constant Value: 1 (0x00000001)

public static final int DATA_DISCONNECTED

Added in API level 1

Data connection state: Disconnected. IP traffic not available.

Constant Value: 0 (0x00000000)

public static final int DATA_SUSPENDED

Added in 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

Added in 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

Added in 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

Added in API level 4

Current network is 1xRTT

Constant Value: 7 (0x00000007)

public static final int NETWORK_TYPE_CDMA

Added in API level 4

Current network is CDMA: Either IS95A or IS95B

Constant Value: 4 (0x00000004)

public static final int NETWORK_TYPE_EDGE

Added in API level 1

Current network is EDGE

Constant Value: 2 (0x00000002)

public static final int NETWORK_TYPE_EHRPD

Added in API level 11

Current network is eHRPD

Constant Value: 14 (0x0000000e)

public static final int NETWORK_TYPE_EVDO_0

Added in API level 4

Current network is EVDO revision 0

Constant Value: 5 (0x00000005)

public static final int NETWORK_TYPE_EVDO_A

Added in API level 4

Current network is EVDO revision A

Constant Value: 6 (0x00000006)

public static final int NETWORK_TYPE_EVDO_B

Added in API level 9

Current network is EVDO revision B

Constant Value: 12 (0x0000000c)

public static final int NETWORK_TYPE_GPRS

Added in API level 1

Current network is GPRS

Constant Value: 1 (0x00000001)

public static final int NETWORK_TYPE_HSDPA

Added in API level 5

Current network is HSDPA

Constant Value: 8 (0x00000008)

public static final int NETWORK_TYPE_HSPA

Added in API level 5

Current network is HSPA

Constant Value: 10 (0x0000000a)

public static final int NETWORK_TYPE_HSPAP

Added in API level 13

Current network is HSPA+

Constant Value: 15 (0x0000000f)

public static final int NETWORK_TYPE_HSUPA

Added in API level 5

Current network is HSUPA

Constant Value: 9 (0x00000009)

public static final int NETWORK_TYPE_IDEN

Added in API level 8

Current network is iDen

Constant Value: 11 (0x0000000b)

public static final int NETWORK_TYPE_LTE

Added in API level 11

Current network is LTE

Constant Value: 13 (0x0000000d)

public static final int NETWORK_TYPE_UMTS

Added in API level 1

Current network is UMTS

Constant Value: 3 (0x00000003)

public static final int NETWORK_TYPE_UNKNOWN

Added in API level 1

Network type is unknown

Constant Value: 0 (0x00000000)

public static final int PHONE_TYPE_CDMA

Added in API level 4

Phone radio is CDMA.

Constant Value: 2 (0x00000002)

public static final int PHONE_TYPE_GSM

Added in API level 1

Phone radio is GSM.

Constant Value: 1 (0x00000001)

public static final int PHONE_TYPE_NONE

Added in API level 1

No phone radio.

Constant Value: 0 (0x00000000)

public static final int PHONE_TYPE_SIP

Added in API level 11

Phone is via SIP.

Constant Value: 3 (0x00000003)

public static final int SIM_STATE_ABSENT

Added in 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

Added in 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

Added in 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

Added in 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

Added in API level 1

SIM card state: Ready

Constant Value: 5 (0x00000005)

public static final int SIM_STATE_UNKNOWN

Added in 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

Added in API level 3

Value used with EXTRA_STATE corresponding to CALL_STATE_IDLE.

public static final String EXTRA_STATE_OFFHOOK

Added in API level 3

Value used with EXTRA_STATE corresponding to CALL_STATE_OFFHOOK.

public static final String EXTRA_STATE_RINGING

Added in API level 3

Value used with EXTRA_STATE corresponding to CALL_STATE_RINGING.

Public Methods

public List<CellInfo> getAllCellInfo ()

Added in API level 17

Returns all observed cell information from all radios on the device including the primary and neighboring cells. This does not cause or change the rate of PhoneStateListner#onCellInfoChanged.

The list can include one or more of CellInfoGsm, CellInfoCdma, CellInfoLte and CellInfoCdma in any combination. Specifically on devices with multiple radios it is typical to see instances of one or more of any these in the list. In addition 0, 1 or more CellInfo objects may return isRegistered() true.

This is preferred over using getCellLocation although for older devices this may return null in which case getCellLocation should be called.

Returns

public int getCallState ()

Added in API level 1

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

public CellLocation getCellLocation ()

Added in API level 1

Returns the current location of the device.

If there is only one radio in the device and that radio has an LTE connection, this method will return null. The implementation must not to try add LTE identifiers into the existing cdma/gsm classes.

In the future this call will be deprecated.

Returns

public int getDataActivity ()

Added in API level 1

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

public int getDataState ()

Added in API level 1

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

public String getDeviceId ()

Added in 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 ()

Added in 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 getGroupIdLevel1 ()

Added in API level 18

Returns the Group Identifier Level1 for a GSM phone. Return null if it is unavailable.

Requires Permission: READ_PHONE_STATE

public String getLine1Number ()

Added in 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 String getMmsUAProfUrl ()

Added in API level 19

Returns the MMS user agent profile URL.

public String getMmsUserAgent ()

Added in API level 19

Returns the MMS user agent.

public List<NeighboringCellInfo> getNeighboringCellInfo ()

Added in API level 3

Returns the neighboring cell information of the device. The getAllCellInfo is preferred and use this only if getAllCellInfo return nulls or an empty list.

In the future this call will be deprecated.

Returns
  • List of NeighboringCellInfo or null if info unavailable.

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

public String getNetworkCountryIso ()

Added in 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 ()

Added in 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 ()

Added in 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 getNetworkType ()

Added in API level 1

Returns
  • the NETWORK_TYPE_xxxx for current data connection.

public int getPhoneType ()

Added in 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 ()

Added in API level 1

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

public String getSimOperator ()

Added in 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 ()

Added in API level 1

Returns the Service Provider Name (SPN).

Availability: SIM state must be SIM_STATE_READY

See Also

public String getSimSerialNumber ()

Added in 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 ()

Added in API level 1

public String getSubscriberId ()

Added in 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 ()

Added in API level 1

Retrieves the alphabetic identifier associated with the voice mail number.

Requires Permission: READ_PHONE_STATE

public String getVoiceMailNumber ()

Added in API level 1

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

Requires Permission: READ_PHONE_STATE

public boolean hasIccCard ()

Added in API level 5

Returns
  • true if a ICC card is present

public boolean isNetworkRoaming ()

Added in 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)

Added in 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 (updated) 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.