Added in API level 23

CarrierService


abstract class CarrierService : Service
kotlin.Any
   ↳ android.content.Context
   ↳ android.content.ContextWrapper
   ↳ android.app.Service
   ↳ android.service.carrier.CarrierService

A service that exposes carrier-specific functionality to the system.

To extend this class, you must declare the service in your manifest file to require the android.Manifest.permission#BIND_CARRIER_SERVICES permission and include an intent filter with the CARRIER_SERVICE_INTERFACE. If the service should have a long-lived binding, set android.service.carrier.LONG_LIVED_BINDING to true in the service's metadata. For example:

<code>&lt;service android:name=".MyCarrierService"
        android:label="@string/service_name"
        android:permission="android.permission.BIND_CARRIER_SERVICES"&gt;
   &lt;intent-filter&gt;
       &lt;action android:name="android.service.carrier.CarrierService" /&gt;
   &lt;/intent-filter&gt;
   &lt;meta-data android:name="android.service.carrier.LONG_LIVED_BINDING"
              android:value="true" /&gt;
  &lt;/service&gt;
  </code>

Summary

Constants
static String

Inherited constants
Public constructors

Public methods
Unit

Informs the system of an intentional upcoming carrier network change by a carrier app.

Unit
notifyCarrierNetworkChange(subscriptionId: Int, active: Boolean)

Informs the system of an intentional upcoming carrier network change by a carrier app on the given subscriptionId.

open IBinder?
onBind(intent: Intent!)

If overriding this method, call through to the super method for any unknown actions.

abstract PersistableBundle!

Override this method to set carrier configuration.

open PersistableBundle?
onLoadConfig(subscriptionId: Int, id: CarrierIdentifier?)

Override this method to set carrier configuration on the given subscriptionId.

Inherited functions

Constants

CARRIER_SERVICE_INTERFACE

Added in API level 23
static val CARRIER_SERVICE_INTERFACE: String
Value: "android.service.carrier.CarrierService"

Public constructors

CarrierService

Added in API level 23
CarrierService()

Public methods

notifyCarrierNetworkChange

Added in API level 23
Deprecated in API level 33
fun notifyCarrierNetworkChange(active: Boolean): Unit

Deprecated: use notifyCarrierNetworkChange(int,boolean) instead. With no parameter to specify the subscription, this API will apply to all subscriptions that the carrier app has carrier privileges on.

Informs the system of an intentional upcoming carrier network change by a carrier app. This call is optional and is only used to allow the system to provide alternative UI while telephony is performing an action that may result in intentional, temporary network lack of connectivity.

Based on the active parameter passed in, this method will either show or hide the alternative UI. There is no timeout associated with showing this UX, so a carrier app must be sure to call with active set to false sometime after calling with it set to true.

Requires Permission: calling app has carrier privileges.

Parameters
active Boolean: Whether the carrier network change is or shortly will be active. Set this value to true to begin showing alternative UI and false to stop.

notifyCarrierNetworkChange

Added in API level 33
fun notifyCarrierNetworkChange(
    subscriptionId: Int,
    active: Boolean
): Unit

Informs the system of an intentional upcoming carrier network change by a carrier app on the given subscriptionId. This call is optional and is only used to allow the system to provide alternative UI while telephony is performing an action that may result in intentional, temporary network lack of connectivity.

Based on the active parameter passed in, this method will either show or hide the alternative UI. There is no timeout associated with showing this UX, so a carrier app must be sure to call with active set to false sometime after calling with it set to true.

Requires Permission: calling app has carrier privileges.

Parameters
subscriptionId Int: the subscription of the carrier network that trigger the change.
active Boolean: whether the carrier network change is or shortly will be active. Set this value to true to begin showing alternative UI and false to stop.

onBind

Added in API level 23
open fun onBind(intent: Intent!): IBinder?

If overriding this method, call through to the super method for any unknown actions. Return the communication channel to the service. May return null if clients can not bind to the service. The returned android.os.IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.


If you override this method you must call through to the superclass implementation.
Parameters
intent Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Return
IBinder? Return an IBinder through which clients can call on to the service.

onLoadConfig

Added in API level 23
Deprecated in API level 33
abstract fun onLoadConfig(id: CarrierIdentifier!): PersistableBundle!

Deprecated: use onLoadConfig(int,android.service.carrier.CarrierIdentifier) instead.

Override this method to set carrier configuration.

This method will be called by telephony services to get carrier-specific configuration values. The returned config will be saved by the system until,

  1. The carrier app package is updated, or
  2. The carrier app requests a reload with notifyConfigChangedForSubId.
This method can be called after a SIM card loads, which may be before or after boot.

This method should not block for a long time. If expensive operations (e.g. network access) are required, this method can schedule the work and return null. Then, use notifyConfigChangedForSubId to trigger a reload when the config is ready.

Implementations should use the keys defined in CarrierConfigManager. Any configuration values not set in the returned PersistableBundle may be overridden by the system's default configuration service.

Parameters
id CarrierIdentifier!: contains details about the current carrier that can be used to decide what configuration values to return. Instead of using details like MCCMNC to decide current carrier, it also contains subscription carrier id android.telephony.TelephonyManager#getSimCarrierId(), a platform-wide unique identifier for each carrier, CarrierConfigService can directly use carrier id as the key to look up the carrier info.
Return
PersistableBundle! a PersistableBundle object containing the configuration or null if default values should be used.

onLoadConfig

Added in API level 33
open fun onLoadConfig(
    subscriptionId: Int,
    id: CarrierIdentifier?
): PersistableBundle?

Override this method to set carrier configuration on the given subscriptionId.

This method will be called by telephony services to get carrier-specific configuration values. The returned config will be saved by the system until,

  1. The carrier app package is updated, or
  2. The carrier app requests a reload with notifyConfigChangedForSubId.
This method can be called after a SIM card loads, which may be before or after boot.

This method should not block for a long time. If expensive operations (e.g. network access) are required, this method can schedule the work and return null. Then, use notifyConfigChangedForSubId to trigger a reload when the config is ready.

Implementations should use the keys defined in CarrierConfigManager. Any configuration values not set in the returned PersistableBundle may be overridden by the system's default configuration service.

By default, this method just calls onLoadConfig(android.service.carrier.CarrierIdentifier) with specified CarrierIdentifier id. Carrier app with target SDK android.os.Build.VERSION_CODES#TIRAMISU and above should override this method to load carrier configuration on the given subscriptionId. Note that onLoadConfig(android.service.carrier.CarrierIdentifier) is still called prior to android.os.Build.VERSION_CODES#TIRAMISU.

Parameters
subscriptionId Int: the subscription on which the carrier app should load configuration
id CarrierIdentifier?: contains details about the current carrier that can be used to decide what configuration values to return. Instead of using details like MCCMNC to decide current carrier, it also contains subscription carrier id android.telephony.TelephonyManager#getSimCarrierId(), a platform-wide unique identifier for each carrier, CarrierConfigService can directly use carrier id as the key to look up the carrier info. This value may be null.
Return
PersistableBundle? a PersistableBundle object containing the configuration or null if default values should be used.