SubscriptionManager
open class SubscriptionManager
| kotlin.Any | |
| ↳ | android.telephony.SubscriptionManager |
SubscriptionManager is the application interface to SubscriptionController and provides information about the current Telephony Subscriptions.
Summary
Nested classes |
|
|---|---|
| open |
A listener class for monitoring changes to |
| open |
A listener class for monitoring changes to |
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 |
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 |
| static Int |
Indicates invalid sim slot. |
| static Int |
An invalid subscription identifier |
| 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. |
Public methods |
|
|---|---|
| open Unit |
addOnOpportunisticSubscriptionsChangedListener(executor: Executor, listener: SubscriptionManager.OnOpportunisticSubscriptionsChangedListener)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 |
| open Unit |
addOnSubscriptionsChangedListener(executor: Executor, listener: SubscriptionManager.OnSubscriptionsChangedListener)Register for changes to the list of active |
| open Unit |
addSubscriptionsIntoGroup(subIdList: MutableList<Int!>, groupUuid: ParcelUuid)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 |
createSubscriptionGroup(subIdList: MutableList<Int!>)Inform SubscriptionManager that subscriptions in the list are bundled as a group. |
| open static SubscriptionManager! | |
| 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! |
getActiveSubscriptionInfo(subId: Int)Get the active SubscriptionInfo with the input subId. |
| open Int |
Requires Permission: |
| open Int | |
| open SubscriptionInfo! |
getActiveSubscriptionInfoForSimSlotIndex(slotIndex: Int)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 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<SubscriptionInfo!> |
Return opportunistic subscriptions that can be visible to the caller. |
| open static Int |
getSlotIndex(subscriptionId: Int)Get slotIndex associated with the subscription. |
| open IntArray? |
getSubscriptionIds(slotIndex: Int)Get an array of Subscription Ids for specified slot Index. |
| open MutableList<SubscriptionPlan!> |
getSubscriptionPlans(subId: Int)Get the description of the billing relationship plan between a carrier and a specific subscriber. |
| open MutableList<SubscriptionInfo!> |
getSubscriptionsInGroup(groupUuid: ParcelUuid)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 |
isNetworkRoaming(subId: Int)Returns true if the device is considered roaming on the current network for a subscription. |
| 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 |
removeOnOpportunisticSubscriptionsChangedListener(listener: SubscriptionManager.OnOpportunisticSubscriptionsChangedListener)Unregister the |
| open Unit |
Unregister the |
| open Unit |
removeSubscriptionsFromGroup(subIdList: MutableList<Int!>, groupUuid: ParcelUuid)Remove a list of subscriptions from their subscription group. |
| 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, timeoutMillis: 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, timeoutMillis: Long)Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered unmetered. |
| open Unit |
setSubscriptionPlans(subId: Int, plans: MutableList<SubscriptionPlan!>)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 |
Constants
ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED
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
static val ACTION_DEFAULT_SUBSCRIPTION_CHANGED: String
Broadcast Action: The default subscription has changed. This has the following extra values:
TheEXTRA_SUBSCRIPTION_INDEX extra indicates the current default subscription index
Value: "android.telephony.action.DEFAULT_SUBSCRIPTION_CHANGED"
ACTION_MANAGE_SUBSCRIPTION_PLANS
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
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"
DATA_ROAMING_DISABLE
static val DATA_ROAMING_DISABLE: Int
Indicates that data roaming is disabled for a subscription
Value: 0
DATA_ROAMING_ENABLE
static val DATA_ROAMING_ENABLE: Int
Indicates that data roaming is enabled for a subscription
Value: 1
DEFAULT_SUBSCRIPTION_ID
static val DEFAULT_SUBSCRIPTION_ID: Int
Indicates the default subscription ID in Telephony.
Value: 2147483647
EXTRA_SLOT_INDEX
static val EXTRA_SLOT_INDEX: String
Integer extra to specify SIM slot index.
Value: "android.telephony.extra.SLOT_INDEX"
EXTRA_SUBSCRIPTION_INDEX
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
static val INVALID_SIM_SLOT_INDEX: Int
Indicates invalid sim slot. This can be returned by getSlotIndex(int).
Value: -1
INVALID_SUBSCRIPTION_ID
static val INVALID_SUBSCRIPTION_ID: Int
An invalid subscription identifier
Value: -1
SUBSCRIPTION_TYPE_LOCAL_SIM
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
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
Public methods
addOnOpportunisticSubscriptionsChangedListener
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(). To dispatch events through a shared thread pool, you can use AsyncTask#THREAD_POOL_EXECUTOR. |
addOnSubscriptionsChangedListener
open fun addOnSubscriptionsChangedListener(listener: SubscriptionManager.OnSubscriptionsChangedListener!): Unit
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 | |
|---|---|
listener |
SubscriptionManager.OnSubscriptionsChangedListener!: an instance of OnSubscriptionsChangedListener with onSubscriptionsChanged overridden. |
addOnSubscriptionsChangedListener
open fun addOnSubscriptionsChangedListener(
executor: Executor,
listener: SubscriptionManager.OnSubscriptionsChangedListener
): Unit
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 | |
|---|---|
listener |
SubscriptionManager.OnSubscriptionsChangedListener: an instance of OnSubscriptionsChangedListener with 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(). To dispatch events through a shared thread pool, you can use AsyncTask#THREAD_POOL_EXECUTOR. |
addSubscriptionsIntoGroup
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. |
canManageSubscription
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.
| Parameters | |
|---|---|
info |
SubscriptionInfo!: The subscription to check. |
| Return | |
|---|---|
Boolean |
whether the app is authorized to manage this subscription per its metadata. |
createSubscriptionGroup
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. |
from
open static funfrom(context: Context!): SubscriptionManager!
Deprecated: developers should always obtain references directly from Context#getSystemService(Class).
getAccessibleSubscriptionInfoList
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.
|
getActiveDataSubscriptionId
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(). Eg. Opportunistics data See PhoneStateListener#onActiveDataSubscriptionIdChanged(int) for the details.
| Return | |
|---|---|
Int |
Active data subscription id if any is chosen, or SubscriptionManager.INVALID_SUBSCRIPTION_ID if not. |
getActiveSubscriptionInfo
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. |
getActiveSubscriptionInfoCount
open fun getActiveSubscriptionInfoCount(): Int
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 android.Manifest.permission#READ_PHONE_STATE
| Return | |
|---|---|
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
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
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 |
getActiveSubscriptionInfoList
open fun getActiveSubscriptionInfoList(): MutableList<SubscriptionInfo!>!
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 android.Manifest.permission#READ_PHONE_STATE
| Return | |
|---|---|
MutableList<SubscriptionInfo!>! |
Sorted list of the currently SubscriptionInfo records available on the device.
|
getCompleteActiveSubscriptionInfoList
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. |
getDefaultDataSubscriptionId
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
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
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
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. |
getOpportunisticSubscriptions
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. |
getSlotIndex
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. |
getSubscriptionIds
open fun getSubscriptionIds(slotIndex: Int): IntArray?
Get an array of Subscription Ids for specified slot Index.
| Parameters | |
|---|---|
slotIndex |
Int: the slot index. |
| Return | |
|---|---|
IntArray? |
subscription Ids or null if the given slot Index is not valid or there are no active subscriptions in the slot. |
getSubscriptionPlans
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:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges(). - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING.
| Parameters | |
|---|---|
subId |
Int: the subscriber this relationship applies to |
| Return | |
|---|---|
MutableList<SubscriptionPlan!> |
This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.SecurityException |
if the caller doesn't meet the requirements outlined above. |
getSubscriptionsInGroup
open fun getSubscriptionsInGroup(groupUuid: ParcelUuid): MutableList<SubscriptionInfo!>
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 android.Manifest.permission#READ_PHONE_STATE permission or had carrier privilege permission on the subscription. TelephonyManager#hasCarrierPrivileges()
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. |
isActiveSubscriptionId
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. |
isNetworkRoaming
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 |
isUsableSubscriptionId
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
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
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
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
open fun removeSubscriptionsFromGroup(
subIdList: MutableList<Int!>,
groupUuid: ParcelUuid
): Unit
Remove a list of subscriptions from their subscription 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 removing from their groups. This value cannot be null. |
groupUuid |
ParcelUuid: 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. |
setOpportunistic
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. |
setSubscriptionOverrideCongested
open fun setSubscriptionOverrideCongested(
subId: Int,
overrideCongested: Boolean,
timeoutMillis: 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:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges(). - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING.
| Parameters | |
|---|---|
subId |
Int: the subscriber this override applies to. |
overrideCongested |
Boolean: set if the subscription should be considered congested. |
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. |
| Exceptions | |
|---|---|
java.lang.SecurityException |
if the caller doesn't meet the requirements outlined above. |
setSubscriptionOverrideUnmetered
open fun setSubscriptionOverrideUnmetered(
subId: Int,
overrideUnmetered: Boolean,
timeoutMillis: 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:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges(). - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING.
| Parameters | |
|---|---|
subId |
Int: the subscriber this override applies to. |
overrideUnmetered |
Boolean: set if the billing relationship should be considered unmetered. |
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. |
| Exceptions | |
|---|---|
java.lang.SecurityException |
if the caller doesn't meet the requirements outlined above. |
setSubscriptionPlans
open fun setSubscriptionPlans(
subId: Int,
plans: MutableList<SubscriptionPlan!>
): 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:
- The carrier app for this subscriberId, as determined by
TelephonyManager#hasCarrierPrivileges(). - The carrier app explicitly delegated access through
CarrierConfigManager#KEY_CONFIG_PLANS_PACKAGE_OVERRIDE_STRING.
| Parameters | |
|---|---|
subId |
Int: the subscriber this relationship applies to. An empty list may be sent to clear any existing plans. |
plans |
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. |
switchToSubscription
open fun switchToSubscription(
subId: Int,
callbackIntent: PendingIntent
): Unit
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. |