Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

SubscriptionManager

public class SubscriptionManager
extends Object

java.lang.Object
   ↳ android.telephony.SubscriptionManager


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

Instances of this class must be obtained using Context.getSystemService(Class) with the argument SubscriptionManager.class or Context.getSystemService(String) with the argument Context.TELEPHONY_SUBSCRIPTION_SERVICE.

Summary

Nested classes

class SubscriptionManager.OnSubscriptionsChangedListener

A listener class for monitoring changes to SubscriptionInfo records. 

Constants

String ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED

Broadcast Action: The default sms subscription has changed.

String ACTION_DEFAULT_SUBSCRIPTION_CHANGED

Broadcast Action: The default subscription has changed.

String ACTION_MANAGE_SUBSCRIPTION_PLANS

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

String ACTION_REFRESH_SUBSCRIPTION_PLANS

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

int DATA_ROAMING_DISABLE

Indicates that data roaming is disabled for a subscription

int DATA_ROAMING_ENABLE

Indicates that data roaming is enabled for a subscription

String EXTRA_SUBSCRIPTION_INDEX

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

int INVALID_SUBSCRIPTION_ID

An invalid subscription identifier

Public methods

void addOnSubscriptionsChangedListener(SubscriptionManager.OnSubscriptionsChangedListener listener)

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

boolean canManageSubscription(SubscriptionInfo info)

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

static SubscriptionManager from(Context context)

This method was deprecated in API level 28. developers should always obtain references directly from Context.getSystemService(Class).

List<SubscriptionInfo> getAccessibleSubscriptionInfoList()

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

SubscriptionInfo getActiveSubscriptionInfo(int subId)

Get the active SubscriptionInfo with the input subId.

int getActiveSubscriptionInfoCount()

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

int getActiveSubscriptionInfoCountMax()
SubscriptionInfo getActiveSubscriptionInfoForSimSlotIndex(int slotIndex)

Get the active SubscriptionInfo associated with the slotIndex

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

List<SubscriptionInfo> getActiveSubscriptionInfoList()

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

static int getDefaultDataSubscriptionId()

Returns the system's default data subscription id.

static int getDefaultSmsSubscriptionId()

Returns the system's default SMS subscription id.

static int getDefaultSubscriptionId()

Returns the system's default subscription id.

static int getDefaultVoiceSubscriptionId()

Returns the system's default voice subscription id.

List<SubscriptionPlan> getSubscriptionPlans(int subId)

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

boolean isNetworkRoaming(int subId)

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

void removeOnSubscriptionsChangedListener(SubscriptionManager.OnSubscriptionsChangedListener listener)

Unregister the SubscriptionManager.OnSubscriptionsChangedListener.

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

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

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

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

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

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

Inherited methods

Constants

ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED

added in API level 26
public static final String ACTION_DEFAULT_SMS_SUBSCRIPTION_CHANGED

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

EXTRA_SUBSCRIPTION_INDEX extra indicates the current default sms subscription index

Constant Value: "android.telephony.action.DEFAULT_SMS_SUBSCRIPTION_CHANGED"

ACTION_DEFAULT_SUBSCRIPTION_CHANGED

added in API level 26
public static final String ACTION_DEFAULT_SUBSCRIPTION_CHANGED

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

The EXTRA_SUBSCRIPTION_INDEX extra indicates the current default subscription index

Constant Value: "android.telephony.action.DEFAULT_SUBSCRIPTION_CHANGED"

ACTION_MANAGE_SUBSCRIPTION_PLANS

added in API level 28
public static final String ACTION_MANAGE_SUBSCRIPTION_PLANS

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

Carrier apps are encouraged to implement this activity, and the OS will provide an affordance to quickly enter this activity, typically via Settings. This affordance will only be shown when the carrier app is actively providing subscription plan information via setSubscriptionPlans(int, List).

Contains EXTRA_SUBSCRIPTION_INDEX to indicate which subscription the user is interested in.

Constant Value: "android.telephony.action.MANAGE_SUBSCRIPTION_PLANS"

ACTION_REFRESH_SUBSCRIPTION_PLANS

added in API level 28
public static final String ACTION_REFRESH_SUBSCRIPTION_PLANS

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

Carrier apps are encouraged to implement this receiver, and the OS will provide an affordance to request a refresh. This affordance will only be shown when the carrier app is actively providing subscription plan information via setSubscriptionPlans(int, List).

Contains EXTRA_SUBSCRIPTION_INDEX to indicate which subscription the user is interested in.

Receivers should protect themselves by checking that the sender holds the android.permission.MANAGE_SUBSCRIPTION_PLANS permission.

Constant Value: "android.telephony.action.REFRESH_SUBSCRIPTION_PLANS"

DATA_ROAMING_DISABLE

added in API level 22
public static final int DATA_ROAMING_DISABLE

Indicates that data roaming is disabled for a subscription

Constant Value: 0 (0x00000000)

DATA_ROAMING_ENABLE

added in API level 22
public static final int DATA_ROAMING_ENABLE

Indicates that data roaming is enabled for a subscription

Constant Value: 1 (0x00000001)

EXTRA_SUBSCRIPTION_INDEX

added in API level 26
public static final String EXTRA_SUBSCRIPTION_INDEX

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

Constant Value: "android.telephony.extra.SUBSCRIPTION_INDEX"

INVALID_SUBSCRIPTION_ID

added in API level 24
public static final int INVALID_SUBSCRIPTION_ID

An invalid subscription identifier

Constant Value: -1 (0xffffffff)

Public methods

addOnSubscriptionsChangedListener

added in API level 22
public void addOnSubscriptionsChangedListener (SubscriptionManager.OnSubscriptionsChangedListener listener)

Register for changes to the list of active SubscriptionInfo records or to the individual records themselves. When a change occurs the onSubscriptionsChanged method of the listener will be invoked immediately if there has been a notification.

Parameters
listener SubscriptionManager.OnSubscriptionsChangedListener: an instance of SubscriptionManager.OnSubscriptionsChangedListener with onSubscriptionsChanged overridden.

canManageSubscription

added in API level 28
public boolean canManageSubscription (SubscriptionInfo info)

Checks whether the app with the given context is authorized to manage the given subscription according to its metadata. Only supported for embedded subscriptions (if SubscriptionInfo#isEmbedded returns true).

Parameters
info SubscriptionInfo: The subscription to check.

Returns
boolean whether the app is authorized to manage this subscription per its metadata.

Throws
IllegalArgumentException if this subscription is not embedded.

from

added in API level 22
public static SubscriptionManager from (Context context)

This method was deprecated in API level 28.
developers should always obtain references directly from Context.getSystemService(Class).

Parameters
context Context

Returns
SubscriptionManager

getAccessibleSubscriptionInfoList

added in API level 28
public List<SubscriptionInfo> getAccessibleSubscriptionInfoList ()

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

Only those subscriptions for which the calling app has carrier privileges per the subscription metadata, if any, will be included in the returned list.

The records will be sorted by SubscriptionInfo.getSimSlotIndex() then by SubscriptionInfo.getSubscriptionId().

Returns
List<SubscriptionInfo> Sorted list of the current embedded SubscriptionInfo records available on the device which are accessible to the caller.

getActiveSubscriptionInfo

added in API level 22
public SubscriptionInfo getActiveSubscriptionInfo (int subId)

Get the active SubscriptionInfo with the input subId.

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

Parameters
subId int: The unique SubscriptionInfo key in database.

Returns
SubscriptionInfo SubscriptionInfo, maybe null if its not active.

getActiveSubscriptionInfoCount

added in API level 22
public int getActiveSubscriptionInfoCount ()

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

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

getActiveSubscriptionInfoCountMax

added in API level 22
public int getActiveSubscriptionInfoCountMax ()

Returns
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
public SubscriptionInfo getActiveSubscriptionInfoForSimSlotIndex (int slotIndex)

Get the active SubscriptionInfo associated with the slotIndex

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

Parameters
slotIndex int: the slot which the subscription is inserted

Returns
SubscriptionInfo SubscriptionInfo, maybe null if its not active

getActiveSubscriptionInfoList

added in API level 22
public List<SubscriptionInfo> getActiveSubscriptionInfoList ()

Get the SubscriptionInfo(s) of the currently inserted 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.

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

getDefaultDataSubscriptionId

added in API level 24
public static int getDefaultDataSubscriptionId ()

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

Returns
int the default data subscription Id.

getDefaultSmsSubscriptionId

added in API level 24
public static int getDefaultSmsSubscriptionId ()

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

Returns
int the default SMS subscription Id.

getDefaultSubscriptionId

added in API level 24
public static int getDefaultSubscriptionId ()

Returns the system's default subscription id. For a voice capable device, it will return getDefaultVoiceSubscriptionId. For a data only device, it will return the getDefaultDataSubscriptionId. May return an INVALID_SUBSCRIPTION_ID on error.

Returns
int the "system" default subscription id.

getDefaultVoiceSubscriptionId

added in API level 24
public static int getDefaultVoiceSubscriptionId ()

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

Returns
int the default voice subscription Id.

getSubscriptionPlans

added in API level 28
public List<SubscriptionPlan> getSubscriptionPlans (int subId)

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

This method is only accessible to the following narrow set of apps:

Parameters
subId int: the subscriber this relationship applies to

Returns
List<SubscriptionPlan>

This value will never be null.

Throws
SecurityException if the caller doesn't meet the requirements outlined above.

isNetworkRoaming

added in API level 22
public boolean isNetworkRoaming (int subId)

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

Availability: Only when user registered to a network.

Parameters
subId int: The subscription ID

Returns
boolean true if the network for the subscription is roaming, false otherwise

removeOnSubscriptionsChangedListener

added in API level 22
public void removeOnSubscriptionsChangedListener (SubscriptionManager.OnSubscriptionsChangedListener listener)

Unregister the SubscriptionManager.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.

setSubscriptionOverrideCongested

added in API level 28
public void setSubscriptionOverrideCongested (int subId, 
                boolean overrideCongested, 
                long timeoutMillis)

Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered congested. This will cause the device to delay certain network requests when possible, such as developer jobs that are willing to run in a flexible time window.

This method is only accessible to the following narrow set of apps:

Parameters
subId int: the subscriber this override applies to.

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

timeoutMillis long: the timeout after which the requested override will be automatically cleared, or 0 to leave in the requested state until explicitly cleared, or the next reboot, whichever happens first.

Value is a non-negative duration in milliseconds.

Throws
SecurityException if the caller doesn't meet the requirements outlined above.

setSubscriptionOverrideUnmetered

added in API level 28
public void setSubscriptionOverrideUnmetered (int subId, 
                boolean overrideUnmetered, 
                long timeoutMillis)

Temporarily override the billing relationship plan between a carrier and a specific subscriber to be considered unmetered. This will be reflected to apps via NetworkCapabilities.NET_CAPABILITY_NOT_METERED.

This method is only accessible to the following narrow set of apps:

Parameters
subId int: the subscriber this override applies to.

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

timeoutMillis long: the timeout after which the requested override will be automatically cleared, or 0 to leave in the requested state until explicitly cleared, or the next reboot, whichever happens first.

Value is a non-negative duration in milliseconds.

Throws
SecurityException if the caller doesn't meet the requirements outlined above.

setSubscriptionPlans

added in API level 28
public void setSubscriptionPlans (int subId, 
                List<SubscriptionPlan> plans)

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

This method is only accessible to the following narrow set of apps:

Parameters
subId int: the subscriber this relationship applies to. An empty list may be sent to clear any existing plans.

plans List: the list of plans. The first plan is always the primary and most important plan. Any additional plans are secondary and may not be displayed or used by decision making logic.

This value must never be null.

Throws
SecurityException if the caller doesn't meet the requirements outlined above.