CompanionDeviceManager
class CompanionDeviceManager
kotlin.Any | |
↳ | android.companion.CompanionDeviceManager |
Public interfaces for managing companion devices.
The interfaces in this class allow companion apps to associate(android.companion.AssociationRequest,java.util.concurrent.Executor,android.companion.CompanionDeviceManager.Callback)
discover and request device profiles} for companion devices, listen to device presence
, transfer system level
via the reported
and more.
Requires the
PackageManager#FEATURE_COMPANION_DEVICE_SETUP
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Summary
Nested classes | |
---|---|
abstract |
Callback for applications to receive updates about and the outcome of |
Constants | |
---|---|
static String |
Extra field name for the |
static String |
A device, returned in the activity result of the
|
static Int |
Used by |
static Int |
The result code to propagate back to the user activity, indicates if the association dialog is implicitly cancelled. |
static Int |
The result code to propagate back to the user activity, indicates the association dialog is dismissed if there's no device found after 20 seconds. |
static Int |
The result code to propagate back to the user activity, indicates the internal error in CompanionDeviceManager. |
static Int |
The result code to propagate back to the user activity, indicates the association is created successfully. |
static Int |
The result code to propagate back to the user activity, indicates the association dialog is explicitly declined by the users. |
Public methods | |
---|---|
Unit |
associate(request: AssociationRequest, callback: CompanionDeviceManager.Callback, handler: Handler?) Request to associate this app with a companion device. |
Unit |
associate(request: AssociationRequest, executor: Executor, callback: CompanionDeviceManager.Callback) Request to associate this app with a companion device. |
Unit |
attachSystemDataTransport(associationId: Int, in: InputStream, out: OutputStream) Attach a bidirectional communication stream to be used as a transport channel for transporting system data between associated devices. |
IntentSender? |
Cancel the current association activity. |
IntentSender? |
buildPermissionTransferUserConsentIntent(associationId: Int) Build a permission sync user consent dialog. |
Unit |
detachSystemDataTransport(associationId: Int) Detach the transport channel that's previously attached for the associated device. |
Unit |
disableSystemDataSyncForTypes(associationId: Int, flags: Int) Disable system data sync (it only supports call metadata sync for now). |
Unit |
disassociate(deviceMacAddress: String) Remove the association between this app and the device with the given mac address. |
Unit |
disassociate(associationId: Int) Remove an association. |
Unit |
enableSystemDataSyncForTypes(associationId: Int, flags: Int) Enable system data sync (it only supports call metadata sync for now). |
MutableList<String!> |
Calling this API requires a uses-feature |
MutableList<AssociationInfo!> |
Calling this API requires a uses-feature |
Boolean |
hasNotificationAccess(component: ComponentName!) Check whether the given component can access the notifications via a |
Boolean |
isPermissionTransferUserConsented(associationId: Int) Return the current state of consent for permission transfer for the association. |
Unit |
requestNotificationAccess(component: ComponentName!) Request notification access for the given component. |
Unit |
startObservingDevicePresence(deviceAddress: String) Register to receive callbacks whenever the associated device comes in and out of range. |
Unit |
startSystemDataTransfer(associationId: Int, executor: Executor, result: OutcomeReceiver<Void!, CompanionException!>) Start system data transfer which has been previously approved by the user. |
Unit |
stopObservingDevicePresence(deviceAddress: String) Unregister for receiving callbacks whenever the associated device comes in and out of range. |
Constants
EXTRA_ASSOCIATION
static val EXTRA_ASSOCIATION: String
Extra field name for the AssociationInfo
object, included into android.content.Intent
which application receive in Activity#onActivityResult(int, int, Intent)
after the application's AssociationRequest
was successfully processed and an association was created.
Value: "android.companion.extra.ASSOCIATION"
EXTRA_DEVICE
static valEXTRA_DEVICE: String
Deprecated: use AssociationInfo#getAssociatedDevice()
instead.
A device, returned in the activity result of the IntentSender
received in Callback#onDeviceFound
Type is:
- for classic Bluetooth -
android.bluetooth.BluetoothDevice
- for Bluetooth LE -
android.bluetooth.le.ScanResult
- for WiFi -
android.net.wifi.ScanResult
Value: "android.companion.extra.DEVICE"
FLAG_CALL_METADATA
static val FLAG_CALL_METADATA: Int
Used by enableSystemDataSyncForTypes(int,int)
}. Sync call metadata like muting, ending and silencing a call.
Value: 1
RESULT_CANCELED
static val RESULT_CANCELED: Int
The result code to propagate back to the user activity, indicates if the association dialog is implicitly cancelled. E.g. phone is locked, switch to another app or press outside the dialog.
Value: 0
RESULT_DISCOVERY_TIMEOUT
static val RESULT_DISCOVERY_TIMEOUT: Int
The result code to propagate back to the user activity, indicates the association dialog is dismissed if there's no device found after 20 seconds.
Value: 2
RESULT_INTERNAL_ERROR
static val RESULT_INTERNAL_ERROR: Int
The result code to propagate back to the user activity, indicates the internal error in CompanionDeviceManager.
Value: 3
RESULT_OK
static val RESULT_OK: Int
The result code to propagate back to the user activity, indicates the association is created successfully.
Value: -1
RESULT_USER_REJECTED
static val RESULT_USER_REJECTED: Int
The result code to propagate back to the user activity, indicates the association dialog is explicitly declined by the users.
Value: 1
Public methods
associate
fun associate(
request: AssociationRequest,
callback: CompanionDeviceManager.Callback,
handler: Handler?
): Unit
Request to associate this app with a companion device.
Note that before creating establishing association the system may need to show UI to collect user confirmation.
If the app needs to be excluded from battery optimizations (run in the background) or to have unrestricted data access (use data in the background) it should declare use of android.Manifest.permission#REQUEST_COMPANION_RUN_IN_BACKGROUND
and android.Manifest.permission#REQUEST_COMPANION_USE_DATA_IN_BACKGROUND
in its AndroidManifest.xml respectively. Note that these special capabilities have a negative effect on the device's battery and user's data usage, therefore you should request them when absolutely necessary.
Application can use getMyAssociations()
for retrieving the list of currently AssociationInfo
objects, that represent their existing associations. Applications can also use disassociate(int)
to remove an association, and are recommended to do when an association is no longer relevant to avoid unnecessary battery and/or data drain resulting from special privileges that the association provides
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Parameters | |
---|---|
request |
AssociationRequest: A request object that describes details of the request. This value cannot be null . |
callback |
CompanionDeviceManager.Callback: The callback used to notify application when the association is created. This value cannot be null . |
handler |
Handler?: The handler which will be used to invoke the callback. This value may be null . |
associate
fun associate(
request: AssociationRequest,
executor: Executor,
callback: CompanionDeviceManager.Callback
): Unit
Request to associate this app with a companion device.
Note that before creating establishing association the system may need to show UI to collect user confirmation.
If the app needs to be excluded from battery optimizations (run in the background) or to have unrestricted data access (use data in the background) it should declare use of android.Manifest.permission#REQUEST_COMPANION_RUN_IN_BACKGROUND
and android.Manifest.permission#REQUEST_COMPANION_USE_DATA_IN_BACKGROUND
in its AndroidManifest.xml respectively. Note that these special capabilities have a negative effect on the device's battery and user's data usage, therefore you should request them when absolutely necessary.
Application can use getMyAssociations()
for retrieving the list of currently AssociationInfo
objects, that represent their existing associations. Applications can also use disassociate(int)
to remove an association, and are recommended to do when an association is no longer relevant to avoid unnecessary battery and/or data drain resulting from special privileges that the association provides
Note that if you use this api to associate with a Bluetooth device, please make sure to cancel your own Bluetooth discovery before calling this api, otherwise the callback may fail to return the desired device.
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Parameters | |
---|---|
request |
AssociationRequest: A request object that describes details of the request. This value cannot be null . |
executor |
Executor: The executor which will be used to invoke the callback. This value cannot be null . |
callback |
CompanionDeviceManager.Callback: The callback used to notify application when the association is created. This value cannot be null . |
attachSystemDataTransport
fun attachSystemDataTransport(
associationId: Int,
in: InputStream,
out: OutputStream
): Unit
Attach a bidirectional communication stream to be used as a transport channel for transporting system data between associated devices.
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 . |
Exceptions | |
---|---|
android.companion.DeviceNotAssociatedException |
Thrown if the associationId was not previously associated with this app. |
buildAssociationCancellationIntent
fun buildAssociationCancellationIntent(): IntentSender?
Cancel the current association activity.
The app should launch the returned intentSender
by calling Activity#startIntentSenderForResult(IntentSender, int, Intent, int, int, int)
to cancel the current association activity
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Return | |
---|---|
IntentSender? |
An IntentSender that the app should use to launch in order to cancel the current association activity This value may be null . |
buildPermissionTransferUserConsentIntent
fun buildPermissionTransferUserConsentIntent(associationId: Int): IntentSender?
Build a permission sync user consent dialog.
Only the companion app which owns the association can call this method. Otherwise a null IntentSender will be returned from this method and an error will be logged. The app should launch the Activity
in the returned intentSender
IntentSender
by calling Activity#startIntentSenderForResult(IntentSender, int, Intent, int, int, int)
.
The permission transfer doesn't happen immediately after the call or when the user consents. The app needs to call attachSystemDataTransport(int,java.io.InputStream,java.io.OutputStream)
to attach a transport channel and startSystemDataTransfer(int,java.util.concurrent.Executor,android.os.OutcomeReceiver)
to trigger the system data transfer}.
Parameters | |
---|---|
associationId |
Int: The unique ID assigned to the association of the companion device recorded by CompanionDeviceManager |
Return | |
---|---|
IntentSender? |
An IntentSender that the app should use to launch the UI for the user to confirm the system data transfer request. |
detachSystemDataTransport
fun detachSystemDataTransport(associationId: Int): Unit
Detach the transport channel that's previously attached for the associated device. The system will stop transferring any system data when this method is called.
Requires android.Manifest.permission#DELIVER_COMPANION_MESSAGES
Parameters | |
---|---|
associationId |
Int: id of the associated device. |
Exceptions | |
---|---|
android.companion.DeviceNotAssociatedException |
Thrown if the associationId was not previously associated with this app. |
disableSystemDataSyncForTypes
fun disableSystemDataSyncForTypes(
associationId: Int,
flags: Int
): Unit
Disable system data sync (it only supports call metadata sync for now). By default all supported system data types are enabled.
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Parameters | |
---|---|
associationId |
Int: id of the device association. |
flags |
Int: system data types to be disabled. Value is either 0 or android.companion.CompanionDeviceManager#FLAG_CALL_METADATA |
disassociate
fundisassociate(deviceMacAddress: String): Unit
Deprecated: use disassociate(int)
Remove the association between this app and the device with the given mac address.
Any privileges provided via being associated with a given device will be revoked
Consider doing so when the association is no longer relevant to avoid unnecessary battery and/or data drain resulting from special privileges that the association provides
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Parameters | |
---|---|
deviceMacAddress |
String: the MAC address of device to disassociate from this app. Device address is case-sensitive in API level < 33. This value cannot be null . |
disassociate
fun disassociate(associationId: Int): Unit
Remove an association.
Any privileges provided via being associated with a given device will be revoked
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Parameters | |
---|---|
associationId |
Int: id of the association to be removed. |
enableSystemDataSyncForTypes
fun enableSystemDataSyncForTypes(
associationId: Int,
flags: Int
): Unit
Enable system data sync (it only supports call metadata sync for now). By default all supported system data types are enabled.
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Parameters | |
---|---|
associationId |
Int: id of the device association. |
flags |
Int: system data types to be enabled. Value is either 0 or android.companion.CompanionDeviceManager#FLAG_CALL_METADATA |
getAssociations
fungetAssociations(): MutableList<String!>
Deprecated: use getMyAssociations()
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Return | |
---|---|
MutableList<String!> |
a list of MAC addresses of devices that have been previously associated with the current app are managed by CompanionDeviceManager (ie. does not include devices managed by application itself even if they have a MAC address). This value cannot be null . |
getMyAssociations
fun getMyAssociations(): MutableList<AssociationInfo!>
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Return | |
---|---|
MutableList<AssociationInfo!> |
a list of associations that have been previously associated with the current app. This value cannot be null . |
hasNotificationAccess
funhasNotificationAccess(component: ComponentName!): Boolean
Deprecated: Use NotificationManager#isNotificationListenerAccessGranted(ComponentName)
instead.
Check whether the given component can access the notifications via a NotificationListenerService
Your app must have an association with a device before calling this API
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
Parameters | |
---|---|
component |
ComponentName!: the name of the component |
Return | |
---|---|
Boolean |
whether the given component has the notification listener permission |
isPermissionTransferUserConsented
fun isPermissionTransferUserConsented(associationId: Int): Boolean
Return the current state of consent for permission transfer for the association. True if the user has allowed permission transfer for the association, false otherwise.
Note: The initial user consent is collected via a permission transfer user consent dialog
. After the user has made their initial selection, they can toggle the permission transfer feature in the settings. This method always returns the state of the toggle setting.
Parameters | |
---|---|
associationId |
Int: The unique ID assigned to the association of the companion device recorded by CompanionDeviceManager |
Return | |
---|---|
Boolean |
True if the user has consented to the permission transfer, or false otherwise. |
Exceptions | |
---|---|
android.companion.DeviceNotAssociatedException |
Exception if the companion device is not associated with the user or the calling app. |
requestNotificationAccess
fun requestNotificationAccess(component: ComponentName!): Unit
Request notification access for the given component. The given component must follow the protocol specified in NotificationListenerService
Only components from the same package
as the calling app are allowed. Your app must have an association with a device before calling this API. Side-loaded apps must allow restricted settings before requesting notification access.
Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP
declaration in the manifest
startObservingDevicePresence
fun startObservingDevicePresence(deviceAddress: String): Unit
Register to receive callbacks whenever the associated device comes in and out of range.
The provided device must be #associate with the calling app before calling this method.
Caller must implement a single CompanionDeviceService
which will be bound to and receive callbacks to android.companion.CompanionDeviceService#onDeviceAppeared and android.companion.CompanionDeviceService#onDeviceDisappeared. The app doesn't need to remain running in order to receive its callbacks.
Calling app must declare uses-permission android.Manifest.permission#REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE
.
Calling app must check for feature presence of PackageManager#FEATURE_COMPANION_DEVICE_SETUP
before calling this API.
For Bluetooth LE devices, this is based on scanning for device with the given address. The system will scan for the device when Bluetooth is ON or Bluetooth scanning is ON.
For Bluetooth classic devices this is triggered when the device connects/disconnects. WiFi devices are not supported.
If a Bluetooth LE device wants to use a rotating mac address, it is recommended to use Resolvable Private Address, and ensure the device is bonded to the phone so that android OS is able to resolve the address.
Requires
android.Manifest.permission#REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE
Parameters | |
---|---|
deviceAddress |
String: a previously-associated companion device's address This value cannot be null . |
Exceptions | |
---|---|
android.companion.DeviceNotAssociatedException |
if the given device was not previously associated with this app. |
startSystemDataTransfer
fun startSystemDataTransfer(
associationId: Int,
executor: Executor,
result: OutcomeReceiver<Void!, CompanionException!>
): Unit
Start system data transfer which has been previously approved by the user.
Before calling this method, the app needs to make sure the transport channel is
, and the user consent dialog has prompted to
. The transfer will fail if the transport channel is disconnected or detached
during the transfer.
Parameters | |
---|---|
associationId |
Int: The unique ID assigned to the Association of the companion device recorded by CompanionDeviceManager |
executor |
Executor: The executor which will be used to invoke the result callback. This value cannot be null . |
result |
OutcomeReceiver<Void!, CompanionException!>: The callback to notify the app of the result of the system data transfer. This value cannot be null . |
Exceptions | |
---|---|
android.companion.DeviceNotAssociatedException |
Exception if the companion device is not associated |
stopObservingDevicePresence
fun stopObservingDevicePresence(deviceAddress: String): Unit
Unregister for receiving callbacks whenever the associated device comes in and out of range. The provided device must be #associate with the calling app before calling this method. Calling app must declare uses-permission android.Manifest.permission#REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE
. Calling app must check for feature presence of PackageManager#FEATURE_COMPANION_DEVICE_SETUP
before calling this API.
Requires android.Manifest.permission#REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE
Parameters | |
---|---|
deviceAddress |
String: a previously-associated companion device's address This value cannot be null . |
Exceptions | |
---|---|
android.companion.DeviceNotAssociatedException |
if the given device was not previously associated with this app. |