Added in API level 31

CompanionDeviceService

abstract class CompanionDeviceService : Service
kotlin.Any
   ↳ 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 android.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:

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

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.

<code>&lt;property
        android:name="android.companion.PROPERTY_PRIMARY_COMPANION_DEVICE_SERVICE"
        android:value="true" /&gt;
  </code>

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
static Int

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

static Int

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

static Int

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

static Int

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

static Int

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.

static Int

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.

static String

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

Inherited constants
Public constructors

Public methods
Unit

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

Unit

Detach any bidirectional communication streams previously configured through attachSystemDataTransport.

IBinder?
onBind(intent: Intent)

Return the communication channel to the service.

open Unit

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

open Unit

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

open Unit

Called by system whenever a device associated with this app stops being available.

open Unit

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

open Unit
onDeviceEvent(associationInfo: AssociationInfo, event: Int)

Called by the system during device events.

Inherited functions

Constants

DEVICE_EVENT_BLE_APPEARED

static val DEVICE_EVENT_BLE_APPEARED: Int

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

Value: 0

DEVICE_EVENT_BLE_DISAPPEARED

static val DEVICE_EVENT_BLE_DISAPPEARED: Int

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

Value: 1

DEVICE_EVENT_BT_CONNECTED

static val DEVICE_EVENT_BT_CONNECTED: Int

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

Value: 2

DEVICE_EVENT_BT_DISCONNECTED

static val DEVICE_EVENT_BT_DISCONNECTED: Int

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

Value: 3

DEVICE_EVENT_SELF_MANAGED_APPEARED

static val DEVICE_EVENT_SELF_MANAGED_APPEARED: Int

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.

Value: 4

DEVICE_EVENT_SELF_MANAGED_DISAPPEARED

static val DEVICE_EVENT_SELF_MANAGED_DISAPPEARED: Int

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.

Value: 5

SERVICE_INTERFACE

Added in API level 31
static val SERVICE_INTERFACE: String

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 android.Manifest.permission#BIND_COMPANION_DEVICE_SERVICE

Value: "android.companion.CompanionDeviceService"

Public constructors

CompanionDeviceService

CompanionDeviceService()

Public methods

attachSystemDataTransport

Added in API level 34
fun attachSystemDataTransport(
    associationId: Int,
    in: InputStream,
    out: OutputStream
): Unit

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

detachSystemDataTransport

Added in API level 34
fun detachSystemDataTransport(associationId: Int): Unit

Detach any bidirectional communication streams previously configured through attachSystemDataTransport.

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

Parameters
associationId Int: id of the associated device

onBind

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

onDeviceAppeared

Added in API level 31
Deprecated in API level 33
open fun onDeviceAppeared(address: String): Unit

Deprecated: 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.

onDeviceAppeared

Added in API level 33
open fun onDeviceAppeared(associationInfo: AssociationInfo): Unit

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.

onDeviceDisappeared

Added in API level 31
Deprecated in API level 33
open fun onDeviceDisappeared(address: String): Unit

Deprecated: 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
open fun onDeviceDisappeared(associationInfo: AssociationInfo): Unit

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

open fun onDeviceEvent(
    associationInfo: AssociationInfo,
    event: Int
): Unit

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 android.companion.CompanionDeviceService#DEVICE_EVENT_BLE_APPEARED, android.companion.CompanionDeviceService#DEVICE_EVENT_BLE_DISAPPEARED, android.companion.CompanionDeviceService#DEVICE_EVENT_BT_CONNECTED, android.companion.CompanionDeviceService#DEVICE_EVENT_BT_DISCONNECTED, android.companion.CompanionDeviceService#DEVICE_EVENT_SELF_MANAGED_APPEARED, or android.companion.CompanionDeviceService#DEVICE_EVENT_SELF_MANAGED_DISAPPEARED