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 |
int |
DEVICE_EVENT_BLE_DISAPPEARED
Companion app receives |
int |
DEVICE_EVENT_BT_CONNECTED
Companion app receives |
int |
DEVICE_EVENT_BT_DISCONNECTED
Companion app receives |
int |
DEVICE_EVENT_SELF_MANAGED_APPEARED
A companion app for a self-managed device will receive the callback
|
int |
DEVICE_EVENT_SELF_MANAGED_DISAPPEARED
A companion app for a self-managed device will receive the callback
|
String |
SERVICE_INTERFACE
An intent action for a service to be bound whenever this app's companion device(s) are nearby. |
Inherited constants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Service
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.Context
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks2
|
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 |
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 |
void
|
onDeviceDisappeared(String address)
This method was deprecated
in API level 33.
please override |
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Service
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.ContextWrapper
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.Context
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
java.lang.Object
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks
|
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
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
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
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
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
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
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
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
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 |