FileDocCategorySizeDatePackage
TelephonyManager.javaAPI DocAndroid 1.5 API21402Wed May 06 22:42:00 BST 2009android.telephony

TelephonyManager

public class TelephonyManager extends Object
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 {@link android.content.Context#getSystemService Context.getSystemService(Context.TELEPHONY_SERVICE)}.

Note that acess 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.

Fields Summary
private static final String
TAG
private android.content.Context
mContext
private ITelephonyRegistry
mRegistry
private static TelephonyManager
sInstance
public static final String
ACTION_PHONE_STATE_CHANGED
Broadcast intent action indicating that the call state (cellular) on the device has changed.

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

Requires the READ_PHONE_STATE permission.

This was a {@link android.content.Context#sendStickyBroadcast sticky} broadcast in version 1.0, but it is no longer sticky. Instead, use {@link #getCallState} to synchronously query the current call state.

public static final String
EXTRA_STATE
The lookup key used with the {@link #ACTION_PHONE_STATE_CHANGED} broadcast for a String containing the new call state.
public static final String
EXTRA_STATE_IDLE
Value used with {@link #EXTRA_STATE} corresponding to {@link #CALL_STATE_IDLE}.
public static final String
EXTRA_STATE_RINGING
Value used with {@link #EXTRA_STATE} corresponding to {@link #CALL_STATE_RINGING}.
public static final String
EXTRA_STATE_OFFHOOK
Value used with {@link #EXTRA_STATE} corresponding to {@link #CALL_STATE_OFFHOOK}.
public static final String
EXTRA_INCOMING_NUMBER
The lookup key used with the {@link #ACTION_PHONE_STATE_CHANGED} broadcast for a String containing the incoming phone number. Only valid when the new call state is RINGING.

Retrieve with {@link android.content.Intent#getStringExtra(String)}.

public static final int
PHONE_TYPE_NONE
No phone module
public static final int
PHONE_TYPE_GSM
GSM phone
public static final int
NETWORK_TYPE_UNKNOWN
Network type is unknown
public static final int
NETWORK_TYPE_GPRS
Current network is GPRS
public static final int
NETWORK_TYPE_EDGE
Current network is EDGE
public static final int
NETWORK_TYPE_UMTS
Current network is UMTS
public static final int
SIM_STATE_UNKNOWN
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.
public static final int
SIM_STATE_ABSENT
SIM card state: no SIM card is available in the device
public static final int
SIM_STATE_PIN_REQUIRED
SIM card state: Locked: requires the user's SIM PIN to unlock
public static final int
SIM_STATE_PUK_REQUIRED
SIM card state: Locked: requires the user's SIM PUK to unlock
public static final int
SIM_STATE_NETWORK_LOCKED
SIM card state: Locked: requries a network PIN to unlock
public static final int
SIM_STATE_READY
SIM card state: Ready
public static final int
CALL_STATE_IDLE
Device call state: No activity.
public static final int
CALL_STATE_RINGING
Device call state: Ringing. A new call arrived and is ringing or waiting. In the latter case, another call is already active.
public static final int
CALL_STATE_OFFHOOK
Device call state: Off-hook. At least one call exists that is dialing, active, or on hold, and no calls are ringing or waiting.
public static final int
DATA_ACTIVITY_NONE
Data connection activity: No traffic.
public static final int
DATA_ACTIVITY_IN
Data connection activity: Currently receiving IP PPP traffic.
public static final int
DATA_ACTIVITY_OUT
Data connection activity: Currently sending IP PPP traffic.
public static final int
DATA_ACTIVITY_INOUT
Data connection activity: Currently both sending and receiving IP PPP traffic.
public static final int
DATA_DISCONNECTED
Data connection state: Disconnected. IP traffic not available.
public static final int
DATA_CONNECTING
Data connection state: Currently setting up a data connection.
public static final int
DATA_CONNECTED
Data connection state: Connected. IP traffic should be available.
public static final int
DATA_SUSPENDED
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.
Constructors Summary
public TelephonyManager(android.content.Context context)

hide


      
       
        mContext = context;
        mRegistry = ITelephonyRegistry.Stub.asInterface(ServiceManager.getService(
                    "telephony.registry"));
private TelephonyManager()

hide
Methods Summary
public voiddisableLocationUpdates()
Disables location update notifications. {@link PhoneStateListener#onCellLocationChanged PhoneStateListener.onCellLocationChanged} will be called on location updates.

Requires Permission: {@link android.Manifest.permission#CONTROL_LOCATION_UPDATES CONTROL_LOCATION_UPDATES}

hide

        try {
            getITelephony().disableLocationUpdates();
        } catch (RemoteException ex) {
        }
public voidenableLocationUpdates()
Enables location update notifications. {@link PhoneStateListener#onCellLocationChanged PhoneStateListener.onCellLocationChanged} will be called on location updates.

Requires Permission: {@link android.Manifest.permission#CONTROL_LOCATION_UPDATES CONTROL_LOCATION_UPDATES}

hide

        try {
            getITelephony().enableLocationUpdates();
        } catch (RemoteException ex) {
        }
public intgetCallState()
Returns a constant indicating the call state (cellular) on the device.


                    
       
        try {
            return getITelephony().getCallState();
        } catch (RemoteException ex) {
            // the phone process is restarting.
            return CALL_STATE_IDLE;
        }
public CellLocationgetCellLocation()
Returns the current location of the device.

Requires Permission: {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION}.

        try {
            Bundle bundle = getITelephony().getCellLocation();
            return CellLocation.newFromBundle(bundle);
        } catch (RemoteException ex) {
        }
        return null;
public intgetDataActivity()
Returns a constant indicating the type of activity on a data connection (cellular).

see
#DATA_ACTIVITY_NONE
see
#DATA_ACTIVITY_IN
see
#DATA_ACTIVITY_OUT
see
#DATA_ACTIVITY_INOUT


                              
       
        try {
            return getITelephony().getDataActivity();
        } catch (RemoteException ex) {
            // the phone process is restarting.
            return DATA_ACTIVITY_NONE;
        }
public intgetDataState()
Returns a constant indicating the current data connection state (cellular).

see
#DATA_DISCONNECTED
see
#DATA_CONNECTING
see
#DATA_CONNECTED
see
#DATA_SUSPENDED


                            
       
        try {
            return getITelephony().getDataState();
        } catch (RemoteException ex) {
            // the phone process is restarting.
            return DATA_DISCONNECTED;
        }
public static android.telephony.TelephonyManagergetDefault()

hide


      
        
        return sInstance;
public java.lang.StringgetDeviceId()
Returns the unique device ID, for example,the IMEI for GSM phones.

Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}

        try {
            return getSubscriberInfo().getDeviceId();
        } catch (RemoteException ex) {
        }
        return null;
public java.lang.StringgetDeviceSoftwareVersion()
Returns the software version number for the device, for example, the IMEI/SV for GSM phones.

Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}



    //
    //
    // Device Info
    //
    //

                                 
       
        try {
            return getSubscriberInfo().getDeviceSvn();
        } catch (RemoteException ex) {
        }
        return null;
private ITelephonygetITelephony()

        return ITelephony.Stub.asInterface(ServiceManager.getService(Context.TELEPHONY_SERVICE));
public java.lang.StringgetLine1AlphaTag()
Returns the alphabetic identifier associated with the line 1 number.

Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}

hide
nobody seems to call this.

        try {
            return getSubscriberInfo().getLine1AlphaTag();
        } catch (RemoteException ex) {
        }
        return null;
public java.lang.StringgetLine1Number()
Returns the phone number string for line 1, for example, the MSISDN for a GSM phone.

Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}

        try {
            return getSubscriberInfo().getLine1Number();
        } catch (RemoteException ex) {
        }
        return null;
public java.util.ListgetNeighboringCellInfo()
Returns the neighboring cell information of the device.

return
List of NeighboringCellInfo or null if info unavailable.

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

       try {
           return getITelephony().getNeighboringCellInfo();
       } catch (RemoteException ex) {
       }
       return null;
public java.lang.StringgetNetworkCountryIso()
Returns the ISO country code equivilent of the current registered operator's MCC (Mobile Country Code).

Availability: Only when user is registered to a network

        return SystemProperties.get(TelephonyProperties.PROPERTY_OPERATOR_ISO_COUNTRY);
public java.lang.StringgetNetworkOperator()
Returns the numeric name (MCC+MNC) of current registered operator.

Availability: Only when user is registered to a network

        return SystemProperties.get(TelephonyProperties.PROPERTY_OPERATOR_NUMERIC);
public java.lang.StringgetNetworkOperatorName()
Returns the alphabetic name of current registered operator.

Availability: Only when user is registered to a network

        return SystemProperties.get(TelephonyProperties.PROPERTY_OPERATOR_ALPHA);
public intgetNetworkType()
Returns a constant indicating the radio technology (network type) currently in use on the device.

return
the network type
see
#NETWORK_TYPE_UNKNOWN
see
#NETWORK_TYPE_GPRS
see
#NETWORK_TYPE_EDGE
see
#NETWORK_TYPE_UMTS


                                     
       
        String prop = SystemProperties.get(TelephonyProperties.PROPERTY_DATA_NETWORK_TYPE);
        if ("GPRS".equals(prop)) {
            return NETWORK_TYPE_GPRS;
        }
        else if ("EDGE".equals(prop)) {
            return NETWORK_TYPE_EDGE;
        }
        else if ("UMTS".equals(prop)) {
            return NETWORK_TYPE_UMTS;
        }
        else {
            return NETWORK_TYPE_UNKNOWN;
        }
public java.lang.StringgetNetworkTypeName()
Returns a string representation of the radio technology (network type) currently in use on the device.

return
the name of the radio technology
hide
pending API council review

        switch (getNetworkType()) {
            case NETWORK_TYPE_GPRS:
                return "GPRS";
            case NETWORK_TYPE_EDGE:
                return "EDGE";
            case NETWORK_TYPE_UMTS:
                return "UMTS";
            default:
                return "UNKNOWN";
        }
public intgetPhoneType()
Returns a constant indicating the device phone type.

see
#PHONE_TYPE_NONE
see
#PHONE_TYPE_GSM


                       
       
        // in the future, we should really check this
        return PHONE_TYPE_GSM;
public java.lang.StringgetSimCountryIso()
Returns the ISO country code equivalent for the SIM provider's country code.

        return SystemProperties.get(TelephonyProperties.PROPERTY_SIM_OPERATOR_ISO_COUNTRY);
public java.lang.StringgetSimOperator()
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 {@link #SIM_STATE_READY}

see
#getSimState

        return SystemProperties.get(TelephonyProperties.PROPERTY_SIM_OPERATOR_NUMERIC);
public java.lang.StringgetSimOperatorName()
Returns the Service Provider Name (SPN).

Availability: SIM state must be {@link #SIM_STATE_READY}

see
#getSimState

        return SystemProperties.get(TelephonyProperties.PROPERTY_SIM_OPERATOR_ALPHA);
public java.lang.StringgetSimSerialNumber()
Returns the serial number of the SIM, if applicable.

Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}

        try {
            return getSubscriberInfo().getSimSerialNumber();
        } catch (RemoteException ex) {
        }
        return null;
public intgetSimState()
Returns a constant indicating the state of the device SIM card.

see
#SIM_STATE_UNKNOWN
see
#SIM_STATE_ABSENT
see
#SIM_STATE_PIN_REQUIRED
see
#SIM_STATE_PUK_REQUIRED
see
#SIM_STATE_NETWORK_LOCKED
see
#SIM_STATE_READY

    
                                   
       
        String prop = SystemProperties.get(TelephonyProperties.PROPERTY_SIM_STATE);
        if ("ABSENT".equals(prop)) {
            return SIM_STATE_ABSENT;
        }
        else if ("PIN_REQUIRED".equals(prop)) {
            return SIM_STATE_PIN_REQUIRED;
        }
        else if ("PUK_REQUIRED".equals(prop)) {
            return SIM_STATE_PUK_REQUIRED;
        }
        else if ("NETWORK_LOCKED".equals(prop)) {
            return SIM_STATE_NETWORK_LOCKED;
        }
        else if ("READY".equals(prop)) {
            return SIM_STATE_READY;
        }
        else {
            return SIM_STATE_UNKNOWN;
        }
public java.lang.StringgetSubscriberId()
Returns the unique subscriber ID, for example, the IMSI for a GSM phone.

Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}

        try {
            return getSubscriberInfo().getSubscriberId();
        } catch (RemoteException ex) {
        }
        return null;
private IPhoneSubInfogetSubscriberInfo()

        // get it each time because that process crashes a lot
        return IPhoneSubInfo.Stub.asInterface(ServiceManager.getService("iphonesubinfo"));
public java.lang.StringgetVoiceMailAlphaTag()
Retrieves the alphabetic identifier associated with the voice mail number.

Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}

        try {
            return getSubscriberInfo().getVoiceMailAlphaTag();
        } catch (RemoteException ex) {
        }
        return null;
public java.lang.StringgetVoiceMailNumber()
Returns the voice mail number.

Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}

        try {
            return getSubscriberInfo().getVoiceMailNumber();
        } catch (RemoteException ex) {
        }
        return null;
public booleanisNetworkRoaming()
Returns true if the device is considered roaming on the current network, for GSM purposes.

Availability: Only when user registered to a network

        return "true".equals(SystemProperties.get(TelephonyProperties.PROPERTY_OPERATOR_ISROAMING));
public voidlisten(PhoneStateListener listener, int events)
Registers a listener object to receive notification of changes in specified telephony states.

To register a listener, pass a {@link 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 {@link PhoneStateListener#LISTEN_NONE LISTEN_NONE} (0).

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

        String pkgForDebug = mContext != null ? mContext.getPackageName() : "<unknown>";
        try {
            Boolean notifyNow = (getITelephony() != null);
            mRegistry.listen(pkgForDebug, listener.callback, events, notifyNow);
        } catch (RemoteException ex) {
            // system process dead
        }