Added in API level 30

ControlsProviderService


abstract class ControlsProviderService : Service
kotlin.Any
   ↳ android.content.Context
   ↳ android.content.ContextWrapper
   ↳ android.app.Service
   ↳ android.service.controls.ControlsProviderService

Service implementation allowing applications to contribute controls to the System UI.

Summary

Constants
static Int

Controls are being shown on the device controls activity panel.

static Int

Controls are being shown as a dream, while the device is idle.

static String

Integer extra whose value specifies the surface which controls are being displayed on.

static String

Boolean extra containing the value of the setting allowing actions on a locked device.

static String

Manifest metadata to show a custom embedded activity as part of device controls.

static String

static String

Inherited constants
Public constructors

Public methods
abstract Flow.Publisher<Control!>

Return a valid Publisher for the given controlIds.

abstract Flow.Publisher<Control!>

Publisher for all available controls Retrieve all available controls.

open Flow.Publisher<Control!>?

(Optional) Publisher for suggested controls The service may be asked to provide a small number of recommended controls, in order to suggest some controls to the user for favoriting.

IBinder
onBind(intent: Intent)

Return the communication channel to the service.

Boolean
onUnbind(intent: Intent)

Called when all clients have disconnected from a particular interface published by the service.

abstract Unit
performControlAction(controlId: String, action: ControlAction, consumer: Consumer<Int!>)

The user has interacted with a Control.

open static Unit
requestAddControl(context: Context, componentName: ComponentName, control: Control)

Request SystemUI to prompt the user to add a control to favorites.

Inherited functions

Constants

CONTROLS_SURFACE_ACTIVITY_PANEL

Added in API level 35
static val CONTROLS_SURFACE_ACTIVITY_PANEL: Int

Controls are being shown on the device controls activity panel.

Value: 0

CONTROLS_SURFACE_DREAM

Added in API level 35
static val CONTROLS_SURFACE_DREAM: Int

Controls are being shown as a dream, while the device is idle.

Value: 1

EXTRA_CONTROLS_SURFACE

Added in API level 35
static val EXTRA_CONTROLS_SURFACE: String

Integer extra whose value specifies the surface which controls are being displayed on.

The possible values are:

This is passed with the intent when the panel specified by META_DATA_PANEL_ACTIVITY is launched.
Value: "android.service.controls.extra.CONTROLS_SURFACE"

EXTRA_LOCKSCREEN_ALLOW_TRIVIAL_CONTROLS

Added in API level 34
static val EXTRA_LOCKSCREEN_ALLOW_TRIVIAL_CONTROLS: String

Boolean extra containing the value of the setting allowing actions on a locked device. This corresponds to the setting that indicates whether the user has consented to allow actions on devices that declare Control#isAuthRequired() as false when the device is locked. This is passed with the intent when the panel specified by META_DATA_PANEL_ACTIVITY is launched.

Value: "android.service.controls.extra.LOCKSCREEN_ALLOW_TRIVIAL_CONTROLS"

META_DATA_PANEL_ACTIVITY

Added in API level 34
static val META_DATA_PANEL_ACTIVITY: String

Manifest metadata to show a custom embedded activity as part of device controls. The value of this metadata must be the ComponentName as a string of an activity in the same package that will be launched embedded in the device controls space. The activity must be exported, enabled and protected by Manifest.permission#BIND_CONTROLS. It is recommended that the activity is declared android:resizeableActivity="true".

Value: "android.service.controls.META_DATA_PANEL_ACTIVITY"

SERVICE_CONTROLS

Added in API level 30
static val SERVICE_CONTROLS: String
Value: "android.service.controls.ControlsProviderService"

TAG

Added in API level 30
static val TAG: String
Value: "ControlsProviderService"

Public constructors

ControlsProviderService

ControlsProviderService()

Public methods

createPublisherFor

Added in API level 30
abstract fun createPublisherFor(controlIds: MutableList<String!>): Flow.Publisher<Control!>

Return a valid Publisher for the given controlIds. This publisher will be asked to provide updates for the given list of controlIds as long as the Subscription is valid. Calls to Subscriber#onComplete will not be expected. Instead, wait for the call from Subscription#cancel to indicate that updates are no longer required. It is expected that controls provided by this publisher were created using Control.StatefulBuilder. By default, all controls require the device to be unlocked in order for the user to interact with it. This can be modified per Control by Control.StatefulBuilder#setAuthRequired.

Parameters
controlIds MutableList<String!>: This value cannot be null.
Return
Flow.Publisher<Control!> This value cannot be null.

createPublisherForAllAvailable

Added in API level 30
abstract fun createPublisherForAllAvailable(): Flow.Publisher<Control!>

Publisher for all available controls Retrieve all available controls. Use the stateless builder Control.StatelessBuilder to build each Control. Call Subscriber#onComplete when done loading all unique controls, or Subscriber#onError for error scenarios. Duplicate Controls will replace the original.

Return
Flow.Publisher<Control!> This value cannot be null.

createPublisherForSuggested

Added in API level 30
open fun createPublisherForSuggested(): Flow.Publisher<Control!>?

(Optional) Publisher for suggested controls The service may be asked to provide a small number of recommended controls, in order to suggest some controls to the user for favoriting. The controls shall be built using the stateless builder Control.StatelessBuilder. The total number of controls requested through Subscription#request will be restricted to a maximum. Within this larger limit, only 6 controls per structure will be loaded. Therefore, it is advisable to seed multiple structures if they exist. Any control sent over this limit will be discarded. Call Subscriber#onComplete when done, or Subscriber#onError for error scenarios.

Return
Flow.Publisher<Control!>? This value may be null.

onBind

Added in API level 30
fun onBind(intent: Intent): IBinder

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.

Parameters
intent Intent: This value cannot be null.
Return
IBinder This value cannot be null.

onUnbind

Added in API level 30
fun onUnbind(intent: Intent): Boolean

Called when all clients have disconnected from a particular interface published by the service. The default implementation does nothing and returns false.

Parameters
intent Intent: This value cannot be null.
Return
Boolean Return true if you would like to have the service's onRebind method later called when new clients bind to it.

performControlAction

Added in API level 30
abstract fun performControlAction(
    controlId: String,
    action: ControlAction,
    consumer: Consumer<Int!>
): Unit

The user has interacted with a Control. The action is dictated by the type of ControlAction that was sent. A response can be sent via Consumer#accept, with the Integer argument being one of the provided ControlAction response results. The Integer should indicate whether the action was received successfully, or if additional prompts should be presented to the user. Any visual control updates should be sent via the Publisher. By default, all invocations of this method will require the device be unlocked. This can be modified per Control by Control.StatefulBuilder#setAuthRequired.

Parameters
controlId String: This value cannot be null.
action ControlAction: This value cannot be null.
consumer Consumer<Int!>: This value cannot be null.

requestAddControl

Added in API level 30
open static fun requestAddControl(
    context: Context,
    componentName: ComponentName,
    control: Control
): Unit

Request SystemUI to prompt the user to add a control to favorites.
SystemUI may not honor this request in some cases, for example if the requested Control is already a favorite, or the requesting package is not currently in the foreground.

Parameters
context Context: A context This value cannot be null.
componentName ComponentName: Component name of the ControlsProviderService This value cannot be null.
control Control: A stateless control to show to the user This value cannot be null.