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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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 |
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 |
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)
This method was deprecated
in API level 36.
use |
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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
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 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.
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 |
|
onActionRequested
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
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)
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
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
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
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
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
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.
onDeviceTrusted
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
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
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. |