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

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 onDevicePresenceEvent(DevicePresenceEvent event)

Called by the system during device events.

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.

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.

onDevicePresenceEvent

public void onDevicePresenceEvent (DevicePresenceEvent event)

Called by the system during device events.
This method must be called from the main thread of your app.

Parameters
event DevicePresenceEvent: This value cannot be null.