SubscriptionManager
public
class
SubscriptionManager
extends Object
java.lang.Object | |
↳ | android.telephony.SubscriptionManager |
Subscription manager provides the mobile subscription information.
Requires the PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Summary
Nested classes | |
---|---|
class |
SubscriptionManager.OnOpportunisticSubscriptionsChangedListener
A listener class for monitoring changes to |
class |
SubscriptionManager.OnSubscriptionsChangedListener
A listener class for monitoring changes to |
Constants | |
---|---|
String |
ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED
Broadcast Action: The default sms subscription has changed. |
String |
ACTION_DEFAULT_SUBSCRIPTION_CHANGED
Broadcast Action: The default subscription has changed. |
String |
ACTION_MANAGE_SUBSCRIPTION_PLANS
Activity Action: Display UI for managing the billing relationship plans between a carrier and a specific subscriber. |
String |
ACTION_REFRESH_SUBSCRIPTION_PLANS
Broadcast Action: Request a refresh of the billing relationship plans between a carrier and a specific subscriber. |
int |
D2D_SHARING_ALL
Device status is shared whenever possible. |
int |
D2D_SHARING_ALL_CONTACTS
Device status is shared with all numbers in the user's contacts. |
int |
D2D_SHARING_DISABLED
Device status is not shared to a remote party. |
int |
D2D_SHARING_SELECTED_CONTACTS
Device status is shared with all selected contacts. |
String |
D2D_STATUS_SHARING
TelephonyProvider column name for device to device sharing status. |
String |
D2D_STATUS_SHARING_SELECTED_CONTACTS
TelephonyProvider column name for contacts information that allow device to device sharing. |
int |
DATA_ROAMING_DISABLE
Indicates that data roaming is disabled for a subscription |
int |
DATA_ROAMING_ENABLE
Indicates that data roaming is enabled for a subscription |
int |
DEFAULT_SUBSCRIPTION_ID
Indicates the default subscription ID in Telephony. |
String |
EXTRA_SLOT_INDEX
Integer extra to specify SIM slot index. |
String |
EXTRA_SUBSCRIPTION_INDEX
Integer extra used with |
int |
INVALID_SIM_SLOT_INDEX
Indicates invalid sim slot. |
int |
INVALID_SUBSCRIPTION_ID
An invalid subscription identifier |
int |
PHONE_NUMBER_SOURCE_CARRIER
A source of phone number: provided by an app that has carrier privilege. |
int |
PHONE_NUMBER_SOURCE_IMS
A source of phone number: provided by IMS (IP Multimedia Subsystem) implementation. |
int |
PHONE_NUMBER_SOURCE_UICC
A source of phone number: the EF-MSISDN (see 3GPP TS 31.102), or EF-MDN for CDMA (see 3GPP2 C.P0065-B), from UICC application. |
int |
SERVICE_CAPABILITY_DATA
Represents a value indicating the data calling capabilities of a subscription. |
int |
SERVICE_CAPABILITY_SMS
Represents a value indicating the SMS capabilities of a subscription. |
int |
SERVICE_CAPABILITY_VOICE
Represents a value indicating the voice calling capabilities of a subscription. |
int |
SUBSCRIPTION_TYPE_LOCAL_SIM
This constant is to designate a subscription as a Local-SIM Subscription. |
int |
SUBSCRIPTION_TYPE_REMOTE_SIM
This constant is to designate a subscription as a Remote-SIM Subscription. |
int |
USAGE_SETTING_DATA_CENTRIC
This subscription is forced to data-centric mode Refer to data-centric mode in 3gpp 24.301 sec 4.3 and 3gpp 24.501 sec 4.3. |
int |
USAGE_SETTING_DEFAULT
Subscription uses the default setting. |
int |
USAGE_SETTING_UNKNOWN
The usage setting is unknown. |
int |
USAGE_SETTING_VOICE_CENTRIC
This subscription is forced to voice-centric mode Refer to voice-centric mode in 3gpp 24.301 sec 4.3 and 3gpp 24.501 sec 4.3. |
Public methods | |
---|---|
void
|
addOnOpportunisticSubscriptionsChangedListener(Executor executor, SubscriptionManager.OnOpportunisticSubscriptionsChangedListener listener)
Register for changes to the list of opportunistic subscription records or to the individual records themselves. |
void
|
addOnSubscriptionsChangedListener(SubscriptionManager.OnSubscriptionsChangedListener listener)
This method was deprecated
in API level 31.
Will get exception if the parameter listener is not initialized with a Looper.
Use |
void
|
addOnSubscriptionsChangedListener(Executor executor, SubscriptionManager.OnSubscriptionsChangedListener listener)
Register for changes to the list of |
void
|
addSubscriptionsIntoGroup(List<Integer> subIdList, ParcelUuid groupUuid)
Add a list of subscriptions into a group. |
boolean
|
canManageSubscription(SubscriptionInfo info)
Checks whether the app with the given context is authorized to manage the given subscription according to its metadata. |
ParcelUuid
|
createSubscriptionGroup(List<Integer> subIdList)
Inform SubscriptionManager that subscriptions in the list are bundled as a group. |
static
SubscriptionManager
|
from(Context context)
This method was deprecated
in API level 28.
developers should always obtain references directly from
|
List<SubscriptionInfo>
|
getAccessibleSubscriptionInfoList()
Gets the SubscriptionInfo(s) of all embedded subscriptions accessible to the calling app, if any. |
static
int
|
getActiveDataSubscriptionId()
Get active data subscription id. |
SubscriptionInfo
|
getActiveSubscriptionInfo(int subId)
Get the active SubscriptionInfo with the input subId. |
int
|
getActiveSubscriptionInfoCount()
Get the active subscription count. |
int
|
getActiveSubscriptionInfoCountMax()
|
SubscriptionInfo
|
getActiveSubscriptionInfoForSimSlotIndex(int slotIndex)
Get the active SubscriptionInfo associated with the slotIndex Requires Permission: |
List<SubscriptionInfo>
|
getActiveSubscriptionInfoList()
Get the SubscriptionInfo(s) of the currently active SIM(s). |
List<SubscriptionInfo>
|
getAllSubscriptionInfoList()
Get all subscription info records from SIMs that are inserted now or previously inserted. |
List<SubscriptionInfo>
|
getCompleteActiveSubscriptionInfoList()
Get both hidden and visible SubscriptionInfo(s) of the currently active SIM(s). |
static
int
|
getDefaultDataSubscriptionId()
Returns the system's default data subscription id. |
static
int
|
getDefaultSmsSubscriptionId()
Returns the system's default SMS subscription id. |
static
int
|
getDefaultSubscriptionId()
Returns the system's default subscription id. |
static
int
|
getDefaultVoiceSubscriptionId()
Returns the system's default voice subscription id. |
List<Uri>
|
getDeviceToDeviceStatusSharingContacts(int subscriptionId)
Get the list of contacts that allow device to device status sharing. |
int
|
getDeviceToDeviceStatusSharingPreference(int subscriptionId)
Returns the user-chosen device to device status sharing preference |
List<SubscriptionInfo>
|
getOpportunisticSubscriptions()
Return opportunistic subscriptions that can be visible to the caller. |
String
|
getPhoneNumber(int subscriptionId, int source)
Returns the phone number for the given |
String
|
getPhoneNumber(int subscriptionId)
Returns the phone number for the given |
static
int
|
getSlotIndex(int subscriptionId)
Get slotIndex associated with the subscription. |
static
int
|
getSubscriptionId(int slotIndex)
Get the subscription id for specified logical SIM slot index. |
int[]
|
getSubscriptionIds(int slotIndex)
This method was deprecated
in API level 34.
Use |
List<SubscriptionPlan>
|
getSubscriptionPlans(int subId)
Get the description of the billing relationship plan between a carrier and a specific subscriber. |
List<SubscriptionInfo>
|
getSubscriptionsInGroup(ParcelUuid groupUuid)
Get subscriptionInfo list of subscriptions that are in the same group of given subId. |
boolean
|
isActiveSubscriptionId(int subscriptionId)
Checks if the supplied subscription ID corresponds to a subscription which is actively in use on the device. |
boolean
|
isNetworkRoaming(int subId)
Returns true if the device is considered roaming on the current network for a subscription. |
static
boolean
|
isUsableSubscriptionId(int subscriptionId)
Check if the supplied subscription ID is usable. |
static
boolean
|
isValidSubscriptionId(int subscriptionId)
Check if the supplied subscription ID is valid. |
void
|
removeOnOpportunisticSubscriptionsChangedListener(SubscriptionManager.OnOpportunisticSubscriptionsChangedListener listener)
Unregister the |
void
|
removeOnSubscriptionsChangedListener(SubscriptionManager.OnSubscriptionsChangedListener listener)
Unregister the |
void
|
removeSubscriptionsFromGroup(List<Integer> subIdList, ParcelUuid groupUuid)
Remove a list of subscriptions from their subscription group. |
void
|
setCarrierPhoneNumber(int subscriptionId, String number)
Sets the phone number for the given |
void
|
setDeviceToDeviceStatusSharingContacts(int subscriptionId, List<Uri> contacts)
Set the list of contacts that allow device to device status sharing for a subscription id. |
void
|
setDeviceToDeviceStatusSharingPreference(int subscriptionId, int sharing)
Set the device to device status sharing user preference for a subscription id. |
boolean
|
setOpportunistic(boolean opportunistic, int subId)
Set whether a subscription is opportunistic, that is, whether the network it connects to has limited coverage. |
void
|
setSubscriptionOverrideCongested(int subId, boolean overrideCongested, int[] networkTypes, long expirationDurationMillis)
Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested. |
void
|
setSubscriptionOverrideCongested(int subId, boolean overrideCongested, long expirationDurationMillis)
Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested. |
void
|
setSubscriptionOverrideUnmetered(int subId, boolean overrideUnmetered, long expirationDurationMillis)
Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered unmetered. |
void
|
setSubscriptionOverrideUnmetered(int subId, boolean overrideUnmetered, int[] networkTypes, long expirationDurationMillis)
Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered unmetered. |
void
|
setSubscriptionPlans(int subId, List<SubscriptionPlan> plans)
This method was deprecated
in API level 33.
use |
void
|
setSubscriptionPlans(int subId, List<SubscriptionPlan> plans, long expirationDurationMillis)
Set the description of the billing relationship plan between a carrier and a specific subscriber. |
void
|
switchToSubscription(int subId, PendingIntent callbackIntent)
This method was deprecated
in API level 34.
this API is a duplicate of |
Inherited methods | |
---|---|
Constants
ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED
public static final String ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED
Broadcast Action: The default sms subscription has changed. This has the following extra values:
EXTRA_SUBSCRIPTION_INDEX
extra indicates the current default sms
subscription index
Constant Value: "android.telephony.action.DEFAULT_SMS_SUBSCRIPTION_CHANGED"
ACTION_DEFAULT_SUBSCRIPTION_CHANGED
public static final String ACTION_DEFAULT_SUBSCRIPTION_CHANGED
Broadcast Action: The default subscription has changed. This has the following extra values:
TheEXTRA_SUBSCRIPTION_INDEX
extra indicates the current default subscription index
Constant Value: "android.telephony.action.DEFAULT_SUBSCRIPTION_CHANGED"
ACTION_MANAGE_SUBSCRIPTION_PLANS
public static final String ACTION_MANAGE_SUBSCRIPTION_PLANS
Activity Action: Display UI for managing the billing relationship plans between a carrier and a specific subscriber.
Carrier apps are encouraged to implement this activity, and the OS will
provide an affordance to quickly enter this activity, typically via
Settings. This affordance will only be shown when the carrier app is
actively providing subscription plan information via
setSubscriptionPlans(int, java.util.List)
.
Contains EXTRA_SUBSCRIPTION_INDEX
to indicate which subscription
the user is interested in.
Constant Value: "android.telephony.action.MANAGE_SUBSCRIPTION_PLANS"
ACTION_REFRESH_SUBSCRIPTION_PLANS
public static final String ACTION_REFRESH_SUBSCRIPTION_PLANS
Broadcast Action: Request a refresh of the billing relationship plans between a carrier and a specific subscriber.
Carrier apps are encouraged to implement this receiver, and the OS will
provide an affordance to request a refresh. This affordance will only be
shown when the carrier app is actively providing subscription plan
information via setSubscriptionPlans(int, java.util.List)
.
Contains EXTRA_SUBSCRIPTION_INDEX
to indicate which subscription
the user is interested in.
Receivers should protect themselves by checking that the sender holds the
android.permission.MANAGE_SUBSCRIPTION_PLANS
permission.
Constant Value: "android.telephony.action.REFRESH_SUBSCRIPTION_PLANS"
D2D_SHARING_ALL
public static final int D2D_SHARING_ALL
Device status is shared whenever possible.
Constant Value: 3 (0x00000003)
D2D_SHARING_ALL_CONTACTS
public static final int D2D_SHARING_ALL_CONTACTS
Device status is shared with all numbers in the user's contacts.
Constant Value: 1 (0x00000001)
D2D_SHARING_DISABLED
public static final int D2D_SHARING_DISABLED
Device status is not shared to a remote party.
Constant Value: 0 (0x00000000)
D2D_SHARING_SELECTED_CONTACTS
public static final int D2D_SHARING_SELECTED_CONTACTS
Device status is shared with all selected contacts.
Constant Value: 2 (0x00000002)
D2D_STATUS_SHARING
public static final String D2D_STATUS_SHARING
TelephonyProvider column name for device to device sharing status.
Type: INTEGER (int)
Constant Value: "d2d_sharing_status"
D2D_STATUS_SHARING_SELECTED_CONTACTS
public static final String D2D_STATUS_SHARING_SELECTED_CONTACTS
TelephonyProvider column name for contacts information that allow device to device sharing.
Type: TEXT (String)
Constant Value: "d2d_sharing_contacts"
DATA_ROAMING_DISABLE
public static final int DATA_ROAMING_DISABLE
Indicates that data roaming is disabled for a subscription
Constant Value: 0 (0x00000000)
DATA_ROAMING_ENABLE
public static final int DATA_ROAMING_ENABLE
Indicates that data roaming is enabled for a subscription
Constant Value: 1 (0x00000001)
DEFAULT_SUBSCRIPTION_ID
public static final int DEFAULT_SUBSCRIPTION_ID
Indicates the default subscription ID in Telephony.
Constant Value: 2147483647 (0x7fffffff)
EXTRA_SLOT_INDEX
public static final String EXTRA_SLOT_INDEX
Integer extra to specify SIM slot index.
Constant Value: "android.telephony.extra.SLOT_INDEX"
EXTRA_SUBSCRIPTION_INDEX
public static final String EXTRA_SUBSCRIPTION_INDEX
Integer extra used with ACTION_DEFAULT_SUBSCRIPTION_CHANGED
and
ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED
to indicate the subscription
which has changed.
Constant Value: "android.telephony.extra.SUBSCRIPTION_INDEX"
INVALID_SIM_SLOT_INDEX
public static final int INVALID_SIM_SLOT_INDEX
Indicates invalid sim slot. This can be returned by getSlotIndex(int)
.
Constant Value: -1 (0xffffffff)
INVALID_SUBSCRIPTION_ID
public static final int INVALID_SUBSCRIPTION_ID
An invalid subscription identifier
Constant Value: -1 (0xffffffff)
PHONE_NUMBER_SOURCE_CARRIER
public static final int PHONE_NUMBER_SOURCE_CARRIER
A source of phone number: provided by an app that has carrier privilege.
The number is intended to be set by a carrier app knowing the correct number
which is, for example, different from the number in UICC
for some reason.
The number is not available until a carrier app sets one via
setCarrierPhoneNumber(int, java.lang.String)
.
The app can update the number with the same API should the number change.
Constant Value: 2 (0x00000002)
PHONE_NUMBER_SOURCE_IMS
public static final int PHONE_NUMBER_SOURCE_IMS
A source of phone number: provided by IMS (IP Multimedia Subsystem) implementation.
When IMS service is registered (as indicated by
RegistrationManager.RegistrationCallback.onRegistered(int)
)
the IMS implementation may return P-Associated-Uri SIP headers (RFC 3455). The URIs
are the user\u2019s public user identities known to the network (see 3GPP TS 24.229 5.4.1.2),
and the phone number is typically one of them (see \u201cglobal number\u201d in 3GPP TS 23.003 13.4).
This source provides the phone number from the last IMS registration. IMS registration may happen on every device reboot or other network condition changes. The number will be updated should the associated URI change after an IMS registration.
Constant Value: 3 (0x00000003)
PHONE_NUMBER_SOURCE_UICC
public static final int PHONE_NUMBER_SOURCE_UICC
A source of phone number: the EF-MSISDN (see 3GPP TS 31.102), or EF-MDN for CDMA (see 3GPP2 C.P0065-B), from UICC application.
The availability and accuracy of the number depends on the carrier. The number may be updated by over-the-air update to UICC applications from the carrier, or by other means with physical access to the SIM.
Constant Value: 1 (0x00000001)
SERVICE_CAPABILITY_DATA
public static final int SERVICE_CAPABILITY_DATA
Represents a value indicating the data calling capabilities of a subscription.
Constant Value: 3 (0x00000003)
SERVICE_CAPABILITY_SMS
public static final int SERVICE_CAPABILITY_SMS
Represents a value indicating the SMS capabilities of a subscription.
This value identifies whether the subscription supports various sms services. These services can include circuit-switched (CS) SMS, packet-switched (PS) IMS (IP Multimedia Subsystem) SMS, and over-the-top (OTT) SMS options.
Note: The availability of emergency SMS services is not solely dependent on this
sms capability. Emergency services may be accessible even if the subscription lacks
standard sms capabilities. However, the device's ability to support emergency sms
can be influenced by its inherent sms capabilities, as determined by
TelephonyManager#isDeviceSmsCapable()
.
See also:
Constant Value: 2 (0x00000002)
SERVICE_CAPABILITY_VOICE
public static final int SERVICE_CAPABILITY_VOICE
Represents a value indicating the voice calling capabilities of a subscription.
This value identifies whether the subscription supports various voice calling services. These services can include circuit-switched (CS) calling, packet-switched (PS) IMS (IP Multimedia Subsystem) calling, and over-the-top (OTT) calling options.
Note: The availability of emergency calling services is not solely dependent on this
voice capability. Emergency services may be accessible even if the subscription lacks
standard voice capabilities. However, the device's ability to support emergency calls
can be influenced by its inherent voice capabilities, as determined by
TelephonyManager#isDeviceVoiceCapable()
.
See also:
Constant Value: 1 (0x00000001)
SUBSCRIPTION_TYPE_LOCAL_SIM
public static final int SUBSCRIPTION_TYPE_LOCAL_SIM
This constant is to designate a subscription as a Local-SIM Subscription.
A Local-SIM can be a physical SIM inserted into a sim-slot in the device, or eSIM on the device.
Constant Value: 0 (0x00000000)
SUBSCRIPTION_TYPE_REMOTE_SIM
public static final int SUBSCRIPTION_TYPE_REMOTE_SIM
This constant is to designate a subscription as a Remote-SIM Subscription.
A Remote-SIM subscription is for a SIM on a phone connected to this device via some connectivity mechanism, for example bluetooth. Similar to Local SIM, this subscription can be used for SMS, Voice and data by proxying data through the connected device. Certain data of the SIM, such as IMEI, are not accessible for Remote SIMs.
A Remote-SIM is available only as long the phone stays connected to this device. When the phone disconnects, Remote-SIM subscription is removed from this device and is no longer known. All data associated with the subscription, such as stored SMS, call logs, contacts etc, are removed from this device.
If the phone re-connects to this device, a new Remote-SIM subscription is created for the phone. The Subscription Id associated with the new subscription is different from the Subscription Id of the previous Remote-SIM subscription created (and removed) for the phone; i.e., new Remote-SIM subscription treats the reconnected phone as a Remote-SIM that was never seen before.
Constant Value: 1 (0x00000001)
USAGE_SETTING_DATA_CENTRIC
public static final int USAGE_SETTING_DATA_CENTRIC
This subscription is forced to data-centric mode
Refer to data-centric mode in 3gpp 24.301 sec 4.3 and 3gpp 24.501 sec 4.3. Also refer to "UE's usage setting" as defined in 3gpp 24.301 section 3.1 and 3gpp 23.221 Annex A.
Devices that support PackageManager#FEATURE_TELEPHONY_DATA
and support usage
setting configuration must support setting this value via.
CarrierConfigManager#KEY_CELLULAR_USAGE_SETTING_INT
.
Constant Value: 2 (0x00000002)
USAGE_SETTING_DEFAULT
public static final int USAGE_SETTING_DEFAULT
Subscription uses the default setting. The value is based upon device capability and the other properties of the subscription. Most subscriptions will default to voice-centric when in a phone. An opportunistic subscription will default to data-centric.
See also:
Constant Value: 0 (0x00000000)
USAGE_SETTING_UNKNOWN
public static final int USAGE_SETTING_UNKNOWN
The usage setting is unknown. This will be the usage setting returned on devices that do not support querying the or setting the usage setting. It may also be provided by a carrier that wishes to provide a value to avoid making any settings changes.
Constant Value: -1 (0xffffffff)
USAGE_SETTING_VOICE_CENTRIC
public static final int USAGE_SETTING_VOICE_CENTRIC
This subscription is forced to voice-centric mode
Refer to voice-centric mode in 3gpp 24.301 sec 4.3 and 3gpp 24.501 sec 4.3. Also refer to "UE's usage setting" as defined in 3gpp 24.301 section 3.1 and 3gpp 23.221 Annex A.
Devices that support PackageManager#FEATURE_TELEPHONY_CALLING
and support usage
setting configuration must support setting this value via
CarrierConfigManager#KEY_CELLULAR_USAGE_SETTING_INT
.
Constant Value: 1 (0x00000001)
Public methods
addOnOpportunisticSubscriptionsChangedListener
public void addOnOpportunisticSubscriptionsChangedListener (Executor executor, SubscriptionManager.OnOpportunisticSubscriptionsChangedListener listener)
Register for changes to the list of opportunistic subscription records or to the individual records themselves. When a change occurs the onOpportunisticSubscriptionsChanged method of the listener will be invoked immediately if there has been a notification.
Parameters | |
---|---|
executor |
Executor : This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
SubscriptionManager.OnOpportunisticSubscriptionsChangedListener : an instance of OnOpportunisticSubscriptionsChangedListener with
onOpportunisticSubscriptionsChanged overridden.
This value cannot be null . |
addOnSubscriptionsChangedListener
public void addOnSubscriptionsChangedListener (SubscriptionManager.OnSubscriptionsChangedListener listener)
This method was deprecated
in API level 31.
Will get exception if the parameter listener is not initialized with a Looper.
Use addOnSubscriptionsChangedListener(java.util.concurrent.Executor, android.telephony.SubscriptionManager.OnSubscriptionsChangedListener)
.
Register for changes to the list of active SubscriptionInfo
records or to the
individual records themselves. When a change occurs the onSubscriptionsChanged method of
the listener will be invoked immediately if there has been a notification. The
onSubscriptionChanged method will also be triggered once initially when calling this
function. The callback will be invoked on the looper specified in the listener's constructor.
Parameters | |
---|---|
listener |
SubscriptionManager.OnSubscriptionsChangedListener : an instance of OnSubscriptionsChangedListener with
onSubscriptionsChanged overridden. |
addOnSubscriptionsChangedListener
public void addOnSubscriptionsChangedListener (Executor executor, SubscriptionManager.OnSubscriptionsChangedListener listener)
Register for changes to the list of SubscriptionInfo
records or to the
individual records (active or inactive) themselves. When a change occurs, the
OnSubscriptionsChangedListener#onSubscriptionsChanged()
method of
the listener will be invoked immediately. The
OnSubscriptionsChangedListener#onSubscriptionsChanged()
method will also be invoked
once initially when calling this method.
Parameters | |
---|---|
executor |
Executor : the executor that will execute callbacks.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
SubscriptionManager.OnSubscriptionsChangedListener : an instance of OnSubscriptionsChangedListener with
OnSubscriptionsChangedListener#onSubscriptionsChanged() overridden.
This value cannot be null . |
addSubscriptionsIntoGroup
public void addSubscriptionsIntoGroup (List<Integer> subIdList, ParcelUuid groupUuid)
Add a list of subscriptions into a group.
See createSubscriptionGroup(java.util.List)
for more details.
Caller will either have Manifest.permission.MODIFY_PHONE_STATE
permission or had carrier privilege permission on the subscriptions:
TelephonyManager#hasCarrierPrivileges()
or
canManageSubscription(android.telephony.SubscriptionInfo)
Requires Manifest.permission.MODIFY_PHONE_STATE
Parameters | |
---|---|
subIdList |
List : list of subId that need adding into the group
This value cannot be null . |
groupUuid |
ParcelUuid : the groupUuid the subscriptions are being added to.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
IllegalArgumentException |
if the some subscriptions in the list doesn't exist. |
IllegalStateException |
if Telephony service is in bad state. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
canManageSubscription
public boolean canManageSubscription (SubscriptionInfo info)
Checks whether the app with the given context is authorized to manage the given subscription
according to its metadata.
Only supported for embedded subscriptions (if SubscriptionInfo#isEmbedded
returns
true). To check for permissions for non-embedded subscription as well,
see TelephonyManager.hasCarrierPrivileges()
.
Parameters | |
---|---|
info |
SubscriptionInfo : The subscription to check. |
Returns | |
---|---|
boolean |
whether the app is authorized to manage this subscription per its metadata. |
See also:
createSubscriptionGroup
public ParcelUuid createSubscriptionGroup (List<Integer> subIdList)
Inform SubscriptionManager that subscriptions in the list are bundled
as a group. It can be multiple primary (non-opportunistic) subscriptions,
or one or more primary plus one or more opportunistic subscriptions.
This API will always create a new immutable group and assign group UUID to all the
subscriptions, regardless whether they are in a group already or not.
Grouped subscriptions will have below behaviors:
1) They will share the same user settings.
2) The opportunistic subscriptions in the group is considered invisible and will not
return from getActiveSubscriptionInfoList()
, unless caller has carrier
privilege permission of the subscriptions.
3) The opportunistic subscriptions in the group can't be active by itself. If all other
non-opportunistic ones are deactivated (unplugged or disabled in Settings),
the opportunistic ones will be deactivated automatically.
Caller will either have Manifest.permission.MODIFY_PHONE_STATE
permission or had carrier privilege permission on the subscriptions:
TelephonyManager#hasCarrierPrivileges()
or
canManageSubscription(android.telephony.SubscriptionInfo)
Requires Manifest.permission.MODIFY_PHONE_STATE
Parameters | |
---|---|
subIdList |
List : list of subId that will be in the same group
This value cannot be null . |
Returns | |
---|---|
ParcelUuid |
groupUUID a UUID assigned to the subscription group.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
IllegalArgumentException |
if any of the subscriptions in the list doesn't exist. |
IllegalStateException |
if Telephony service is in bad state. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
from
public static SubscriptionManager from (Context context)
This method was deprecated
in API level 28.
developers should always obtain references directly from
Context#getSystemService(Class)
.
Parameters | |
---|---|
context |
Context |
Returns | |
---|---|
SubscriptionManager |
getAccessibleSubscriptionInfoList
public List<SubscriptionInfo> getAccessibleSubscriptionInfoList ()
Gets the SubscriptionInfo(s) of all embedded subscriptions accessible to the calling app, if any.
Only those subscriptions for which the calling app has carrier privileges per the subscription metadata, if any, will be included in the returned list.
The records will be sorted by SubscriptionInfo#getSimSlotIndex
then by
SubscriptionInfo#getSubscriptionId
.
Returns | |
---|---|
List<SubscriptionInfo> |
Sorted list of the current embedded SubscriptionInfo records available on the
device which are accessible to the caller.
|
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_EUICC . |
getActiveDataSubscriptionId
public static int getActiveDataSubscriptionId ()
Get active data subscription id. Active data subscription refers to the subscription
currently chosen to provide cellular internet connection to the user. This may be
different from getDefaultDataSubscriptionId()
.
Returns | |
---|---|
int |
Active data subscription id if any is chosen, or INVALID_SUBSCRIPTION_ID if
not. |
getActiveSubscriptionInfo
public SubscriptionInfo getActiveSubscriptionInfo (int subId)
Get the active SubscriptionInfo with the input subId.
Requires Permission: READ_PHONE_STATE
or that the calling app has carrier privileges (see
TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.READ_PHONE_STATE
Parameters | |
---|---|
subId |
int : The unique SubscriptionInfo key in database. |
Returns | |
---|---|
SubscriptionInfo |
SubscriptionInfo, maybe null if its not active. |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getActiveSubscriptionInfoCount
public int getActiveSubscriptionInfoCount ()
Get the active subscription count.
Requires Manifest.permission.READ_PHONE_STATE
Returns | |
---|---|
int |
The current number of active subscriptions. |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
See also:
getActiveSubscriptionInfoCountMax
public int getActiveSubscriptionInfoCountMax ()
Returns | |
---|---|
int |
the maximum number of active subscriptions that will be returned by
getActiveSubscriptionInfoList() and the value returned by
getActiveSubscriptionInfoCount() . |
getActiveSubscriptionInfoForSimSlotIndex
public SubscriptionInfo getActiveSubscriptionInfoForSimSlotIndex (int slotIndex)
Get the active SubscriptionInfo associated with the slotIndex
Requires Permission: READ_PHONE_STATE
or that the calling app has carrier privileges (see
TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.READ_PHONE_STATE
Parameters | |
---|---|
slotIndex |
int : the slot which the subscription is inserted |
Returns | |
---|---|
SubscriptionInfo |
SubscriptionInfo, maybe null if its not active |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getActiveSubscriptionInfoList
public List<SubscriptionInfo> getActiveSubscriptionInfoList ()
Get the SubscriptionInfo(s) of the currently active SIM(s).
Returned records will be sorted by SubscriptionInfo#getSimSlotIndex
then by
SubscriptionInfo#getSubscriptionId
. Beginning with Android SDK 35, this method will
never return null.
Requires Permission: READ_PHONE_STATE
or that the calling app has carrier privileges (see
TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.READ_PHONE_STATE
Returns | |
---|---|
List<SubscriptionInfo> |
a list of the active SubscriptionInfo that is visible to the caller. If
an empty list or null is returned, then there are no active subscriptions that
are visible to the caller. If the number of active subscriptions available to
any caller changes, then this change will be indicated by
OnSubscriptionsChangedListener#onSubscriptionsChanged . |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getAllSubscriptionInfoList
public List<SubscriptionInfo> getAllSubscriptionInfoList ()
Get all subscription info records from SIMs that are inserted now or previously inserted.
If the caller does not have Manifest.permission#READ_PHONE_NUMBERS
permission,
SubscriptionInfo#getNumber()
will return empty string.
If the caller does not have Manifest.permission#USE_ICC_AUTH_WITH_DEVICE_IDENTIFIER
,
SubscriptionInfo#getIccId()
will return an empty string, and
SubscriptionInfo#getGroupUuid()
will return null
.
The carrier app will only get the list of subscriptions that it has carrier privilege on,
but will have non-stripped SubscriptionInfo
in the list.
Requires Manifest.permission.READ_PHONE_STATE
or carrier privileges
Returns | |
---|---|
List<SubscriptionInfo> |
List of all SubscriptionInfo records from SIMs that are inserted or
previously inserted. Sorted by SubscriptionInfo#getSimSlotIndex() , then
SubscriptionInfo#getSubscriptionId() . |
Throws | |
---|---|
SecurityException |
if callers do not hold the required permission. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getCompleteActiveSubscriptionInfoList
public List<SubscriptionInfo> getCompleteActiveSubscriptionInfoList ()
Get both hidden and visible SubscriptionInfo(s) of the currently active SIM(s).
The records will be sorted by SubscriptionInfo#getSimSlotIndex
then by SubscriptionInfo#getSubscriptionId
.
Hidden subscriptions refer to those are not meant visible to the users.
For example, an opportunistic subscription that is grouped with other
subscriptions should remain invisible to users as they are only functionally
supplementary to primary ones.
Requires Permission: READ_PHONE_STATE
or that the calling app has carrier privileges (see
TelephonyManager#hasCarrierPrivileges
). In the latter case, only records accessible
to the calling app are returned.
Returns | |
---|---|
List<SubscriptionInfo> |
Sorted list of the currently available SubscriptionInfo
records on the device.
This is similar to getActiveSubscriptionInfoList() except that it will return
both active and hidden SubscriptionInfos.
This value cannot be null . |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getDefaultDataSubscriptionId
public static int getDefaultDataSubscriptionId ()
Returns the system's default data subscription id. On a voice only device or on error, will return INVALID_SUBSCRIPTION_ID.
Returns | |
---|---|
int |
the default data subscription Id. |
getDefaultSmsSubscriptionId
public static int getDefaultSmsSubscriptionId ()
Returns the system's default SMS subscription id. On a data only device or on error, will return INVALID_SUBSCRIPTION_ID.
Returns | |
---|---|
int |
the default SMS subscription Id. |
getDefaultSubscriptionId
public static int getDefaultSubscriptionId ()
Returns the system's default subscription id. For a voice capable device, it will return getDefaultVoiceSubscriptionId. For a data only device, it will return the getDefaultDataSubscriptionId. May return an INVALID_SUBSCRIPTION_ID on error.
Returns | |
---|---|
int |
the "system" default subscription id. |
getDefaultVoiceSubscriptionId
public static int getDefaultVoiceSubscriptionId ()
Returns the system's default voice subscription id. On a data only device or on error, will return INVALID_SUBSCRIPTION_ID.
Returns | |
---|---|
int |
the default voice subscription Id. |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getDeviceToDeviceStatusSharingContacts
public List<Uri> getDeviceToDeviceStatusSharingContacts (int subscriptionId)
Get the list of contacts that allow device to device status sharing.
Parameters | |
---|---|
subscriptionId |
int : Subscription id. |
Returns | |
---|---|
List<Uri> |
The list of contacts that allow device to device status sharing.
This value cannot be null . |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getDeviceToDeviceStatusSharingPreference
public int getDeviceToDeviceStatusSharingPreference (int subscriptionId)
Returns the user-chosen device to device status sharing preference
Parameters | |
---|---|
subscriptionId |
int : Subscription id of subscription |
Returns | |
---|---|
int |
The device to device status sharing preference
Value is D2D_SHARING_DISABLED , D2D_SHARING_ALL_CONTACTS , D2D_SHARING_SELECTED_CONTACTS , or D2D_SHARING_ALL |
Throws | |
---|---|
SecurityException |
if the caller doesn't have permissions required. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getOpportunisticSubscriptions
public List<SubscriptionInfo> getOpportunisticSubscriptions ()
Return opportunistic subscriptions that can be visible to the caller. Opportunistic subscriptions are for opportunistic networks, which are cellular networks with limited capabilities and coverage, for example, CBRS.
Requires Permission:
READ_PHONE_STATE
or that the calling app has carrier privileges (see
TelephonyManager#hasCarrierPrivileges
).
Requires Manifest.permission.READ_PHONE_STATE
Returns | |
---|---|
List<SubscriptionInfo> |
the list of opportunistic subscription info. If none exists, an empty list.
This value cannot be null . |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getPhoneNumber
public String getPhoneNumber (int subscriptionId, int source)
Returns the phone number for the given subscriptionId
and source
,
or an empty string if not available.
General apps that need to know the phone number should use getPhoneNumber(int)
instead. This API may be suitable specific apps that needs to know the phone number from
a specific source. For example, a carrier app needs to know exactly what's on
UICC
and decide if the previously set phone number
of source carrier
should be updated.
The API provides no guarantees of what format the number is in: the format can vary
depending on the source
and the network etc. Programmatic parsing should be done
cautiously, for example, after formatting the number to a consistent format with
PhoneNumberUtils.formatNumberToE164(String, String)
.
Note the assumption is that one subscription (which usually means one SIM) has
only one phone number. The multiple sources backup each other so hopefully at least one
is available. For example, for a carrier that doesn't typically set phone numbers
on UICC
, the source IMS
may provide one. Or, a carrier may decide to provide the phone number via source
carrier
if neither source UICC nor IMS is available.
The availability and correctness of the phone number depends on the underlying source
and the network etc. Additional verification is needed to use this number for
security-related or other sensitive scenarios.
Requires Manifest.permission.READ_PHONE_NUMBERS
or android.Manifest.permission.READ_PRIVILEGED_PHONE_STATE or carrier privileges
Parameters | |
---|---|
subscriptionId |
int : the subscription ID, or DEFAULT_SUBSCRIPTION_ID
for the default one. |
source |
int : the source of the phone number, one of the PHONE_NUMBER_SOURCE_* constants.
Value is PHONE_NUMBER_SOURCE_UICC , PHONE_NUMBER_SOURCE_CARRIER , or PHONE_NUMBER_SOURCE_IMS |
Returns | |
---|---|
String |
the phone number, or an empty string if not available.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if source is invalid. |
IllegalStateException |
if the telephony process is not currently available. |
SecurityException |
if the caller doesn't have permissions required. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
getPhoneNumber
public String getPhoneNumber (int subscriptionId)
Returns the phone number for the given subId
, or an empty string if
not available.
This API is suitable for general apps that needs to know the phone number.
For specific apps that needs to know the phone number provided by a specific source,
getPhoneNumber(int, int)
may be suitable.
This API is built up on getPhoneNumber(int, int)
, but picks
from available sources in the following order: PHONE_NUMBER_SOURCE_CARRIER
> PHONE_NUMBER_SOURCE_UICC
> PHONE_NUMBER_SOURCE_IMS
.
The API provides no guarantees of what format the number is in: the format can vary
depending on the underlying source and the network etc. Programmatic parsing should be done
cautiously, for example, after formatting the number to a consistent format with
PhoneNumberUtils.formatNumberToE164(String, String)
.
The availability and correctness of the phone number depends on the underlying source
and the network etc. Additional verification is needed to use this number for
security-related or other sensitive scenarios.
Requires Manifest.permission.READ_PHONE_NUMBERS
or android.Manifest.permission.READ_PRIVILEGED_PHONE_STATE or carrier privileges
Parameters | |
---|---|
subscriptionId |
int : the subscription ID, or DEFAULT_SUBSCRIPTION_ID
for the default one. |
Returns | |
---|---|
String |
the phone number, or an empty string if not available.
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if the telephony process is not currently available. |
SecurityException |
if the caller doesn't have permissions required. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
See also:
getSlotIndex
public static int getSlotIndex (int subscriptionId)
Get slotIndex associated with the subscription.
Parameters | |
---|---|
subscriptionId |
int : the unique SubscriptionInfo index in database |
Returns | |
---|---|
int |
slotIndex as a positive integer or INVALID_SIM_SLOT_INDEX if the supplied
subscriptionId doesn't have an associated slot index. |
getSubscriptionId
public static int getSubscriptionId (int slotIndex)
Get the subscription id for specified logical SIM slot index.
Parameters | |
---|---|
slotIndex |
int : The logical SIM slot index. |
Returns | |
---|---|
int |
The subscription id. INVALID_SUBSCRIPTION_ID if SIM is absent. |
getSubscriptionIds
public int[] getSubscriptionIds (int slotIndex)
This method was deprecated
in API level 34.
Use getSubscriptionId(int)
instead.
Get an array of subscription ids for the specified logical SIM slot Index. The maximum size of the array is 1. This API was mistakenly designed to return multiple subscription ids, which is not possible in the current Android telephony architecture.
Parameters | |
---|---|
slotIndex |
int : The logical SIM slot index. |
Returns | |
---|---|
int[] |
Subscription id of the active subscription on the specified logical SIM slot index.
If SIM is absent on the slot, a single element array of INVALID_SUBSCRIPTION_ID will
be returned. null if the provided slotIndex is not valid. |
getSubscriptionPlans
public List<SubscriptionPlan> getSubscriptionPlans (int subId)
Get the description of the billing relationship plan between a carrier and a specific subscriber.
This method is only accessible to the following narrow set of apps:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges()
. - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING
.
Parameters | |
---|---|
subId |
int : the subscriber this relationship applies to |
Returns | |
---|---|
List<SubscriptionPlan> |
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
getSubscriptionsInGroup
public List<SubscriptionInfo> getSubscriptionsInGroup (ParcelUuid groupUuid)
Get subscriptionInfo list of subscriptions that are in the same group of given subId.
Caller must have Manifest.permission.READ_PHONE_STATE
or carrier privilege permission on the subscription.
TelephonyManager#hasCarrierPrivileges()
Starting with API level 33, the caller also needs permission to access device identifiers to get the list of subscriptions associated with a group UUID. This method can be invoked if one of the following requirements is met:
- If the app has carrier privilege permission.
TelephonyManager#hasCarrierPrivileges()
- If the app has
Manifest.permission.READ_PHONE_STATE
permission and access to device identifiers.
Requires
Manifest.permission.READ_PHONE_STATE
Parameters | |
---|---|
groupUuid |
ParcelUuid : of which list of subInfo will be returned.
This value cannot be null . |
Returns | |
---|---|
List<SubscriptionInfo> |
list of subscriptionInfo that belong to the same group, including the given
subscription itself. It will return an empty list if no subscription belongs to the group.
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if Telephony service is in bad state. |
SecurityException |
if the caller doesn't meet the requirements outlined above. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
isActiveSubscriptionId
public boolean isActiveSubscriptionId (int subscriptionId)
Checks if the supplied subscription ID corresponds to a subscription which is actively in
use on the device. An active subscription ID is a valid and usable subscription ID.
Requires Manifest.permission.READ_PHONE_STATE
Parameters | |
---|---|
subscriptionId |
int : the subscription ID. |
Returns | |
---|---|
boolean |
true if the supplied subscription ID corresponds to an active subscription;
false if it does not correspond to an active subscription; or throw a
SecurityException if the caller hasn't got the right permission.
i |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
isNetworkRoaming
public boolean isNetworkRoaming (int subId)
Returns true if the device is considered roaming on the current network for a subscription.
Availability: Only when user registered to a network.
Parameters | |
---|---|
subId |
int : The subscription ID |
Returns | |
---|---|
boolean |
true if the network for the subscription is roaming, false otherwise |
isUsableSubscriptionId
public static boolean isUsableSubscriptionId (int subscriptionId)
Check if the supplied subscription ID is usable.
A usable subscription ID is a valid subscription ID, but not necessarily an active
subscription ID (see isActiveSubscriptionId(int)
). Some subscription APIs
require a usable subscription ID, and this is noted in their documentation; otherwise, a
subscription ID does not need to be usable for subscription functions, only valid.
Parameters | |
---|---|
subscriptionId |
int : the subscription ID |
Returns | |
---|---|
boolean |
true if the subscription ID is usable; false otherwise. |
isValidSubscriptionId
public static boolean isValidSubscriptionId (int subscriptionId)
Check if the supplied subscription ID is valid.
A valid subscription ID is not necessarily an active subscription ID
(see isActiveSubscriptionId(int)
) or an usable subscription ID
(see isUsableSubscriptionId(int)
). Unless specifically noted, subscription
APIs work with a valid subscription ID.
Parameters | |
---|---|
subscriptionId |
int : The subscription ID. |
Returns | |
---|---|
boolean |
true if the supplied subscriptionId is valid; false otherwise. |
removeOnOpportunisticSubscriptionsChangedListener
public void removeOnOpportunisticSubscriptionsChangedListener (SubscriptionManager.OnOpportunisticSubscriptionsChangedListener listener)
Unregister the OnOpportunisticSubscriptionsChangedListener
that is currently
listening opportunistic subscriptions change. This is not strictly necessary
as the listener will automatically be unregistered if an attempt to invoke the listener
fails.
Parameters | |
---|---|
listener |
SubscriptionManager.OnOpportunisticSubscriptionsChangedListener : that is to be unregistered.
This value cannot be null . |
removeOnSubscriptionsChangedListener
public void removeOnSubscriptionsChangedListener (SubscriptionManager.OnSubscriptionsChangedListener listener)
Unregister the OnSubscriptionsChangedListener
. This is not strictly necessary
as the listener will automatically be unregistered if an attempt to invoke the listener
fails.
Parameters | |
---|---|
listener |
SubscriptionManager.OnSubscriptionsChangedListener : that is to be unregistered. |
removeSubscriptionsFromGroup
public void removeSubscriptionsFromGroup (List<Integer> subIdList, ParcelUuid groupUuid)
Remove a list of subscriptions from their subscription group.
Caller will either have Manifest.permission.MODIFY_PHONE_STATE
permission or has carrier privilege permission on all of the subscriptions provided in
subIdList
.
Requires Manifest.permission.MODIFY_PHONE_STATE
Parameters | |
---|---|
subIdList |
List : list of subId that need removing from their groups.
This value cannot be null . |
groupUuid |
ParcelUuid : The UUID of the subscription group.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
IllegalArgumentException |
if the some subscriptions in the list doesn't belong the specified group. |
IllegalStateException |
if Telephony service is in bad state. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
See also:
setCarrierPhoneNumber
public void setCarrierPhoneNumber (int subscriptionId, String number)
Sets the phone number for the given subId
for source
carrier
.
Sets an empty string to remove the previously set phone number.
The API is suitable for carrier apps to provide a phone number, for example when
it's not possible to update UICC
directly.
It's recommended that the phone number is formatted to well-known formats,
for example, by PhoneNumberUtils
formatNumber*
methods.
Requires carrier privileges
Parameters | |
---|---|
subscriptionId |
int : the subscription ID, or DEFAULT_SUBSCRIPTION_ID
for the default one. |
number |
String : the phone number, or an empty string to remove the previously set number.
This value cannot be null . |
Throws | |
---|---|
IllegalStateException |
if the telephony process is not currently available. |
NullPointerException |
if number is null . |
SecurityException |
if the caller doesn't have permissions required. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
setDeviceToDeviceStatusSharingContacts
public void setDeviceToDeviceStatusSharingContacts (int subscriptionId, List<Uri> contacts)
Set the list of contacts that allow device to device status sharing for a subscription id.
The setting app uses this method to indicate with whom they wish to share device to device
status information.
Requires Manifest.permission.MODIFY_PHONE_STATE
Parameters | |
---|---|
subscriptionId |
int : The subscription id. |
contacts |
List : The list of contacts that allow device to device status sharing.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if the caller doesn't have permissions required. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
setDeviceToDeviceStatusSharingPreference
public void setDeviceToDeviceStatusSharingPreference (int subscriptionId, int sharing)
Set the device to device status sharing user preference for a subscription id. The setting
app uses this method to indicate with whom they wish to share device to device status
information.
Requires Manifest.permission.MODIFY_PHONE_STATE
Parameters | |
---|---|
subscriptionId |
int : The subscription id. |
sharing |
int : The status sharing preference.
Value is D2D_SHARING_DISABLED , D2D_SHARING_ALL_CONTACTS , D2D_SHARING_SELECTED_CONTACTS , or D2D_SHARING_ALL |
Throws | |
---|---|
SecurityException |
if the caller doesn't have permissions required. |
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
setOpportunistic
public boolean setOpportunistic (boolean opportunistic, int subId)
Set whether a subscription is opportunistic, that is, whether the network it connects
to has limited coverage. For example, CBRS. Setting a subscription opportunistic has
following impacts:
1) Even if it's active, it will be dormant most of the time. The modem will not try
to scan or camp until it knows an available network is nearby to save power.
2) Telephony relies on system app or carrier input to notify nearby available networks.
See TelephonyManager#updateAvailableNetworks(List, Executor, Consumer)
for more information.
3) In multi-SIM devices, when the network is nearby and camped, system may automatically
switch internet data between it and default data subscription, based on carrier
recommendation and its signal strength and metered-ness, etc.
Caller will either have Manifest.permission.MODIFY_PHONE_STATE
or carrier
privilege permission of the subscription.
Requires Manifest.permission.MODIFY_PHONE_STATE
Parameters | |
---|---|
opportunistic |
boolean : whether it\u2019s opportunistic subscription. |
subId |
int : the unique SubscriptionInfo index in database |
Returns | |
---|---|
boolean |
true if the operation is succeed, false otherwise. |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_SUBSCRIPTION . |
setSubscriptionOverrideCongested
public void setSubscriptionOverrideCongested (int subId, boolean overrideCongested, int[] networkTypes, long expirationDurationMillis)
Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested. This will cause the device to delay certain network requests when possible, such as developer jobs that are willing to run in a flexible time window.
This method is only accessible to the following narrow set of apps:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges()
. - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING
.
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
setSubscriptionOverrideCongested
public void setSubscriptionOverrideCongested (int subId, boolean overrideCongested, long expirationDurationMillis)
Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested. This will cause the device to delay certain network requests when possible, such as developer jobs that are willing to run in a flexible time window.
This method is only accessible to the following narrow set of apps:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges()
. - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING
.
Parameters | |
---|---|
subId |
int : the subscriber this override applies to. |
overrideCongested |
boolean : set if the subscription should be considered
congested. |
expirationDurationMillis |
long : the duration after which the requested override
will be automatically cleared, or 0 to leave in the
requested state until explicitly cleared, or the next reboot,
whichever happens first.
Value is a non-negative duration in milliseconds. |
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
setSubscriptionOverrideUnmetered
public void setSubscriptionOverrideUnmetered (int subId, boolean overrideUnmetered, long expirationDurationMillis)
Temporarily override the billing relationship plan between a carrier and
a specific subscriber to be considered unmetered. This will be reflected
to apps via NetworkCapabilities#NET_CAPABILITY_NOT_METERED
.
This method is only accessible to the following narrow set of apps:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges()
. - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING
.
Parameters | |
---|---|
subId |
int : the subscriber this override applies to. |
overrideUnmetered |
boolean : set if the billing relationship should be
considered unmetered. |
expirationDurationMillis |
long : the duration after which the requested override
will be automatically cleared, or 0 to leave in the
requested state until explicitly cleared, or the next reboot,
whichever happens first.
Value is a non-negative duration in milliseconds. |
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
setSubscriptionOverrideUnmetered
public void setSubscriptionOverrideUnmetered (int subId, boolean overrideUnmetered, int[] networkTypes, long expirationDurationMillis)
Temporarily override the billing relationship plan between a carrier and
a specific subscriber to be considered unmetered. This will be reflected
to apps via NetworkCapabilities#NET_CAPABILITY_NOT_METERED
.
This method is only accessible to the following narrow set of apps:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges()
. - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING
.
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
setSubscriptionPlans
public void setSubscriptionPlans (int subId, List<SubscriptionPlan> plans)
This method was deprecated
in API level 33.
use setSubscriptionPlans(int, java.util.List, long)
instead.
Set the description of the billing relationship plan between a carrier and a specific subscriber.
This method is only accessible to the following narrow set of apps:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges()
. - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING
.
Parameters | |
---|---|
subId |
int : the subscriber this relationship applies to. An empty list
may be sent to clear any existing plans. |
plans |
List : the list of plans. The first plan is always the primary and
most important plan. Any additional plans are secondary and
may not be displayed or used by decision making logic.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
IllegalArgumentException |
if plans don't meet the requirements
defined in SubscriptionPlan . |
setSubscriptionPlans
public void setSubscriptionPlans (int subId, List<SubscriptionPlan> plans, long expirationDurationMillis)
Set the description of the billing relationship plan between a carrier and a specific subscriber.
This method is only accessible to the following narrow set of apps:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges()
. - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING
.
Parameters | |
---|---|
subId |
int : the subscriber this relationship applies to. An empty list
may be sent to clear any existing plans. |
plans |
List : the list of plans. The first plan is always the primary and
most important plan. Any additional plans are secondary and
may not be displayed or used by decision making logic.
This value cannot be null . |
expirationDurationMillis |
long : the duration after which the subscription plans
will be automatically cleared, or 0 to leave the plans until
explicitly cleared, or the next reboot, whichever happens first.
Value is a non-negative duration in milliseconds. |
Throws | |
---|---|
SecurityException |
if the caller doesn't meet the requirements outlined above. |
IllegalArgumentException |
if plans don't meet the requirements
defined in SubscriptionPlan . |
switchToSubscription
public void switchToSubscription (int subId, PendingIntent callbackIntent)
This method was deprecated
in API level 34.
this API is a duplicate of EuiccManager#switchToSubscription(int,
PendingIntent)
and does not support Multiple Enabled Profile(MEP). Apps should use
EuiccManager#switchToSubscription(int, PendingIntent)
or
EuiccManager#switchToSubscription(int, int, PendingIntent)
instead.
Switch to a certain subscription
Requires android.Manifest.permission.WRITE_EMBEDDED_SUBSCRIPTIONS
Requires the PackageManager#FEATURE_TELEPHONY_EUICC
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Parameters | |
---|---|
subId |
int : sub id |
callbackIntent |
PendingIntent : pending intent that will be sent after operation is done.
This value cannot be null . |
Throws | |
---|---|
UnsupportedOperationException |
If the device does not have
PackageManager#FEATURE_TELEPHONY_EUICC . |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-06-18 UTC.