CompanionDeviceService


public abstract class CompanionDeviceService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.companion.CompanionDeviceService


A service that receives calls from the system with device events.

Companion applications must create a service that extends CompanionDeviceService, and declare it in their AndroidManifest.xml with the "android.permission.BIND_COMPANION_DEVICE_SERVICE" permission (see Manifest.permission.BIND_COMPANION_DEVICE_SERVICE), as well as add an intent filter for the "android.companion.CompanionDeviceService" action (see SERVICE_INTERFACE).

Following is an example of such declaration:

<service
       android:name=".CompanionService"
       android:label="@string/service_name"
       android:exported="true"
       android:permission="android.permission.BIND_COMPANION_DEVICE_SERVICE">
   <intent-filter>
       <action android:name="android.companion.CompanionDeviceService" />
   </intent-filter>
</service>

If the companion application has requested observing device presence (see CompanionDeviceManager.stopObservingDevicePresence(ObservingDevicePresenceRequest)) the system will bind the service when one of the DevicePresenceEvent.EVENT_BLE_APPEARED, DevicePresenceEvent.EVENT_BT_CONNECTED, DevicePresenceEvent.EVENT_SELF_MANAGED_APPEARED event is notified.

The system binding CompanionDeviceService elevates the priority of the process that the service is running in, and thus may prevent the Low-memory killer from killing the process at expense of other processes with lower priority.

It is possible for an application to declare multiple CompanionDeviceService-s. In such case, the system will bind all declared services, but will deliver service binding calls e.g. onDevicePresenceEvent(DevicePresenceEvent) and onActionRequested(AssociationInfo,ActionRequest) only to the "primary" service. Applications that declare multiple CompanionDeviceService-s should indicate the "primary" service using "android.companion.PROPERTY_PRIMARY_COMPANION_DEVICE_SERVICE" service level property.

<property
      android:name="android.companion.PROPERTY_PRIMARY_COMPANION_DEVICE_SERVICE"
      android:value="true" />

If the application declares multiple CompanionDeviceService-s, but does not indicate the "primary" one, the system will pick one of the declared services to use as "primary".

If the application declares multiple "primary" CompanionDeviceService-s, the system will pick single one of them to use as "primary".

Summary

Constants

String SERVICE_INTERFACE

An intent action for a service to be bound whenever this app's companion device(s) are nearby or self-managed device(s) report app appeared.

Inherited constants

Public constructors

CompanionDeviceService()

Public methods

final void attachSystemDataTransport(int associationId, InputStream in, OutputStream out)

Attach the given bidirectional communication streams to be used for transporting system data between associated devices.

final void detachSystemDataTransport(int associationId)

Detach any bidirectional communication streams previously configured through attachSystemDataTransport(int, InputStream, OutputStream).

void onActionRequested(AssociationInfo associationInfo, ActionRequest request)

Called by the system when it requests an action for an association managed by this app.

final IBinder onBind(Intent intent)

Return the communication channel to the service.

void onDeviceAppeared(AssociationInfo associationInfo)

This method was deprecated in API level 36. use onDevicePresenceEvent(DevicePresenceEvent)} instead.

void onDeviceAppeared(String address)

This method was deprecated in API level 33. please override onDeviceAppeared(AssociationInfo) instead.

void onDeviceDisappeared(String address)

This method was deprecated in API level 33. please override onDeviceDisappeared(AssociationInfo) instead.

void onDeviceDisappeared(AssociationInfo associationInfo)

This method was deprecated in API level 36. use onDevicePresenceEvent(DevicePresenceEvent)} instead.

void onDevicePresenceEvent(DevicePresenceEvent event)

Called by the system when an associated device's presence state changes.

void onDeviceTrustFailure(AssociationInfo associationInfo, int errorCode)

Called by the system when trust session establishment or trust pairing fails.

void onDeviceTrusted(AssociationInfo associationInfo)

Called by the system when the device becomes trusted following a successful trust pairing.

void onTrustPairingCanceledFromRemote(AssociationInfo associationInfo, IntentSender cancelIntentSender)

Called by the system when the trust pairing is canceled by the remote device.

void onTrustPairingResponsePending(AssociationInfo associationInfo, IntentSender intentSender)

Called by the system when a trust pairing response is pending user confirmation on the responder device.

Inherited methods

Constants

SERVICE_INTERFACE

Added in API level 31
public static final String SERVICE_INTERFACE

An intent action for a service to be bound whenever this app's companion device(s) are nearby or self-managed device(s) report app appeared.

The app will be kept bound by the system when one of the DevicePresenceEvent.EVENT_BLE_APPEARED, DevicePresenceEvent.EVENT_BT_CONNECTED, DevicePresenceEvent.EVENT_SELF_MANAGED_APPEARED event is notified. If the app is not running when one of the DevicePresenceEvent.EVENT_BLE_APPEARED, DevicePresenceEvent.EVENT_BT_CONNECTED, DevicePresenceEvent.EVENT_SELF_MANAGED_APPEARED event is notified, the app will be kept bound by the system.

Shortly, the service will be unbound if both DevicePresenceEvent.EVENT_BLE_DISAPPEARED and DevicePresenceEvent.EVENT_BT_DISCONNECTED are notified, or DevicePresenceEvent.EVENT_SELF_MANAGED_DISAPPEARED event is notified. The app will be eligible for cleanup, unless any other user-visible components are running.

If running in background is not essential for the devices that this app can manage, app should avoid declaring this service.

The service must also require permission Manifest.permission.BIND_COMPANION_DEVICE_SERVICE

Constant Value: "android.companion.CompanionDeviceService"

Public constructors

CompanionDeviceService

public CompanionDeviceService ()

Public methods

attachSystemDataTransport

Added in API level 34
public final void attachSystemDataTransport (int associationId, 
                InputStream in, 
                OutputStream out)

Attach the given bidirectional communication streams to be used for transporting system data between associated devices.

The companion service providing these streams is responsible for ensuring that all data is transported accurately and in-order between the two devices, including any fragmentation and re-assembly when carried over a size-limited transport.

As an example, it's valid to provide streams obtained from a BluetoothSocket to this method, since BluetoothSocket meets the API contract described above.

This method passes through to CompanionDeviceManager.attachSystemDataTransport(int,InputStream,OutputStream) for your convenience if you get callbacks in this class.
Requires Manifest.permission.DELIVER_COMPANION_MESSAGES

Parameters
associationId int: id of the associated device

in InputStream: already connected stream of data incoming from remote associated device.
This value cannot be null.

out OutputStream: already connected stream of data outgoing to remote associated device.
This value cannot be null.

Throws
DeviceNotAssociatedException

detachSystemDataTransport

Added in API level 34
public final void detachSystemDataTransport (int associationId)

Detach any bidirectional communication streams previously configured through attachSystemDataTransport(int, InputStream, OutputStream).

This method passes through to CompanionDeviceManager.detachSystemDataTransport(int) for your convenience if you get callbacks in this class.
Requires Manifest.permission.DELIVER_COMPANION_MESSAGES

Parameters
associationId int: id of the associated device

Throws
DeviceNotAssociatedException

onActionRequested

Added in API level 37
public void onActionRequested (AssociationInfo associationInfo, 
                ActionRequest request)

Called by the system when it requests an action for an association managed by this app.
This method must be called from the main thread of your app.

Parameters
associationInfo AssociationInfo: The association for which the action is requested.
This value cannot be null.

request ActionRequest: The specific request being requested.
This value cannot be null.

onBind

Added in API level 31
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 may be null.

onDeviceAppeared

Added in API level 33
Deprecated in API level 36
public void onDeviceAppeared (AssociationInfo associationInfo)

This method was deprecated in API level 36.
use onDevicePresenceEvent(DevicePresenceEvent)} instead.

Called by the system when an associated device is nearby or connected.
This method must be called from the main thread of your app.

Parameters
associationInfo AssociationInfo: A record for the companion device.
This value cannot be null.

onDeviceAppeared

Added in API level 31
Deprecated in API level 33
public void onDeviceAppeared (String address)

This method was deprecated in API level 33.
please override onDeviceAppeared(AssociationInfo) instead.

Called by system whenever a device associated with this app is available.
This method must be called from the main thread of your app.

Parameters
address String: the MAC address of the device.
This value cannot be null.

onDeviceDisappeared

Added in API level 31
Deprecated in API level 33
public void onDeviceDisappeared (String address)

This method was deprecated in API level 33.
please override onDeviceDisappeared(AssociationInfo) instead.

Called by system whenever a device associated with this app stops being available. Usually this means the device goes out of range or is turned off.
This method must be called from the main thread of your app.

Parameters
address String: the MAC address of the device.
This value cannot be null.

onDeviceDisappeared

Added in API level 33
Deprecated in API level 36
public void onDeviceDisappeared (AssociationInfo associationInfo)

This method was deprecated in API level 36.
use onDevicePresenceEvent(DevicePresenceEvent)} instead.

Called by the system when an associated device is out of range or disconnected.
This method must be called from the main thread of your app.

Parameters
associationInfo AssociationInfo: A record for the companion device.
This value cannot be null.

onDevicePresenceEvent

Added in API level 36
public void onDevicePresenceEvent (DevicePresenceEvent event)

Called by the system when an associated device's presence state changes.
This method must be called from the main thread of your app.

Parameters
event DevicePresenceEvent: This value cannot be null.

onDeviceTrustFailure

Added in version 37.2
public void onDeviceTrustFailure (AssociationInfo associationInfo, 
                int errorCode)

Called by the system when trust session establishment or trust pairing fails.
This method must be called from the main thread of your app.

Parameters
associationInfo AssociationInfo: The association for which trust establishment failed. Note that if trust resumption failed, this AssociationInfo will reflect that the device is no longer trusted (i.e. AssociationInfo.isTrusted() will return false).
This value cannot be null.

errorCode int: The error code indicating the reason for failure. One of: .
Value is one of the following:

onDeviceTrusted

Added in version 37.2
public void onDeviceTrusted (AssociationInfo associationInfo)

Called by the system when the device becomes trusted following a successful trust pairing.
This method must be called from the main thread of your app.

Parameters
associationInfo AssociationInfo: The association that is now trusted.
This value cannot be null.

onTrustPairingCanceledFromRemote

Added in version 37.2
public void onTrustPairingCanceledFromRemote (AssociationInfo associationInfo, 
                IntentSender cancelIntentSender)

Called by the system when the trust pairing is canceled by the remote device. The application is expected to launch the provided cancelIntentSender to cancel the trust pairing.
This method must be called from the main thread of your app.

Parameters
associationInfo AssociationInfo: The association for which trust pairing is canceled.
This value cannot be null.

cancelIntentSender IntentSender: An IntentSender which the application should use to launch in order to cancel the trust pairing dialog.
This value cannot be null.

onTrustPairingResponsePending

Added in version 37.2
public void onTrustPairingResponsePending (AssociationInfo associationInfo, 
                IntentSender intentSender)

Called by the system when a trust pairing response is pending user confirmation on the responder device. This can happen when the pairing was initiated by the remote device. The application is expected to launch the provided intentSender to display the user confirmation dialog.
This method must be called from the main thread of your app.

Parameters
associationInfo AssociationInfo: The association for which trust pairing is requested.
This value cannot be null.

intentSender IntentSender: An IntentSender which the application should use to launch the UI for the user to confirm the trust pairing.
This value cannot be null.