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#startObservingDevicePresence(String)) the system will bind the service when it detects the device nearby (for BLE devices) or when the device is connected (for Bluetooth devices).

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 onDeviceAppeared(android.companion.AssociationInfo) and onDeviceDisappeared(android.companion.AssociationInfo) only to one "primary" services. 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

int DEVICE_EVENT_BLE_APPEARED

Companion app receives onDeviceEvent(android.companion.AssociationInfo, int) callback with this event if the device comes into BLE range.

int DEVICE_EVENT_BLE_DISAPPEARED

Companion app receives onDeviceEvent(android.companion.AssociationInfo, int) callback with this event if the device is no longer in BLE range.

int DEVICE_EVENT_BT_CONNECTED

Companion app receives onDeviceEvent(android.companion.AssociationInfo, int) callback with this event when the bluetooth device is connected.

int DEVICE_EVENT_BT_DISCONNECTED

Companion app receives onDeviceEvent(android.companion.AssociationInfo, int) callback with this event if the bluetooth device is disconnected.

int DEVICE_EVENT_SELF_MANAGED_APPEARED

A companion app for a self-managed device will receive the callback onDeviceEvent(android.companion.AssociationInfo, int) if it reports that a device has appeared on its own.

int DEVICE_EVENT_SELF_MANAGED_DISAPPEARED

A companion app for a self-managed device will receive the callback onDeviceEvent(android.companion.AssociationInfo, int) if it reports that a device has disappeared on its own.

String SERVICE_INTERFACE

An intent action for a service to be bound whenever this app's companion device(s) are nearby.

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

final IBinder onBind(Intent intent)

Return the communication channel to the service.

void onDeviceAppeared(AssociationInfo associationInfo)

Called by system whenever a device associated with this app is connected.

void onDeviceAppeared(String address)

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

void onDeviceDisappeared(String address)

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

void onDeviceDisappeared(AssociationInfo associationInfo)

Called by system whenever a device associated with this app is disconnected.

void onDeviceEvent(AssociationInfo associationInfo, int event)

Called by the system during device events.

Inherited methods

Constants

DEVICE_EVENT_BLE_APPEARED

public static final int DEVICE_EVENT_BLE_APPEARED

Companion app receives onDeviceEvent(android.companion.AssociationInfo, int) callback with this event if the device comes into BLE range.

Constant Value: 0 (0x00000000)

DEVICE_EVENT_BLE_DISAPPEARED

public static final int DEVICE_EVENT_BLE_DISAPPEARED

Companion app receives onDeviceEvent(android.companion.AssociationInfo, int) callback with this event if the device is no longer in BLE range.

Constant Value: 1 (0x00000001)

DEVICE_EVENT_BT_CONNECTED

public static final int DEVICE_EVENT_BT_CONNECTED

Companion app receives onDeviceEvent(android.companion.AssociationInfo, int) callback with this event when the bluetooth device is connected.

Constant Value: 2 (0x00000002)

DEVICE_EVENT_BT_DISCONNECTED

public static final int DEVICE_EVENT_BT_DISCONNECTED

Companion app receives onDeviceEvent(android.companion.AssociationInfo, int) callback with this event if the bluetooth device is disconnected.

Constant Value: 3 (0x00000003)

DEVICE_EVENT_SELF_MANAGED_APPEARED

public static final int DEVICE_EVENT_SELF_MANAGED_APPEARED

A companion app for a self-managed device will receive the callback onDeviceEvent(android.companion.AssociationInfo, int) if it reports that a device has appeared on its own.

Constant Value: 4 (0x00000004)

DEVICE_EVENT_SELF_MANAGED_DISAPPEARED

public static final int DEVICE_EVENT_SELF_MANAGED_DISAPPEARED

A companion app for a self-managed device will receive the callback onDeviceEvent(android.companion.AssociationInfo, int) if it reports that a device has disappeared on its own.

Constant Value: 5 (0x00000005)

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.

The app will be kept alive for as long as the device is nearby or companion app reports appeared. If the app is not running at the time device gets connected, the app will be woken up.

Shortly after the device goes out of range or the companion app reports disappeared, the service will be unbound, and 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

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
public void onDeviceAppeared (AssociationInfo associationInfo)

Called by system whenever a device associated with this app is 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(android.companion.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(android.companion.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
public void onDeviceDisappeared (AssociationInfo associationInfo)

Called by system whenever a device associated with this app is 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.

onDeviceEvent

public void onDeviceEvent (AssociationInfo associationInfo, 
                int event)

Called by the system during device events.

E.g. Event DEVICE_EVENT_BLE_APPEARED will be called when the associated companion device comes into BLE range.

Event DEVICE_EVENT_BLE_DISAPPEARED will be called when the associated companion device is no longer in BLE range.

Event DEVICE_EVENT_BT_CONNECTED will be called when the associated companion device is connected.

Event DEVICE_EVENT_BT_DISCONNECTED will be called when the associated companion device is disconnected. Note that app must receive DEVICE_EVENT_BLE_APPEARED first before DEVICE_EVENT_BLE_DISAPPEARED and DEVICE_EVENT_BT_CONNECTED before DEVICE_EVENT_BT_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.

event int: Associated companion device's event. Value is DEVICE_EVENT_BLE_APPEARED, DEVICE_EVENT_BLE_DISAPPEARED, DEVICE_EVENT_BT_CONNECTED, DEVICE_EVENT_BT_DISCONNECTED, DEVICE_EVENT_SELF_MANAGED_APPEARED, or DEVICE_EVENT_SELF_MANAGED_DISAPPEARED