# Print output for @column tags ?> SubscriptionManager - Android SDK | Android Developers

Most visited

Recently visited

SubscriptionManager

public class SubscriptionManager
extends Object

java.lang.Object
   ↳ android.telephony.SubscriptionManager


SubscriptionManager is the application interface to SubscriptionController and provides information about the current Telephony Subscriptions.

Summary

Nested classes

class SubscriptionManager.OnOpportunisticSubscriptionsChangedListener

A listener class for monitoring changes to SubscriptionInfo records of opportunistic subscriptions. 

class SubscriptionManager.OnSubscriptionsChangedListener

A listener class for monitoring changes to SubscriptionInfo records. 

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 ACTION_DEFAULT_SUBSCRIPTION_CHANGED and ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED to indicate the subscription which has changed.

int INVALID_SIM_SLOT_INDEX

Indicates invalid sim slot.

int INVALID_SUBSCRIPTION_ID

An invalid subscription identifier

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.

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 is deprecated. Will get exception if the parameter listener is not initialized with a Looper. Use addOnSubscriptionsChangedListener(java.util.concurrent.Executor, android.telephony.SubscriptionManager.OnSubscriptionsChangedListener).

void addOnSubscriptionsChangedListener(Executor executor, SubscriptionManager.OnSubscriptionsChangedListener listener)

Register for changes to the list of active SubscriptionInfo records or to the individual records themselves.

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 is deprecated. developers should always obtain references directly from Context#getSystemService(Class).

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

Requires Permission: READ_PHONE_STATE or that the calling app has carrier privileges (see TelephonyManager#hasCarrierPrivileges).

int getActiveSubscriptionInfoCountMax()
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).

List<SubscriptionInfo> getActiveSubscriptionInfoList()

Get the SubscriptionInfo(s) of the currently active SIM(s).

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)

Returns 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.

static int getSlotIndex(int subscriptionId)

Get slotIndex associated with the subscription.

int[] getSubscriptionIds(int slotIndex)

Get an array of Subscription Ids for specified slot Index.

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 OnOpportunisticSubscriptionsChangedListener that is currently listening opportunistic subscriptions change.

void removeOnSubscriptionsChangedListener(SubscriptionManager.OnSubscriptionsChangedListener listener)

Unregister the OnSubscriptionsChangedListener.

void removeSubscriptionsFromGroup(List<Integer> subIdList, ParcelUuid groupUuid)

Remove a list of subscriptions from their subscription group.

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 timeoutMillis)

Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested.

void setSubscriptionOverrideCongested(int subId, boolean overrideCongested, long timeoutMillis)

Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested.

void setSubscriptionOverrideUnmetered(int subId, boolean overrideUnmetered, long timeoutMillis)

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 timeoutMillis)

Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered unmetered.

void setSubscriptionPlans(int subId, List<SubscriptionPlan> plans)

Set the description of the billing relationship plan between a carrier and a specific subscriber.

void switchToSubscription(int subId, PendingIntent callbackIntent)

Switch to a certain subscription
Requires android.Manifest.permission.WRITE_EMBEDDED_SUBSCRIPTIONS

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:

The EXTRA_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)

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)

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(). To dispatch events through a shared thread pool, you can use AsyncTask#THREAD_POOL_EXECUTOR.

listener SubscriptionManager.OnOpportunisticSubscriptionsChangedListener: an instance of OnOpportunisticSubscriptionsChangedListener with onOpportunisticSubscriptionsChanged overridden. This value cannot be null.

addOnSubscriptionsChangedListener

public void addOnSubscriptionsChangedListener (SubscriptionManager.OnSubscriptionsChangedListener listener)

This method is deprecated.
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 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.

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(). To dispatch events through a shared thread pool, you can use AsyncTask#THREAD_POOL_EXECUTOR.

listener SubscriptionManager.OnSubscriptionsChangedListener: an instance of OnSubscriptionsChangedListener with 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.

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, .

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.

from

public static SubscriptionManager from (Context context)

This method is deprecated.
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.

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(). Eg. Opportunistics data See PhoneStateListener#onActiveDataSubscriptionIdChanged(int) for the details.

Returns
int Active data subscription id if any is chosen, or SubscriptionManager.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.

getActiveSubscriptionInfoCount

public int getActiveSubscriptionInfoCount ()

Requires Permission: READ_PHONE_STATE or that the calling app has carrier privileges (see TelephonyManager#hasCarrierPrivileges). In the latter case, the count will include only those subscriptions accessible to the caller.
Requires Manifest.permission.READ_PHONE_STATE

Returns
int the current number of active subscriptions. There is no guarantee the value returned by this method will be the same as the length of the list returned by getActiveSubscriptionInfoList().

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

getActiveSubscriptionInfoList

public List<SubscriptionInfo> getActiveSubscriptionInfoList ()

Get the SubscriptionInfo(s) of the currently active SIM(s). The records will be sorted by SubscriptionInfo#getSimSlotIndex then by SubscriptionInfo#getSubscriptionId.

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.
Requires Manifest.permission.READ_PHONE_STATE

Returns
List<SubscriptionInfo> Sorted list of the currently SubscriptionInfo records available on the device.

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.

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.

getDeviceToDeviceStatusSharingContacts

public List<Uri> getDeviceToDeviceStatusSharingContacts (int subscriptionId)

Returns the list of contacts that allow device to device status sharing.

Parameters
subscriptionId int: Subscription id of subscription

Returns
List<Uri> The list of contacts that allow device to device status sharing This value cannot be null.

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

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.

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.

getSubscriptionIds

public int[] getSubscriptionIds (int slotIndex)

Get an array of Subscription Ids for specified slot Index.

Parameters
slotIndex int: the slot index.

Returns
int[] subscription Ids or null if the given slot Index is not valid or there are no active subscriptions in the slot.

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:

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. See createSubscriptionGroup(java.util.List) for more details. Caller will either have Manifest.permission.READ_PHONE_STATE permission or had carrier privilege permission on the subscription. TelephonyManager#hasCarrierPrivileges()
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.

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.

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. 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 removing from their groups. This value cannot be null.

groupUuid ParcelUuid: 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.

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 unique Subscription ID in database

contacts List: The list of contacts that allow device to device status sharing This value cannot be null.

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 unique Subscription ID in database

sharing int: the status sharing preference Value is D2D_SHARING_DISABLED, D2D_SHARING_ALL_CONTACTS, D2D_SHARING_SELECTED_CONTACTS, or D2D_SHARING_ALL

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’s opportunistic subscription.

subId int: the unique SubscriptionInfo index in database

Returns
boolean true if the operation is succeed, false otherwise.

setSubscriptionOverrideCongested

public void setSubscriptionOverrideCongested (int subId, 
                boolean overrideCongested, 
                int[] networkTypes, 
                long timeoutMillis)

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:

Parameters
subId int: the subscriber this override applies to.

overrideCongested boolean: set if the subscription should be considered congested.

networkTypes int: the network types this override applies to. If no network types are specified, override values will be ignored. This value cannot be null. Value is TelephonyManager.NETWORK_TYPE_UNKNOWN, TelephonyManager.NETWORK_TYPE_GPRS, TelephonyManager.NETWORK_TYPE_EDGE, TelephonyManager.NETWORK_TYPE_UMTS, TelephonyManager.NETWORK_TYPE_CDMA, TelephonyManager.NETWORK_TYPE_EVDO_0, TelephonyManager.NETWORK_TYPE_EVDO_A, TelephonyManager.NETWORK_TYPE_1xRTT, TelephonyManager.NETWORK_TYPE_HSDPA, TelephonyManager.NETWORK_TYPE_HSUPA, TelephonyManager.NETWORK_TYPE_HSPA, TelephonyManager.NETWORK_TYPE_IDEN, TelephonyManager.NETWORK_TYPE_EVDO_B, TelephonyManager.NETWORK_TYPE_LTE, TelephonyManager.NETWORK_TYPE_EHRPD, TelephonyManager.NETWORK_TYPE_HSPAP, TelephonyManager.NETWORK_TYPE_GSM, TelephonyManager.NETWORK_TYPE_TD_SCDMA, TelephonyManager.NETWORK_TYPE_IWLAN, or TelephonyManager.NETWORK_TYPE_NR

timeoutMillis long: the timeout 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.

setSubscriptionOverrideCongested

public void setSubscriptionOverrideCongested (int subId, 
                boolean overrideCongested, 
                long timeoutMillis)

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:

Parameters
subId int: the subscriber this override applies to.

overrideCongested boolean: set if the subscription should be considered congested.

timeoutMillis long: the timeout 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 timeoutMillis)

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:

Parameters
subId int: the subscriber this override applies to.

overrideUnmetered boolean: set if the billing relationship should be considered unmetered.

timeoutMillis long: the timeout 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 timeoutMillis)

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:

Parameters
subId int: the subscriber this override applies to.

overrideUnmetered boolean: set if the billing relationship should be considered unmetered.

networkTypes int: the network types this override applies to. If no network types are specified, override values will be ignored. This value cannot be null. Value is TelephonyManager.NETWORK_TYPE_UNKNOWN, TelephonyManager.NETWORK_TYPE_GPRS, TelephonyManager.NETWORK_TYPE_EDGE, TelephonyManager.NETWORK_TYPE_UMTS, TelephonyManager.NETWORK_TYPE_CDMA, TelephonyManager.NETWORK_TYPE_EVDO_0, TelephonyManager.NETWORK_TYPE_EVDO_A, TelephonyManager.NETWORK_TYPE_1xRTT, TelephonyManager.NETWORK_TYPE_HSDPA, TelephonyManager.NETWORK_TYPE_HSUPA, TelephonyManager.NETWORK_TYPE_HSPA, TelephonyManager.NETWORK_TYPE_IDEN, TelephonyManager.NETWORK_TYPE_EVDO_B, TelephonyManager.NETWORK_TYPE_LTE, TelephonyManager.NETWORK_TYPE_EHRPD, TelephonyManager.NETWORK_TYPE_HSPAP, TelephonyManager.NETWORK_TYPE_GSM, TelephonyManager.NETWORK_TYPE_TD_SCDMA, TelephonyManager.NETWORK_TYPE_IWLAN, or TelephonyManager.NETWORK_TYPE_NR

timeoutMillis long: the timeout 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.

setSubscriptionPlans

public void setSubscriptionPlans (int subId, 
                List<SubscriptionPlan> plans)

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:

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.

switchToSubscription

public void switchToSubscription (int subId, 
                PendingIntent callbackIntent)

Switch to a certain subscription
Requires android.Manifest.permission.WRITE_EMBEDDED_SUBSCRIPTIONS

Parameters
subId int: sub id

callbackIntent PendingIntent: pending intent that will be sent after operation is done. This value cannot be null.