# Print output for @column tags ?>
public
class
PhoneStateListener
extends Object
java.lang.Object | |
↳ | android.telephony.PhoneStateListener |
A listener class for monitoring changes in specific telephony states on the device, including service state, signal strength, message waiting indicator (voicemail), and others.
Override the methods for the state that you wish to receive updates for, and
pass your PhoneStateListener object, along with bitwise-or of the LISTEN_
flags to TelephonyManager#listen
. Methods are
called when the state changes, as well as once on initial registration.
Note that access to some telephony information is permission-protected. Your application won't receive updates for protected information unless it has the appropriate permissions declared in its manifest file. Where permissions apply, they are noted in the appropriate LISTEN_ flags.
Constants | |
---|---|
int |
LISTEN_ACTIVE_DATA_SUBSCRIPTION_ID_CHANGE
Listen for changes to active data subId. |
int |
LISTEN_BARRING_INFO
Listen for Barring Information for the current registered / camped cell. |
int |
LISTEN_CALL_DISCONNECT_CAUSES
Listen for call disconnect causes which contains |
int |
LISTEN_CALL_FORWARDING_INDICATOR
Listen for changes to the call-forwarding indicator. |
int |
LISTEN_CALL_STATE
Listen for changes to the device call state. |
int |
LISTEN_CELL_INFO
Listen for changes to observed cell info. |
int |
LISTEN_CELL_LOCATION
Listen for changes to the device's cell location. Note that this will result in frequent callbacks to the listener. |
int |
LISTEN_DATA_ACTIVITY
Listen for changes to the direction of data traffic on the data connection (cellular). |
int |
LISTEN_DATA_CONNECTION_STATE
Listen for changes to the data connection state (cellular). |
int |
LISTEN_DISPLAY_INFO_CHANGED
Listen for display info changed event. |
int |
LISTEN_EMERGENCY_NUMBER_LIST
Listen for changes to emergency number list based on all active subscriptions. |
int |
LISTEN_IMS_CALL_DISCONNECT_CAUSES
Listen for IMS call disconnect causes which contains
Requires permission |
int |
LISTEN_MESSAGE_WAITING_INDICATOR
Listen for changes to the message-waiting indicator. |
int |
LISTEN_NONE
Stop listening for updates. |
int |
LISTEN_PRECISE_DATA_CONNECTION_STATE
Listen for |
int |
LISTEN_REGISTRATION_FAILURE
Listen for Registration Failures. |
int |
LISTEN_SERVICE_STATE
Listen for changes to the network service state (cellular). |
int |
LISTEN_SIGNAL_STRENGTH
This constant is deprecated.
by |
int |
LISTEN_SIGNAL_STRENGTHS
Listen for changes to the network signal strengths (cellular). |
int |
LISTEN_USER_MOBILE_DATA_STATE
Listen for changes to the user mobile data state |
Public constructors | |
---|---|
PhoneStateListener()
Create a PhoneStateListener for the Phone with the default subscription. |
|
PhoneStateListener(Executor executor)
Create a PhoneStateListener for the Phone using the specified Executor Create a PhoneStateListener with a specified Executor for handling necessary callbacks. |
Public methods | |
---|---|
void
|
onActiveDataSubscriptionIdChanged(int subId)
Callback invoked when active data subId changes. |
void
|
onBarringInfoChanged(BarringInfo barringInfo)
Report updated barring information for the current camped/registered cell. |
void
|
onCallDisconnectCauseChanged(int disconnectCause, int preciseDisconnectCause)
Callback invoked when call disconnect cause changes on the registered subscription. |
void
|
onCallForwardingIndicatorChanged(boolean cfi)
Callback invoked when the call-forwarding indicator changes on the registered subscription. |
void
|
onCallStateChanged(int state, String phoneNumber)
Callback invoked when device call state changes. |
void
|
onCellInfoChanged(List<CellInfo> cellInfo)
Callback invoked when a observed cell info has changed or new cells have been added or removed on the registered subscription. |
void
|
onCellLocationChanged(CellLocation location)
Callback invoked when device cell location changes on the registered subscription. |
void
|
onDataActivity(int direction)
Callback invoked when data activity state changes on the registered subscription. |
void
|
onDataConnectionStateChanged(int state, int networkType)
same as above, but with the network type. |
void
|
onDataConnectionStateChanged(int state)
Callback invoked when connection state changes on the registered subscription. |
void
|
onDisplayInfoChanged(TelephonyDisplayInfo telephonyDisplayInfo)
Callback invoked when the display info has changed on the registered subscription. |
void
|
onImsCallDisconnectCauseChanged(ImsReasonInfo imsReasonInfo)
Callback invoked when Ims call disconnect cause changes on the registered subscription. |
void
|
onMessageWaitingIndicatorChanged(boolean mwi)
Callback invoked when the message-waiting indicator changes on the registered subscription. |
void
|
onPreciseDataConnectionStateChanged(PreciseDataConnectionState dataConnectionState)
Callback providing update about the default/internet data connection on the registered subscription. |
void
|
onRegistrationFailed(CellIdentity cellIdentity, String chosenPlmn, int domain, int causeCode, int additionalCauseCode)
Report that Registration or a Location/Routing/Tracking Area update has failed. |
void
|
onServiceStateChanged(ServiceState serviceState)
Callback invoked when device service state changes on the registered subscription. |
void
|
onSignalStrengthChanged(int asu)
This method is deprecated.
Use |
void
|
onSignalStrengthsChanged(SignalStrength signalStrength)
Callback invoked when network signal strengths changes on the registered subscription. |
void
|
onUserMobileDataStateChanged(boolean enabled)
Callback invoked when the user mobile data state has changed on the registered subscription. |
Inherited methods | |
---|---|
public static final int LISTEN_ACTIVE_DATA_SUBSCRIPTION_ID_CHANGE
Listen for changes to active data subId. Active data subscription is the current subscription used to setup Cellular Internet data. For example, it could be the current active opportunistic subscription in use, or the subscription user selected as default data subscription in DSDS mode.
See also:
Constant Value: 4194304 (0x00400000)
public static final int LISTEN_BARRING_INFO
Listen for Barring Information for the current registered / camped cell.
Requires permission Manifest.permission.READ_PRECISE_PHONE_STATE
or
the calling app has carrier privileges (see TelephonyManager#hasCarrierPrivileges
).
Also requires the Manifest.permission#ACCESS_FINE_LOCATION
permission, regardless
of whether the calling app has carrier privileges.
Requires Manifest.permission.READ_PRECISE_PHONE_STATE
See also:
Constant Value: -2147483648 (0x80000000)
public static final int LISTEN_CALL_DISCONNECT_CAUSES
Listen for call disconnect causes which contains DisconnectCause
and
PreciseDisconnectCause
.
Requires permission Manifest.permission.READ_PRECISE_PHONE_STATE
or the calling app has carrier privileges
(see TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.READ_PRECISE_PHONE_STATE
Constant Value: 33554432 (0x02000000)
public static final int LISTEN_CALL_FORWARDING_INDICATOR
Listen for changes to the call-forwarding indicator.
Requires Permission: READ_PHONE_STATE
or that the calling app has carrier privileges (see
TelephonyManager#hasCarrierPrivileges
).
Constant Value: 8 (0x00000008)
public static final int LISTEN_CALL_STATE
Listen for changes to the device call state.
See also:
Constant Value: 32 (0x00000020)
public static final int LISTEN_CELL_INFO
Listen for changes to observed cell info.
Listening to this event requires the Manifest.permission#ACCESS_FINE_LOCATION
permission.
See also:
Constant Value: 1024 (0x00000400)
public static final int LISTEN_CELL_LOCATION
Listen for changes to the device's cell location. Note that this will result in frequent callbacks to the listener.
Requires Permission: ACCESS_FINE_LOCATION
If you need regular location updates but want more control over
the update interval or location precision, you can set up a listener
through the location manager
instead.
See also:
Constant Value: 16 (0x00000010)
public static final int LISTEN_DATA_ACTIVITY
Listen for changes to the direction of data traffic on the data connection (cellular).
Example: The status bar uses this to display the appropriate data-traffic icon.
See also:
Constant Value: 128 (0x00000080)
public static final int LISTEN_DATA_CONNECTION_STATE
Listen for changes to the data connection state (cellular).
See also:
Constant Value: 64 (0x00000040)
public static final int LISTEN_DISPLAY_INFO_CHANGED
Listen for display info changed event.
Requires Permission: READ_PHONE_STATE
or that the calling app has carrier privileges (see
TelephonyManager#hasCarrierPrivileges
).
Constant Value: 1048576 (0x00100000)
public static final int LISTEN_EMERGENCY_NUMBER_LIST
Listen for changes to emergency number list based on all active subscriptions.
Requires permission Manifest.permission.READ_PHONE_STATE
or the calling
app has carrier privileges (see TelephonyManager#hasCarrierPrivileges
).
Constant Value: 16777216 (0x01000000)
public static final int LISTEN_IMS_CALL_DISCONNECT_CAUSES
Listen for IMS call disconnect causes which contains
ImsReasonInfo
Requires permission Manifest.permission.READ_PRECISE_PHONE_STATE
or the calling app has carrier privileges
(see TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.READ_PRECISE_PHONE_STATE
Constant Value: 134217728 (0x08000000)
public static final int LISTEN_MESSAGE_WAITING_INDICATOR
Listen for changes to the message-waiting indicator.
Requires Permission: READ_PHONE_STATE
or that the calling app has carrier privileges (see
TelephonyManager#hasCarrierPrivileges
).
Example: The status bar uses this to determine when to display the voicemail icon.
Constant Value: 4 (0x00000004)
public static final int LISTEN_NONE
Stop listening for updates. The PhoneStateListener is not tied to any subscription and unregistered for any update.
Constant Value: 0 (0x00000000)
public static final int LISTEN_PRECISE_DATA_CONNECTION_STATE
Listen for PreciseDataConnectionState
on the data connection (cellular).
Requires permission Manifest.permission.READ_PRECISE_PHONE_STATE
or the calling app has carrier privileges
(see TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.READ_PRECISE_PHONE_STATE
Constant Value: 4096 (0x00001000)
public static final int LISTEN_REGISTRATION_FAILURE
Listen for Registration Failures.
Listen for indications that a registration procedure has failed in either the CS or PS
domain. This indication does not necessarily indicate a change of service state, which should
be tracked via LISTEN_SERVICE_STATE
.
Requires permission Manifest.permission.READ_PRECISE_PHONE_STATE
or
the calling app has carrier privileges (see TelephonyManager#hasCarrierPrivileges
).
Also requires the Manifest.permission#ACCESS_FINE_LOCATION
permission, regardless
of whether the calling app has carrier privileges.
Requires Manifest.permission.READ_PRECISE_PHONE_STATE
Constant Value: 1073741824 (0x40000000)
public static final int LISTEN_SERVICE_STATE
Listen for changes to the network service state (cellular).
Constant Value: 1 (0x00000001)
public static final int LISTEN_SIGNAL_STRENGTH
This constant is deprecated.
by LISTEN_SIGNAL_STRENGTHS
Listen for changes to the network signal strength (cellular).
See also:
Constant Value: 2 (0x00000002)
public static final int LISTEN_SIGNAL_STRENGTHS
Listen for changes to the network signal strengths (cellular).
Example: The status bar uses this to control the signal-strength icon.
See also:
Constant Value: 256 (0x00000100)
public static final int LISTEN_USER_MOBILE_DATA_STATE
Listen for changes to the user mobile data state
See also:
Constant Value: 524288 (0x00080000)
public PhoneStateListener ()
Create a PhoneStateListener for the Phone with the default subscription. This class requires Looper.myLooper() not return null.
public PhoneStateListener (Executor executor)
Create a PhoneStateListener for the Phone using the specified Executor
Create a PhoneStateListener with a specified Executor for handling necessary callbacks. The Executor must not be null.
Parameters | |
---|---|
executor |
Executor : a non-null Executor that will execute callbacks for the PhoneStateListener.
This value cannot be null . |
public void onActiveDataSubscriptionIdChanged (int subId)
Callback invoked when active data subId changes. Note, this callback triggers regardless of registered subscription. Requires the READ_PHONE_STATE permission.
Parameters | |
---|---|
subId |
int : current subscription used to setup Cellular Internet data.
For example, it could be the current active opportunistic subscription in use,
or the subscription user selected as default data subscription in DSDS mode. |
public void onBarringInfoChanged (BarringInfo barringInfo)
Report updated barring information for the current camped/registered cell.
Barring info is provided for all services applicable to the current camped/registered cell, for the registered PLMN and current access class/access category.
Parameters | |
---|---|
barringInfo |
BarringInfo : for all services on the current cell.
This value cannot be null . |
See also:
public void onCallDisconnectCauseChanged (int disconnectCause, int preciseDisconnectCause)
Callback invoked when call disconnect cause changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Requires Manifest.permission.READ_PRECISE_PHONE_STATE
Parameters | |
---|---|
disconnectCause |
int : DisconnectCause . |
preciseDisconnectCause |
int : PreciseDisconnectCause . |
public void onCallForwardingIndicatorChanged (boolean cfi)
Callback invoked when the call-forwarding indicator changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
cfi |
boolean |
public void onCallStateChanged (int state, String phoneNumber)
Callback invoked when device call state changes.
Reports the state of Telephony (mobile) calls on the device for the registered subscription.
Note: the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Note: The state returned here may differ from that returned by
TelephonyManager#getCallState()
. Receivers of this callback should be aware that
calling TelephonyManager#getCallState()
from within this callback may return a
different state than the callback reports.
Parameters | |
---|---|
state |
int : call state
Value is TelephonyManager.CALL_STATE_IDLE , TelephonyManager.CALL_STATE_RINGING , or TelephonyManager.CALL_STATE_OFFHOOK |
phoneNumber |
String : call phone number. If application does not have
READ_CALL_LOG permission or carrier
privileges (see TelephonyManager#hasCarrierPrivileges ), an empty string will be
passed as an argument. |
public void onCellInfoChanged (List<CellInfo> cellInfo)
Callback invoked when a observed cell info has changed or new cells have been added
or removed on the registered subscription.
Note, the registration subId s from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
cellInfo |
List : is the list of currently visible cells. |
public void onCellLocationChanged (CellLocation location)
Callback invoked when device cell location changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
location |
CellLocation |
public void onDataActivity (int direction)
Callback invoked when data activity state changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
direction |
int |
public void onDataConnectionStateChanged (int state, int networkType)
same as above, but with the network type. Both called.
Parameters | |
---|---|
state |
int |
networkType |
int |
public void onDataConnectionStateChanged (int state)
Callback invoked when connection state changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
state |
int |
public void onDisplayInfoChanged (TelephonyDisplayInfo telephonyDisplayInfo)
Callback invoked when the display info has changed on the registered subscription.
The TelephonyDisplayInfo
contains status information shown to the user based on
carrier policy.
Requires Permission: Manifest.permission.READ_PHONE_STATE
or that the calling
app has carrier privileges (see TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.READ_PHONE_STATE
Parameters | |
---|---|
telephonyDisplayInfo |
TelephonyDisplayInfo : The display information.
This value cannot be null . |
public void onImsCallDisconnectCauseChanged (ImsReasonInfo imsReasonInfo)
Callback invoked when Ims call disconnect cause changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Requires Manifest.permission.READ_PRECISE_PHONE_STATE
Parameters | |
---|---|
imsReasonInfo |
ImsReasonInfo : ImsReasonInfo contains details on why IMS call failed.
This value cannot be null . |
public void onMessageWaitingIndicatorChanged (boolean mwi)
Callback invoked when the message-waiting indicator changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
mwi |
boolean |
public void onPreciseDataConnectionStateChanged (PreciseDataConnectionState dataConnectionState)
Callback providing update about the default/internet data connection on the registered
subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Requires permission Manifest.permission.MODIFY_PHONE_STATE
or the calling app has carrier privileges
(see TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.MODIFY_PHONE_STATE
Parameters | |
---|---|
dataConnectionState |
PreciseDataConnectionState : PreciseDataConnectionState
This value cannot be null . |
public void onRegistrationFailed (CellIdentity cellIdentity, String chosenPlmn, int domain, int causeCode, int additionalCauseCode)
Report that Registration or a Location/Routing/Tracking Area update has failed.
Indicate whenever a registration procedure, including a location, routing, or tracking area update fails. This includes procedures that do not necessarily result in a change of the modem's registration status. If the modem's registration status changes, that is reflected in the onNetworkStateChanged() and subsequent get{Voice/Data}RegistrationState().
Because registration failures are ephemeral, this callback is not sticky. Registrants will not receive the most recent past value when registering.
Parameters | |
---|---|
cellIdentity |
CellIdentity : the CellIdentity, which must include the globally unique identifier
for the cell (for example, all components of the CGI or ECGI).
This value cannot be null . |
chosenPlmn |
String : a 5 or 6 digit alphanumeric PLMN (MCC|MNC) among those broadcast by the
cell that was chosen for the failed registration attempt.
This value cannot be null . |
domain |
int : DOMAIN_CS, DOMAIN_PS or both in case of a combined procedure. |
causeCode |
int : the primary failure cause code of the procedure.
For GSM/UMTS (MM), values are in TS 24.008 Sec 10.5.95
For GSM/UMTS (GMM), values are in TS 24.008 Sec 10.5.147
For LTE (EMM), cause codes are TS 24.301 Sec 9.9.3.9
For NR (5GMM), cause codes are TS 24.501 Sec 9.11.3.2
Integer.MAX_VALUE if this value is unused. |
additionalCauseCode |
int : the cause code of any secondary/combined procedure if appropriate.
For UMTS, if a combined attach succeeds for PS only, then the GMM cause code shall be
included as an additionalCauseCode. For LTE (ESM), cause codes are in
TS 24.301 9.9.4.4. Integer.MAX_VALUE if this value is unused. |
public void onServiceStateChanged (ServiceState serviceState)
Callback invoked when device service state changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
The instance of ServiceState
passed as an argument here will have various levels of
location information stripped from it depending on the location permissions that your app
holds. Only apps holding the Manifest.permission#ACCESS_FINE_LOCATION
permission will
receive all the information in ServiceState
.
Parameters | |
---|---|
serviceState |
ServiceState |
public void onSignalStrengthChanged (int asu)
This method is deprecated.
Use onSignalStrengthsChanged(android.telephony.SignalStrength)
Callback invoked when network signal strength changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
asu |
int |
public void onSignalStrengthsChanged (SignalStrength signalStrength)
Callback invoked when network signal strengths changes on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
signalStrength |
SignalStrength |
public void onUserMobileDataStateChanged (boolean enabled)
Callback invoked when the user mobile data state has changed on the registered subscription.
Note, the registration subId comes from TelephonyManager
object which registers
PhoneStateListener by TelephonyManager#listen(PhoneStateListener, int)
.
If this TelephonyManager object was created with
TelephonyManager#createForSubscriptionId(int)
, then the callback applies to the
subId. Otherwise, this callback applies to
SubscriptionManager#getDefaultSubscriptionId()
.
Parameters | |
---|---|
enabled |
boolean : indicates whether the current user mobile data state is enabled or disabled. |