ControlsProviderService


public abstract class ControlsProviderService
extends Service

java.lang.Object
   ↳ 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

int CONTROLS_SURFACE_ACTIVITY_PANEL

Controls are being shown on the device controls activity panel.

int CONTROLS_SURFACE_DREAM

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

String EXTRA_CONTROLS_SURFACE

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

String EXTRA_LOCKSCREEN_ALLOW_TRIVIAL_CONTROLS

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

String META_DATA_PANEL_ACTIVITY

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

String SERVICE_CONTROLS

String TAG

Inherited constants

Public constructors

ControlsProviderService()

Public methods

abstract Publisher<Control> createPublisherFor(List<String> controlIds)

Return a valid Publisher for the given controlIds.

abstract Publisher<Control> createPublisherForAllAvailable()

Publisher for all available controls Retrieve all available controls.

Publisher<Control> createPublisherForSuggested()

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

final IBinder onBind(Intent intent)

Return the communication channel to the service.

final boolean onUnbind(Intent intent)

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

abstract void performControlAction(String controlId, ControlAction action, Consumer<Integer> consumer)

The user has interacted with a Control.

static void requestAddControl(Context context, ComponentName componentName, Control control)

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

Inherited methods

Constants

CONTROLS_SURFACE_ACTIVITY_PANEL

Added in API level 35
public static final int CONTROLS_SURFACE_ACTIVITY_PANEL

Controls are being shown on the device controls activity panel.

Constant Value: 0 (0x00000000)

CONTROLS_SURFACE_DREAM

Added in API level 35
public static final int CONTROLS_SURFACE_DREAM

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

Constant Value: 1 (0x00000001)

EXTRA_CONTROLS_SURFACE

Added in API level 35
public static final String EXTRA_CONTROLS_SURFACE

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.

Constant Value: "android.service.controls.extra.CONTROLS_SURFACE"

EXTRA_LOCKSCREEN_ALLOW_TRIVIAL_CONTROLS

Added in API level 34
public static final String EXTRA_LOCKSCREEN_ALLOW_TRIVIAL_CONTROLS

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.

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

META_DATA_PANEL_ACTIVITY

Added in API level 34
public static final String META_DATA_PANEL_ACTIVITY

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".

Constant Value: "android.service.controls.META_DATA_PANEL_ACTIVITY"

SERVICE_CONTROLS

Added in API level 30
public static final String SERVICE_CONTROLS

Constant Value: "android.service.controls.ControlsProviderService"

TAG

Added in API level 30
public static final String TAG

Constant Value: "ControlsProviderService"

Public constructors

ControlsProviderService

public ControlsProviderService ()

Public methods

createPublisherFor

Added in API level 30
public abstract Publisher<Control> createPublisherFor (List<String> controlIds)

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 List: This value cannot be null.

Returns
Publisher<Control> This value cannot be null.

createPublisherForAllAvailable

Added in API level 30
public abstract Publisher<Control> createPublisherForAllAvailable ()

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.

Returns
Publisher<Control> This value cannot be null.

createPublisherForSuggested

Added in API level 30
public Publisher<Control> createPublisherForSuggested ()

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

Returns
Publisher<Control> This value may be null.

onBind

Added in API level 30
public final IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned 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.

Returns
IBinder This value cannot be null.

onUnbind

Added in API level 30
public final boolean onUnbind (Intent intent)

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.

Returns
boolean Return true if you would like to have the service's onRebind(Intent) method later called when new clients bind to it.

performControlAction

Added in API level 30
public abstract void performControlAction (String controlId, 
                ControlAction action, 
                Consumer<Integer> consumer)

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: This value cannot be null.

requestAddControl

Added in API level 30
public static void requestAddControl (Context context, 
                ComponentName componentName, 
                Control control)

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.