Added in API level 22

SubscriptionManager

open class SubscriptionManager
kotlin.Any
   ↳ 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
open

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

A listener class for monitoring changes to SubscriptionInfo records.
Constants
static String

Broadcast Action: The default sms subscription has changed.
static String

Broadcast Action: The default subscription has changed.
static String

Activity Action: Display UI for managing the billing relationship plans between a carrier and a specific subscriber.
static String

Broadcast Action: Request a refresh of the billing relationship plans between a carrier and a specific subscriber.
static Int

Device status is shared whenever possible.
static Int

Device status is shared with all numbers in the user's contacts.
static Int

Device status is not shared to a remote party.
static Int

Device status is shared with all selected contacts.
static String

TelephonyProvider column name for device to device sharing status.
static String

TelephonyProvider column name for contacts information that allow device to device sharing.
static Int

Indicates that data roaming is disabled for a subscription
static Int

Indicates that data roaming is enabled for a subscription
static Int

Indicates the default subscription ID in Telephony.
static String

Integer extra to specify SIM slot index.
static String

Integer extra used with ACTION_DEFAULT_SUBSCRIPTION_CHANGED and ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED to indicate the subscription which has changed.
static Int

Indicates invalid sim slot.
static Int

An invalid subscription identifier
static Int

A source of phone number: provided by an app that has carrier privilege.
static Int

A source of phone number: provided by IMS (IP Multimedia Subsystem) implementation.
static Int

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.
static Int

Represents a value indicating the data calling capabilities of a subscription.
static Int

Represents a value indicating the SMS capabilities of a subscription.
static Int

Represents a value indicating the voice calling capabilities of a subscription.
static Int

This constant is to designate a subscription as a Local-SIM Subscription.
static Int

This constant is to designate a subscription as a Remote-SIM Subscription.
static Int

This subscription is forced to data-centric mode

static Int

Subscription uses the default setting.
static Int

The usage setting is unknown.
static Int

This subscription is forced to voice-centric mode

Public methods
open Unit

Register for changes to the list of opportunistic subscription records or to the individual records themselves.
open Unit

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

Register for changes to the list of SubscriptionInfo records or to the individual records (active or inactive) themselves.
open Unit

Add a list of subscriptions into a group.
open Boolean

Checks whether the app with the given context is authorized to manage the given subscription according to its metadata.
open ParcelUuid

Inform SubscriptionManager that subscriptions in the list are bundled as a group.
open static SubscriptionManager!
from(context: Context!)
open MutableList<SubscriptionInfo!>?

Gets the SubscriptionInfo(s) of all embedded subscriptions accessible to the calling app, if any.
open static Int

Get active data subscription id.
open SubscriptionInfo!

Get the active SubscriptionInfo with the input subId.
open Int

Get the active subscription count.
open Int

open SubscriptionInfo!

Get the active SubscriptionInfo associated with the slotIndex

open MutableList<SubscriptionInfo!>?

Get the SubscriptionInfo(s) of the currently active SIM(s).
open MutableList<SubscriptionInfo!>

Get all subscription info records from SIMs that are inserted now or previously inserted.
open MutableList<SubscriptionInfo!>

Get both hidden and visible SubscriptionInfo(s) of the currently active SIM(s).
open static Int

Returns the system's default data subscription id.
open static Int

Returns the system's default SMS subscription id.
open static Int

Returns the system's default subscription id.
open static Int

Returns the system's default voice subscription id.
open MutableList<Uri!>

Get the list of contacts that allow device to device status sharing.
open Int

Returns the user-chosen device to device status sharing preference
open MutableList<SubscriptionInfo!>

Return opportunistic subscriptions that can be visible to the caller.
open String
getPhoneNumber(subscriptionId: Int)

Returns the phone number for the given subId, or an empty string if not available.
open String
getPhoneNumber(subscriptionId: Int, source: Int)

Returns the phone number for the given subscriptionId and source, or an empty string if not available.
open static Int
getSlotIndex(subscriptionId: Int)

Get slotIndex associated with the subscription.
open static Int
getSubscriptionId(slotIndex: Int)

Get the subscription id for specified logical SIM slot index.
open IntArray?
getSubscriptionIds(slotIndex: Int)

Get an array of subscription ids for the specified logical SIM slot Index.
open MutableList<SubscriptionPlan!>

Get the description of the billing relationship plan between a carrier and a specific subscriber.
open MutableList<SubscriptionInfo!>

Get subscriptionInfo list of subscriptions that are in the same group of given subId.
open Boolean
isActiveSubscriptionId(subscriptionId: Int)

Checks if the supplied subscription ID corresponds to a subscription which is actively in use on the device.
open Boolean

Returns true if the device is considered roaming on the current network for a subscription.
open Boolean

Returns whether the given subscription is associated with the calling user.
open static Boolean
isUsableSubscriptionId(subscriptionId: Int)

Check if the supplied subscription ID is usable.
open static Boolean
isValidSubscriptionId(subscriptionId: Int)

Check if the supplied subscription ID is valid.
open Unit

Unregister the OnOpportunisticSubscriptionsChangedListener that is currently listening opportunistic subscriptions change.
open Unit

Unregister the OnSubscriptionsChangedListener.
open Unit

Remove a list of subscriptions from their subscription group.
open Unit
setCarrierPhoneNumber(subscriptionId: Int, number: String)

Sets the phone number for the given subId for source carrier.
open Unit

Set the list of contacts that allow device to device status sharing for a subscription id.
open Unit
setDeviceToDeviceStatusSharingPreference(subscriptionId: Int, sharing: Int)

Set the device to device status sharing user preference for a subscription id.
open Boolean
setOpportunistic(opportunistic: Boolean, subId: Int)

Set whether a subscription is opportunistic, that is, whether the network it connects to has limited coverage.
open Unit
setSubscriptionOverrideCongested(subId: Int, overrideCongested: Boolean, networkTypes: IntArray, expirationDurationMillis: Long)

Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested.
open Unit
setSubscriptionOverrideCongested(subId: Int, overrideCongested: Boolean, expirationDurationMillis: Long)

Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested.
open Unit
setSubscriptionOverrideUnmetered(subId: Int, overrideUnmetered: Boolean, networkTypes: IntArray, expirationDurationMillis: Long)

Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered unmetered.
open Unit
setSubscriptionOverrideUnmetered(subId: Int, overrideUnmetered: Boolean, expirationDurationMillis: Long)

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

Set the description of the billing relationship plan between a carrier and a specific subscriber.
open Unit
setSubscriptionPlans(subId: Int, plans: MutableList<SubscriptionPlan!>, expirationDurationMillis: Long)

Set the description of the billing relationship plan between a carrier and a specific subscriber.
open Unit
switchToSubscription(subId: Int, callbackIntent: PendingIntent)

Switch to a certain subscription
Requires android.

Constants

ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED

Added in API level 26
static val ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED: String

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 
Value: "android.telephony.action.DEFAULT_SMS_SUBSCRIPTION_CHANGED"

ACTION_DEFAULT_SUBSCRIPTION_CHANGED

Added in API level 26
static val ACTION_DEFAULT_SUBSCRIPTION_CHANGED: String

Broadcast Action: The default subscription has changed. This has the following extra values:

The EXTRA_SUBSCRIPTION_INDEX extra indicates the current default subscription index 
Value: "android.telephony.action.DEFAULT_SUBSCRIPTION_CHANGED"

ACTION_MANAGE_SUBSCRIPTION_PLANS

Added in API level 28
static val ACTION_MANAGE_SUBSCRIPTION_PLANS: String

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.

Value: "android.telephony.action.MANAGE_SUBSCRIPTION_PLANS"

ACTION_REFRESH_SUBSCRIPTION_PLANS

Added in API level 28
static val ACTION_REFRESH_SUBSCRIPTION_PLANS: String

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.

Value: "android.telephony.action.REFRESH_SUBSCRIPTION_PLANS"

D2D_SHARING_ALL

Added in API level 31
static val D2D_SHARING_ALL: Int

Device status is shared whenever possible.

Value: 3

D2D_SHARING_ALL_CONTACTS

Added in API level 31
static val D2D_SHARING_ALL_CONTACTS: Int

Device status is shared with all numbers in the user's contacts.

Value: 1

D2D_SHARING_DISABLED

Added in API level 31
static val D2D_SHARING_DISABLED: Int

Device status is not shared to a remote party.

Value: 0

D2D_SHARING_SELECTED_CONTACTS

Added in API level 31
static val D2D_SHARING_SELECTED_CONTACTS: Int

Device status is shared with all selected contacts.

Value: 2

D2D_STATUS_SHARING

Added in API level 31
static val D2D_STATUS_SHARING: String

TelephonyProvider column name for device to device sharing status.

Type: INTEGER (int)

Value: "d2d_sharing_status"

D2D_STATUS_SHARING_SELECTED_CONTACTS

Added in API level 31
static val D2D_STATUS_SHARING_SELECTED_CONTACTS: String

TelephonyProvider column name for contacts information that allow device to device sharing.

Type: TEXT (String)

Value: "d2d_sharing_contacts"

DATA_ROAMING_DISABLE

Added in API level 22
static val DATA_ROAMING_DISABLE: Int

Indicates that data roaming is disabled for a subscription

Value: 0

DATA_ROAMING_ENABLE

Added in API level 22
static val DATA_ROAMING_ENABLE: Int

Indicates that data roaming is enabled for a subscription

Value: 1

DEFAULT_SUBSCRIPTION_ID

Added in API level 29
static val DEFAULT_SUBSCRIPTION_ID: Int

Indicates the default subscription ID in Telephony.

Value: 2147483647

EXTRA_SLOT_INDEX

Added in API level 30
static val EXTRA_SLOT_INDEX: String

Integer extra to specify SIM slot index.

Value: "android.telephony.extra.SLOT_INDEX"

EXTRA_SUBSCRIPTION_INDEX

Added in API level 26
static val EXTRA_SUBSCRIPTION_INDEX: String

Integer extra used with ACTION_DEFAULT_SUBSCRIPTION_CHANGED and ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED to indicate the subscription which has changed.

Value: "android.telephony.extra.SUBSCRIPTION_INDEX"

INVALID_SIM_SLOT_INDEX

Added in API level 29
static val INVALID_SIM_SLOT_INDEX: Int

Indicates invalid sim slot. This can be returned by getSlotIndex(int).

Value: -1

INVALID_SUBSCRIPTION_ID

Added in API level 24
static val INVALID_SUBSCRIPTION_ID: Int

An invalid subscription identifier

Value: -1

PHONE_NUMBER_SOURCE_CARRIER

Added in API level 33
static val PHONE_NUMBER_SOURCE_CARRIER: Int

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.

Value: 2

PHONE_NUMBER_SOURCE_IMS

Added in API level 33
static val PHONE_NUMBER_SOURCE_IMS: Int

A source of phone number: provided by IMS (IP Multimedia Subsystem) implementation. When IMS service is registered (as indicated by android.telephony.ims.RegistrationManager.RegistrationCallback#onRegistered(int)) the IMS implementation may return P-Associated-Uri SIP headers (RFC 3455). The URIs are the user’s 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 “global number” 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.

Value: 3

PHONE_NUMBER_SOURCE_UICC

Added in API level 33
static val PHONE_NUMBER_SOURCE_UICC: Int

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.

Value: 1

SERVICE_CAPABILITY_DATA

Added in API level 35
static val SERVICE_CAPABILITY_DATA: Int

Represents a value indicating the data calling capabilities of a subscription.

Value: 3

SERVICE_CAPABILITY_SMS

Added in API level 35
static val SERVICE_CAPABILITY_SMS: Int

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

Value: 2

SERVICE_CAPABILITY_VOICE

Added in API level 35
static val SERVICE_CAPABILITY_VOICE: Int

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

Value: 1

SUBSCRIPTION_TYPE_LOCAL_SIM

Added in API level 29
static val SUBSCRIPTION_TYPE_LOCAL_SIM: Int

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. 

Value: 0

SUBSCRIPTION_TYPE_REMOTE_SIM

Added in API level 29
static val SUBSCRIPTION_TYPE_REMOTE_SIM: Int

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. 

Value: 1

USAGE_SETTING_DATA_CENTRIC

Added in API level 33
static val USAGE_SETTING_DATA_CENTRIC: Int

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.

Value: 2

USAGE_SETTING_DEFAULT

Added in API level 33
static val USAGE_SETTING_DEFAULT: Int

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.

Value: 0

USAGE_SETTING_UNKNOWN

Added in API level 33
static val USAGE_SETTING_UNKNOWN: Int

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.

Value: -1

USAGE_SETTING_VOICE_CENTRIC

Added in API level 33
static val USAGE_SETTING_VOICE_CENTRIC: Int

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.

Value: 1

Public methods

addOnOpportunisticSubscriptionsChangedListener

Added in API level 29
open fun addOnOpportunisticSubscriptionsChangedListener(
    executor: Executor, 
    listener: SubscriptionManager.OnOpportunisticSubscriptionsChangedListener
): Unit

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
listener SubscriptionManager.OnOpportunisticSubscriptionsChangedListener: an instance of OnOpportunisticSubscriptionsChangedListener with onOpportunisticSubscriptionsChanged overridden. This value cannot be null.
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.

addOnSubscriptionsChangedListener

Added in API level 22
Deprecated in API level 31
open fun addOnSubscriptionsChangedListener(listener: SubscriptionManager.OnSubscriptionsChangedListener!): Unit

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

Added in API level 30
open fun addOnSubscriptionsChangedListener(
    executor: Executor, 
    listener: SubscriptionManager.OnSubscriptionsChangedListener
): Unit

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
listener SubscriptionManager.OnSubscriptionsChangedListener: an instance of OnSubscriptionsChangedListener with OnSubscriptionsChangedListener.onSubscriptionsChanged() overridden. This value cannot be null.
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.

addSubscriptionsIntoGroup

Added in API level 29
open fun addSubscriptionsIntoGroup(
    subIdList: MutableList<Int!>, 
    groupUuid: ParcelUuid
): Unit

Add a list of subscriptions into a group. See createSubscriptionGroup(java.util.List) for more details. Caller will either have android.Manifest.permission#MODIFY_PHONE_STATE permission or had carrier privilege permission on the subscriptions: TelephonyManager.hasCarrierPrivileges() or canManageSubscription(android.telephony.SubscriptionInfo)
Requires android.Manifest.permission#MODIFY_PHONE_STATE

Parameters
subIdList MutableList<Int!>: 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.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.
java.lang.IllegalArgumentException if the some subscriptions in the list doesn't exist.
java.lang.IllegalStateException if Telephony service is in bad state.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

canManageSubscription

Added in API level 28
open fun canManageSubscription(info: SubscriptionInfo!): Boolean

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 android.telephony.TelephonyManager#hasCarrierPrivileges.

Parameters
info SubscriptionInfo!: The subscription to check.
Return
Boolean whether the app is authorized to manage this subscription per its metadata.

createSubscriptionGroup

Added in API level 29
open fun createSubscriptionGroup(subIdList: MutableList<Int!>): ParcelUuid

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 android.Manifest.permission#MODIFY_PHONE_STATE permission or had carrier privilege permission on the subscriptions: TelephonyManager.hasCarrierPrivileges() or canManageSubscription(android.telephony.SubscriptionInfo)
Requires android.Manifest.permission#MODIFY_PHONE_STATE

Parameters
subIdList MutableList<Int!>: list of subId that will be in the same group This value cannot be null.
Return
ParcelUuid groupUUID a UUID assigned to the subscription group. This value cannot be null.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.
java.lang.IllegalArgumentException if any of the subscriptions in the list doesn't exist.
java.lang.IllegalStateException if Telephony service is in bad state.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

from

Added in API level 22
Deprecated in API level 28
open static fun from(context: Context!): SubscriptionManager!

Deprecated: developers should always obtain references directly from Context.getSystemService(Class).

getAccessibleSubscriptionInfoList

Added in API level 28
open fun getAccessibleSubscriptionInfoList(): MutableList<SubscriptionInfo!>?

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.

Return
MutableList<SubscriptionInfo!>? Sorted list of the current embedded SubscriptionInfo records available on the device which are accessible to the caller.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_EUICC.

getActiveDataSubscriptionId

Added in API level 30
open static fun getActiveDataSubscriptionId(): Int

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

Return
Int Active data subscription id if any is chosen, or INVALID_SUBSCRIPTION_ID if not.

getActiveSubscriptionInfo

Added in API level 22
open fun getActiveSubscriptionInfo(subId: Int): SubscriptionInfo!

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

Parameters
subId Int: The unique SubscriptionInfo key in database.
Return
SubscriptionInfo! SubscriptionInfo, maybe null if its not active.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getActiveSubscriptionInfoCount

Added in API level 22
open fun getActiveSubscriptionInfoCount(): Int

Get the active subscription count.
Requires android.Manifest.permission#READ_PHONE_STATE

Return
Int The current number of active subscriptions.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getActiveSubscriptionInfoCountMax

Added in API level 22
open fun getActiveSubscriptionInfoCountMax(): Int
Return
Int the maximum number of active subscriptions that will be returned by getActiveSubscriptionInfoList and the value returned by getActiveSubscriptionInfoCount.

getActiveSubscriptionInfoForSimSlotIndex

Added in API level 22
open fun getActiveSubscriptionInfoForSimSlotIndex(slotIndex: Int): SubscriptionInfo!

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

Parameters
slotIndex Int: the slot which the subscription is inserted
Return
SubscriptionInfo! SubscriptionInfo, maybe null if its not active
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getActiveSubscriptionInfoList

Added in API level 22
open fun getActiveSubscriptionInfoList(): MutableList<SubscriptionInfo!>?

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

Return
MutableList<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.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getAllSubscriptionInfoList

Added in API level 34
open fun getAllSubscriptionInfoList(): MutableList<SubscriptionInfo!>

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 android.Manifest.permission#READ_PHONE_STATE or carrier privileges

Return
MutableList<SubscriptionInfo!> List of all SubscriptionInfo records from SIMs that are inserted or previously inserted. Sorted by SubscriptionInfo.getSimSlotIndex(), then SubscriptionInfo.getSubscriptionId().
Exceptions
java.lang.SecurityException if callers do not hold the required permission.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getCompleteActiveSubscriptionInfoList

Added in API level 30
open fun getCompleteActiveSubscriptionInfoList(): MutableList<SubscriptionInfo!>

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.

Return
MutableList<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.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getDefaultDataSubscriptionId

Added in API level 24
open static fun getDefaultDataSubscriptionId(): Int

Returns the system's default data subscription id. On a voice only device or on error, will return INVALID_SUBSCRIPTION_ID.

Return
Int the default data subscription Id.

getDefaultSmsSubscriptionId

Added in API level 24
open static fun getDefaultSmsSubscriptionId(): Int

Returns the system's default SMS subscription id. On a data only device or on error, will return INVALID_SUBSCRIPTION_ID.

Return
Int the default SMS subscription Id.

getDefaultSubscriptionId

Added in API level 24
open static fun getDefaultSubscriptionId(): Int

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.

Return
Int the "system" default subscription id.

getDefaultVoiceSubscriptionId

Added in API level 24
open static fun getDefaultVoiceSubscriptionId(): Int

Returns the system's default voice subscription id. On a data only device or on error, will return INVALID_SUBSCRIPTION_ID.

Return
Int the default voice subscription Id.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getDeviceToDeviceStatusSharingContacts

Added in API level 31
open fun getDeviceToDeviceStatusSharingContacts(subscriptionId: Int): MutableList<Uri!>

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

Parameters
subscriptionId Int: Subscription id.
Return
MutableList<Uri!> The list of contacts that allow device to device status sharing. This value cannot be null.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getDeviceToDeviceStatusSharingPreference

Added in API level 31
open fun getDeviceToDeviceStatusSharingPreference(subscriptionId: Int): Int

Returns the user-chosen device to device status sharing preference

Parameters
subscriptionId Int: Subscription id of subscription
Return
Int The device to device status sharing preference Value is android.telephony.SubscriptionManager#D2D_SHARING_DISABLED, android.telephony.SubscriptionManager#D2D_SHARING_ALL_CONTACTS, android.telephony.SubscriptionManager#D2D_SHARING_SELECTED_CONTACTS, or android.telephony.SubscriptionManager#D2D_SHARING_ALL
Exceptions
java.lang.SecurityException if the caller doesn't have permissions required.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getOpportunisticSubscriptions

Added in API level 29
open fun getOpportunisticSubscriptions(): MutableList<SubscriptionInfo!>

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

Return
MutableList<SubscriptionInfo!> the list of opportunistic subscription info. If none exists, an empty list. This value cannot be null.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getPhoneNumber

Added in API level 33
open fun getPhoneNumber(subscriptionId: Int): String

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 android.telephony.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 android.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.
Return
String the phone number, or an empty string if not available. This value cannot be null.
Exceptions
java.lang.IllegalStateException if the telephony process is not currently available.
java.lang.SecurityException if the caller doesn't have permissions required.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getPhoneNumber

Added in API level 33
open fun getPhoneNumber(
    subscriptionId: Int, 
    source: Int
): String

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 android.telephony.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 android.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 android.telephony.SubscriptionManager#PHONE_NUMBER_SOURCE_UICC, android.telephony.SubscriptionManager#PHONE_NUMBER_SOURCE_CARRIER, or android.telephony.SubscriptionManager#PHONE_NUMBER_SOURCE_IMS
Return
String the phone number, or an empty string if not available. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if source is invalid.
java.lang.IllegalStateException if the telephony process is not currently available.
java.lang.SecurityException if the caller doesn't have permissions required.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

getSlotIndex

Added in API level 29
open static fun getSlotIndex(subscriptionId: Int): Int

Get slotIndex associated with the subscription.

Parameters
subscriptionId Int: the unique SubscriptionInfo index in database
Return
Int slotIndex as a positive integer or INVALID_SIM_SLOT_INDEX if the supplied subscriptionId doesn't have an associated slot index.

getSubscriptionId

Added in API level 34
open static fun getSubscriptionId(slotIndex: Int): Int

Get the subscription id for specified logical SIM slot index.

Parameters
slotIndex Int: The logical SIM slot index.
Return
Int The subscription id. INVALID_SUBSCRIPTION_ID if SIM is absent.

getSubscriptionIds

Added in API level 29
Deprecated in API level 34
open fun getSubscriptionIds(slotIndex: Int): IntArray?

Deprecated: 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.
Return
IntArray? 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

Added in API level 28
open fun getSubscriptionPlans(subId: Int): MutableList<SubscriptionPlan!>

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
Return
MutableList<SubscriptionPlan!> This value cannot be null.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.

getSubscriptionsInGroup

Added in API level 29
open fun getSubscriptionsInGroup(groupUuid: ParcelUuid): MutableList<SubscriptionInfo!>

Get subscriptionInfo list of subscriptions that are in the same group of given subId. Caller must have 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:


Requires android.Manifest.permission#READ_PHONE_STATE
Parameters
groupUuid ParcelUuid: of which list of subInfo will be returned. This value cannot be null.
Return
MutableList<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.
Exceptions
java.lang.IllegalStateException if Telephony service is in bad state.
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

isActiveSubscriptionId

Added in API level 29
open fun isActiveSubscriptionId(subscriptionId: Int): Boolean

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

Parameters
subscriptionId Int: the subscription ID.
Return
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
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

isNetworkRoaming

Added in API level 22
open fun isNetworkRoaming(subId: Int): Boolean

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
Return
Boolean true if the network for the subscription is roaming, false otherwise

isSubscriptionAssociatedWithUser

Added in API level Baklava
open fun isSubscriptionAssociatedWithUser(subscriptionId: Int): Boolean

Returns whether the given subscription is associated with the calling user.
Requires android.Manifest.permission#READ_PHONE_STATE

Parameters
subscriptionId Int: the subscription ID of the subscription
Return
Boolean true if the subscription is associated with the user that the current process is running in; false otherwise.
Exceptions
java.lang.IllegalArgumentException if subscription doesn't exist.
java.lang.SecurityException if the caller doesn't have permissions required.

isUsableSubscriptionId

Added in API level 29
open static fun isUsableSubscriptionId(subscriptionId: Int): Boolean

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
Return
Boolean true if the subscription ID is usable; false otherwise.

isValidSubscriptionId

Added in API level 29
open static fun isValidSubscriptionId(subscriptionId: Int): Boolean

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.
Return
Boolean true if the supplied subscriptionId is valid; false otherwise.

removeOnOpportunisticSubscriptionsChangedListener

Added in API level 29
open fun removeOnOpportunisticSubscriptionsChangedListener(listener: SubscriptionManager.OnOpportunisticSubscriptionsChangedListener): Unit

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

Added in API level 22
open fun removeOnSubscriptionsChangedListener(listener: SubscriptionManager.OnSubscriptionsChangedListener!): Unit

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

Added in API level 29
open fun removeSubscriptionsFromGroup(
    subIdList: MutableList<Int!>, 
    groupUuid: ParcelUuid
): Unit

Remove a list of subscriptions from their subscription group. Caller will either have android.Manifest.permission#MODIFY_PHONE_STATE permission or has carrier privilege permission on all of the subscriptions provided in subIdList.
Requires android.Manifest.permission#MODIFY_PHONE_STATE

Parameters
subIdList MutableList<Int!>: 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.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.
java.lang.IllegalArgumentException if the some subscriptions in the list doesn't belong the specified group.
java.lang.IllegalStateException if Telephony service is in bad state.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

setCarrierPhoneNumber

Added in API level 33
open fun setCarrierPhoneNumber(
    subscriptionId: Int, 
    number: String
): Unit

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.
Exceptions
java.lang.IllegalStateException if the telephony process is not currently available.
java.lang.NullPointerException if number is null.
java.lang.SecurityException if the caller doesn't have permissions required.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

setDeviceToDeviceStatusSharingContacts

Added in API level 31
open fun setDeviceToDeviceStatusSharingContacts(
    subscriptionId: Int, 
    contacts: MutableList<Uri!>
): Unit

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 android.Manifest.permission#MODIFY_PHONE_STATE

Parameters
subscriptionId Int: The subscription id.
contacts MutableList<Uri!>: The list of contacts that allow device to device status sharing. This value cannot be null.
Exceptions
java.lang.SecurityException if the caller doesn't have permissions required.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

setDeviceToDeviceStatusSharingPreference

Added in API level 31
open fun setDeviceToDeviceStatusSharingPreference(
    subscriptionId: Int, 
    sharing: Int
): Unit

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 android.Manifest.permission#MODIFY_PHONE_STATE

Parameters
subscriptionId Int: The subscription id.
sharing Int: The status sharing preference. Value is android.telephony.SubscriptionManager#D2D_SHARING_DISABLED, android.telephony.SubscriptionManager#D2D_SHARING_ALL_CONTACTS, android.telephony.SubscriptionManager#D2D_SHARING_SELECTED_CONTACTS, or android.telephony.SubscriptionManager#D2D_SHARING_ALL
Exceptions
java.lang.SecurityException if the caller doesn't have permissions required.
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

setOpportunistic

Added in API level 29
open fun setOpportunistic(
    opportunistic: Boolean, 
    subId: Int
): Boolean

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 android.Manifest.permission#MODIFY_PHONE_STATE or carrier privilege permission of the subscription.
Requires android.Manifest.permission#MODIFY_PHONE_STATE

Parameters
opportunistic Boolean: whether it’s opportunistic subscription.
subId Int: the unique SubscriptionInfo index in database
Return
Boolean true if the operation is succeed, false otherwise.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_SUBSCRIPTION.

setSubscriptionOverrideCongested

Added in API level 31
open fun setSubscriptionOverrideCongested(
    subId: Int, 
    overrideCongested: Boolean, 
    networkTypes: IntArray, 
    expirationDurationMillis: Long
): Unit

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 IntArray: 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 android.telephony.TelephonyManager#NETWORK_TYPE_UNKNOWN, android.telephony.TelephonyManager#NETWORK_TYPE_GPRS, android.telephony.TelephonyManager#NETWORK_TYPE_EDGE, android.telephony.TelephonyManager#NETWORK_TYPE_UMTS, android.telephony.TelephonyManager#NETWORK_TYPE_CDMA, android.telephony.TelephonyManager#NETWORK_TYPE_EVDO_0, android.telephony.TelephonyManager#NETWORK_TYPE_EVDO_A, android.telephony.TelephonyManager#NETWORK_TYPE_1xRTT, android.telephony.TelephonyManager#NETWORK_TYPE_HSDPA, android.telephony.TelephonyManager#NETWORK_TYPE_HSUPA, android.telephony.TelephonyManager#NETWORK_TYPE_HSPA, android.telephony.TelephonyManager#NETWORK_TYPE_IDEN, android.telephony.TelephonyManager#NETWORK_TYPE_EVDO_B, android.telephony.TelephonyManager#NETWORK_TYPE_LTE, android.telephony.TelephonyManager#NETWORK_TYPE_EHRPD, android.telephony.TelephonyManager#NETWORK_TYPE_HSPAP, android.telephony.TelephonyManager#NETWORK_TYPE_GSM, android.telephony.TelephonyManager#NETWORK_TYPE_TD_SCDMA, android.telephony.TelephonyManager#NETWORK_TYPE_IWLAN, or android.telephony.TelephonyManager#NETWORK_TYPE_NR
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.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.

setSubscriptionOverrideCongested

Added in API level 28
open fun setSubscriptionOverrideCongested(
    subId: Int, 
    overrideCongested: Boolean, 
    expirationDurationMillis: Long
): Unit

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.
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.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.

setSubscriptionOverrideUnmetered

Added in API level 31
open fun setSubscriptionOverrideUnmetered(
    subId: Int, 
    overrideUnmetered: Boolean, 
    networkTypes: IntArray, 
    expirationDurationMillis: Long
): Unit

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 IntArray: 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 android.telephony.TelephonyManager#NETWORK_TYPE_UNKNOWN, android.telephony.TelephonyManager#NETWORK_TYPE_GPRS, android.telephony.TelephonyManager#NETWORK_TYPE_EDGE, android.telephony.TelephonyManager#NETWORK_TYPE_UMTS, android.telephony.TelephonyManager#NETWORK_TYPE_CDMA, android.telephony.TelephonyManager#NETWORK_TYPE_EVDO_0, android.telephony.TelephonyManager#NETWORK_TYPE_EVDO_A, android.telephony.TelephonyManager#NETWORK_TYPE_1xRTT, android.telephony.TelephonyManager#NETWORK_TYPE_HSDPA, android.telephony.TelephonyManager#NETWORK_TYPE_HSUPA, android.telephony.TelephonyManager#NETWORK_TYPE_HSPA, android.telephony.TelephonyManager#NETWORK_TYPE_IDEN, android.telephony.TelephonyManager#NETWORK_TYPE_EVDO_B, android.telephony.TelephonyManager#NETWORK_TYPE_LTE, android.telephony.TelephonyManager#NETWORK_TYPE_EHRPD, android.telephony.TelephonyManager#NETWORK_TYPE_HSPAP, android.telephony.TelephonyManager#NETWORK_TYPE_GSM, android.telephony.TelephonyManager#NETWORK_TYPE_TD_SCDMA, android.telephony.TelephonyManager#NETWORK_TYPE_IWLAN, or android.telephony.TelephonyManager#NETWORK_TYPE_NR
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.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.

setSubscriptionOverrideUnmetered

Added in API level 28
open fun setSubscriptionOverrideUnmetered(
    subId: Int, 
    overrideUnmetered: Boolean, 
    expirationDurationMillis: Long
): Unit

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.
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.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.

setSubscriptionPlans

Added in API level 28
Deprecated in API level 33
open fun setSubscriptionPlans(
    subId: Int, 
    plans: MutableList<SubscriptionPlan!>
): Unit

Deprecated: 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:

Parameters
subId Int: the subscriber this relationship applies to. An empty list may be sent to clear any existing plans.
plans MutableList<SubscriptionPlan!>: 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.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.
java.lang.IllegalArgumentException if plans don't meet the requirements defined in SubscriptionPlan.

setSubscriptionPlans

Added in API level 33
open fun setSubscriptionPlans(
    subId: Int, 
    plans: MutableList<SubscriptionPlan!>, 
    expirationDurationMillis: Long
): Unit

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 MutableList<SubscriptionPlan!>: 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.
Exceptions
java.lang.SecurityException if the caller doesn't meet the requirements outlined above.
java.lang.IllegalArgumentException if plans don't meet the requirements defined in SubscriptionPlan.

switchToSubscription

Added in API level 29
Deprecated in API level 34
open fun switchToSubscription(
    subId: Int, 
    callbackIntent: PendingIntent
): Unit

Deprecated: this API is a duplicate of EuiccManager.switchToSubscription(int, 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.
Exceptions
java.lang.UnsupportedOperationException If the device does not have PackageManager.FEATURE_TELEPHONY_EUICC.