CompanionDeviceManager  |  API reference  |  Android Developers (original) (raw)

public final class CompanionDeviceManager
extends [Object](/reference/java/lang/Object) ``

Public interfaces for managing companion devices.

The interfaces in this class allow companion apps to[associate(AssociationRequest,Executor,Callback)](/reference/android/companion/CompanionDeviceManager#associate%28android.companion.AssociationRequest,%20java.util.concurrent.Executor,%20android.companion.CompanionDeviceManager.Callback%29) discover and request device profiles} for companion devices, [listen to device presence events](/reference/android/companion/CompanionDeviceManager#startObservingDevicePresence%28java.lang.String%29), [transfer system level data](/reference/android/companion/CompanionDeviceManager#startSystemDataTransfer%28int,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Void,android.companion.CompanionException>%29) via [the reported channel](/reference/android/companion/CompanionDeviceManager#attachSystemDataTransport%28int,%20java.io.InputStream,%20java.io.OutputStream%29) and more.

Developer Guides

For more information about managing companion devices, read the Companion Device Pairing developer guide.

.
Requires the [PackageManager#FEATURE_COMPANION_DEVICE_SETUP](/reference/android/content/pm/PackageManager#FEATURE%5FCOMPANION%5FDEVICE%5FSETUP) feature which can be detected using [PackageManager.hasSystemFeature(String)](/reference/android/content/pm/PackageManager#hasSystemFeature%28java.lang.String%29).

Summary

Nested classes
class CompanionDeviceManager.Callback Callback for applications to receive updates about and the outcome ofAssociationRequest issued via associate() call.
Constants
String EXTRA_ASSOCIATION Extra field name for the AssociationInfo object, included intoIntent which application receive inActivity.onActivityResult(int,int,Intent) after the application'sAssociationRequest was successfully processed and an association was created.
String EXTRA_DEVICE This constant was deprecated in API level 33. use AssociationInfo.getAssociatedDevice() instead.
int FLAG_AIRPLANE_MODE Used by enableSystemDataSyncForTypes(int, int)}.
int FLAG_CALL_METADATA Used by enableSystemDataSyncForTypes(int, int)}.
int FLAG_TASK_CONTINUITY Used by enableSystemDataSyncForTypes(int, int)}.
int FLAG_UNIVERSAL_MODES Used by enableSystemDataSyncForTypes(int, int)}.
int RESULT_CANCELED The result code to propagate back to the user activity, indicates if the association dialog is implicitly cancelled.
int RESULT_DISCOVERY_TIMEOUT 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.
int RESULT_INTERNAL_ERROR The result code to propagate back to the user activity, indicates the internal error in CompanionDeviceManager.
int RESULT_OK The result code to propagate back to the user activity, indicates the association is created successfully.
int RESULT_SECURITY_ERROR The result code to propagate back to the user activity andCallback.onFailure(int,CharSequence), indicates app is not allow to create the association due to the security issue.
int RESULT_USER_REJECTED The result code to propagate back to the user activity, indicates the association dialog is explicitly declined by the users.
Public methods
void associate(AssociationRequest request, Executor executor, CompanionDeviceManager.Callback callback) Request to associate this app with a companion device.
void associate(AssociationRequest request, CompanionDeviceManager.Callback callback, Handler handler) Request to associate this app with a companion device.
void attachSystemDataTransport(int associationId, InputStream in, OutputStream out) Attach a bidirectional communication stream to be used as a transport channel for transporting system data between associated devices.
IntentSender buildAssociationCancellationIntent() Cancel the current association activity.
IntentSender buildPermissionTransferUserConsentIntent(int associationId) Build a permission sync user consent dialog.
DeviceId createAndSetDeviceId(int associationId, DeviceId deviceId) Returns a new DeviceId which can be passed to device manufacturers' apps, allowing them to fetch AssociationInfo or observe device presence for this associated device.
void detachSystemDataTransport(int associationId) Detach the transport channel that's previously attached for the associated device.
void disableSystemDataSyncForTypes(int associationId, int flags) Disable system data sync for an associated device.
void disassociate(int associationId) Remove an association.
void disassociate(String deviceMacAddress) This method was deprecated in API level 33. use disassociate(int)
void enableSystemDataSyncForTypes(int associationId, int flags) Enable system data sync for an associated device.
List<String> getAssociations() This method was deprecated in API level 33. use getMyAssociations()
List<AssociationInfo> getMyAssociations() Calling this API requires a uses-featurePackageManager.FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest
boolean hasNotificationAccess(ComponentName component) This method was deprecated in API level 33. UseNotificationManager.isNotificationListenerAccessGranted(ComponentName) instead.
boolean isPermissionTransferUserConsented(int associationId) Return the current state of consent for permission transfer for the association.
boolean isSystemDataTransportAttached(int associationId) Checks if a transport is currently attached for a given association id.
void notifyActionResult(int associationId, ActionResult result) Allows a companion app to report the result of an action that was requested by the system.
boolean removeBond(int associationId) Remove bonding between this device and an associated companion device.
void requestNotificationAccess(ComponentName component) Request notification access for the given component.
void setDeviceId(int associationId, DeviceId deviceId) This method was deprecated in API level 36.1. use createAndSetDeviceId(int,DeviceId) instead.
void startObservingDevicePresence(ObservingDevicePresenceRequest request) Register to receive callbacks whenever the associated device's presence changes.
void startObservingDevicePresence(String deviceAddress) This method was deprecated in API level 36. use startObservingDevicePresence(ObservingDevicePresenceRequest) instead.
void startSystemDataTransfer(int associationId, Executor executor, OutcomeReceiver<Void, CompanionException> result) Start system data transfer which has been previously approved by the user.
void stopObservingDevicePresence(String deviceAddress) This method was deprecated in API level 36. use stopObservingDevicePresence(ObservingDevicePresenceRequest) instead.
void stopObservingDevicePresence(ObservingDevicePresenceRequest request) Unregister for receiving callbacks whenever the associated device comes in and out of range.
Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. finalClass<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

FLAG_AIRPLANE_MODE

public static final int FLAG_AIRPLANE_MODE

Used by [enableSystemDataSyncForTypes(int, int)](/reference/android/companion/CompanionDeviceManager#enableSystemDataSyncForTypes%28int,%20int%29)}. Synchronize airplane mode state across devices. Disabled by default.

Constant Value: 16 (0x00000010)

FLAG_CALL_METADATA

public static final int FLAG_CALL_METADATA

Used by [enableSystemDataSyncForTypes(int, int)](/reference/android/companion/CompanionDeviceManager#enableSystemDataSyncForTypes%28int,%20int%29)}. Sync call metadata like muting, ending and silencing a call. Enabled by default.

Constant Value: 1 (0x00000001)

FLAG_TASK_CONTINUITY

public static final int FLAG_TASK_CONTINUITY

Used by [enableSystemDataSyncForTypes(int, int)](/reference/android/companion/CompanionDeviceManager#enableSystemDataSyncForTypes%28int,%20int%29)}. Synchronize task continuity data like open tasks, and enable this transport for Handoff. Disabled by default.

Constant Value: 2 (0x00000002)

FLAG_UNIVERSAL_MODES

public static final int FLAG_UNIVERSAL_MODES

Used by [enableSystemDataSyncForTypes(int, int)](/reference/android/companion/CompanionDeviceManager#enableSystemDataSyncForTypes%28int,%20int%29)}. Synchronize user settings like contextual modes across devices. Disabled by default.

Constant Value: 4 (0x00000004)

RESULT_CANCELED

public static final int RESULT_CANCELED

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.

Constant Value: 0 (0x00000000)

RESULT_DISCOVERY_TIMEOUT

public static final int RESULT_DISCOVERY_TIMEOUT

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.

Constant Value: 2 (0x00000002)

RESULT_INTERNAL_ERROR

public static final int RESULT_INTERNAL_ERROR

The result code to propagate back to the user activity, indicates the internal error in CompanionDeviceManager.

Constant Value: 3 (0x00000003)

RESULT_OK

public static final int RESULT_OK

The result code to propagate back to the user activity, indicates the association is created successfully.

Constant Value: -1 (0xffffffff)

RESULT_SECURITY_ERROR

public static final int RESULT_SECURITY_ERROR

The result code to propagate back to the user activity and[Callback.onFailure(int,CharSequence)](/reference/android/companion/CompanionDeviceManager.Callback#onFailure%28int,%20java.lang.CharSequence%29), indicates app is not allow to create the association due to the security issue. E.g. There are missing necessary permissions when creating association.

Constant Value: 4 (0x00000004)

RESULT_USER_REJECTED

public static final int RESULT_USER_REJECTED

The result code to propagate back to the user activity, indicates the association dialog is explicitly declined by the users.

Constant Value: 1 (0x00000001)

Public methods

associate

public void associate (AssociationRequest request, Executor executor, CompanionDeviceManager.Callback callback)

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[Manifest.permission.REQUEST_COMPANION_RUN_IN_BACKGROUND](/reference/android/Manifest.permission#REQUEST%5FCOMPANION%5FRUN%5FIN%5FBACKGROUND) and[Manifest.permission.REQUEST_COMPANION_USE_DATA_IN_BACKGROUND](/reference/android/Manifest.permission#REQUEST%5FCOMPANION%5FUSE%5FDATA%5FIN%5FBACKGROUND) 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()](/reference/android/companion/CompanionDeviceManager#getMyAssociations%28%29) for retrieving the list of currently[AssociationInfo](/reference/android/companion/AssociationInfo) objects, that represent their existing associations. Applications can also use [disassociate(int)](/reference/android/companion/CompanionDeviceManager#disassociate%28int%29) 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](/reference/android/content/pm/PackageManager#FEATURE%5FCOMPANION%5FDEVICE%5FSETUP) 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.

See also:

buildPermissionTransferUserConsentIntent

public IntentSender buildPermissionTransferUserConsentIntent (int associationId)

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](/reference/android/app/Activity) in the returned intentSender [IntentSender](/reference/android/content/IntentSender) by calling[Activity.startIntentSenderForResult(IntentSender,int,Intent,int,int,int)](/reference/android/app/Activity#startIntentSenderForResult%28android.content.IntentSender,%20int,%20android.content.Intent,%20int,%20int,%20int%29).

The permission transfer doesn't happen immediately after the call or when the user consents. The app needs to call[attachSystemDataTransport(int,InputStream,OutputStream)](/reference/android/companion/CompanionDeviceManager#attachSystemDataTransport%28int,%20java.io.InputStream,%20java.io.OutputStream%29) to attach a transport channel and[startSystemDataTransfer(int,Executor,OutcomeReceiver)](/reference/android/companion/CompanionDeviceManager#startSystemDataTransfer%28int,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Void,android.companion.CompanionException>%29) to trigger the system data transfer}.

Parameters
associationId int: The unique ID assigned to the association of the companion device recorded by CompanionDeviceManager
Returns
IntentSender An IntentSender that the app should use to launch the UI for the user to confirm the system data transfer request.
Throws
DeviceNotAssociatedException

See also:

createAndSetDeviceId

public DeviceId createAndSetDeviceId (int associationId, DeviceId deviceId)

Returns a new [DeviceId](/reference/android/companion/DeviceId) which can be passed to device manufacturers' apps, allowing them to fetch [AssociationInfo](/reference/android/companion/AssociationInfo) or observe device presence for this associated device. This method creates a new object and does not mutate any existing[DeviceId](/reference/android/companion/DeviceId).

The system will generate and assign a new, random 128-bit key to this returned[DeviceId](/reference/android/companion/DeviceId). Each call to this method generates a new key, any previously associated key will be obsoleted. Therefore, the returned [DeviceId](/reference/android/companion/DeviceId) is the one that contains the newly assigned key and should be used for subsequent operations.

This device id also helps the system uniquely identify your device for efficient device management and prevents duplicate entries.

WARNING: Do not pass the returned DeviceId to apps you do not trust.

Parameters
associationId int: The unique AssociationInfo.getId assigned to the Association of the companion device recorded by CompanionDeviceManager.
deviceId DeviceId: to be used as device identifier to represent the associated device. This value may be null.
Returns
DeviceId This value may be null.

detachSystemDataTransport

public void detachSystemDataTransport (int associationId)

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 [Manifest.permission.DELIVER_COMPANION_MESSAGES](/reference/android/Manifest.permission#DELIVER%5FCOMPANION%5FMESSAGES)

Parameters
associationId int: id of the associated device.
Throws
DeviceNotAssociatedException Thrown if the associationId was not previously associated with this app.

disassociate

public void disassociate (int associationId)

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](/reference/android/content/pm/PackageManager#FEATURE%5FCOMPANION%5FDEVICE%5FSETUP) declaration in the manifest

Parameters
associationId int: id of the association to be removed.

disassociate

public void disassociate (String deviceMacAddress)

This method was deprecated in API level 33.
use [disassociate(int)](/reference/android/companion/CompanionDeviceManager#disassociate%28int%29)

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](/reference/android/content/pm/PackageManager#FEATURE%5FCOMPANION%5FDEVICE%5FSETUP) 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.

getAssociations

public List<String> getAssociations ()

This method was deprecated in API level 33.
use [getMyAssociations()](/reference/android/companion/CompanionDeviceManager#getMyAssociations%28%29)

Calling this API requires a uses-feature[PackageManager.FEATURE_COMPANION_DEVICE_SETUP](/reference/android/content/pm/PackageManager#FEATURE%5FCOMPANION%5FDEVICE%5FSETUP) declaration in the manifest

Returns
List<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.

isPermissionTransferUserConsented

public boolean isPermissionTransferUserConsented (int associationId)

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](/reference/android/companion/CompanionDeviceManager#buildPermissionTransferUserConsentIntent%28int%29). 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
Returns
boolean True if the user has consented to the permission transfer, or false otherwise.
Throws
DeviceNotAssociatedException Exception if the companion device is not associated with the user or the calling app.

isSystemDataTransportAttached

public boolean isSystemDataTransportAttached (int associationId)

Checks if a transport is currently attached for a given association id.

A transport is considered attached if[attachSystemDataTransport(int,InputStream,OutputStream)](/reference/android/companion/CompanionDeviceManager#attachSystemDataTransport%28int,%20java.io.InputStream,%20java.io.OutputStream%29) has been successfully called for the given associationId, and[detachSystemDataTransport(int)](/reference/android/companion/CompanionDeviceManager#detachSystemDataTransport%28int%29) has not yet been called.

This is useful for determining if the system is ready to handle data transfers before calling [startSystemDataTransfer(int,Executor,OutcomeReceiver)](/reference/android/companion/CompanionDeviceManager#startSystemDataTransfer%28int,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver<java.lang.Void,android.companion.CompanionException>%29).

The caller must meet one of the following requirements:

Parameters
associationId int: The unique id of the device association
Returns
boolean true if a system data transport is attached for the given association id,false otherwise.

See also:

removeBond

public boolean removeBond (int associationId)

Remove bonding between this device and an associated companion device.

This is an asynchronous call, it will return immediately. Register for [BluetoothDevice.ACTION_BOND_STATE_CHANGED](/reference/android/bluetooth/BluetoothDevice#ACTION%5FBOND%5FSTATE%5FCHANGED) intents to be notified when the bond removal process completes, and its result.

This API should be used to remove a bluetooth bond that was created either by using [BluetoothDevice.createBond()](/reference/android/bluetooth/BluetoothDevice#createBond%28%29) or by a direct user action. The association must already exist with this device before calling this method, but this may be done retroactively to remove a bond that was created outside of the CompanionDeviceManager.
Requires [Manifest.permission.BLUETOOTH_CONNECT](/reference/android/Manifest.permission#BLUETOOTH%5FCONNECT)

Parameters
associationId int: an already-associated companion device to remove bond from
Returns
boolean false on immediate error, true if bond removal process will begin

requestNotificationAccess

public void requestNotificationAccess (ComponentName component)

Request notification access for the given component. The given component must follow the protocol specified in [NotificationListenerService](/reference/android/service/notification/NotificationListenerService) Only components from the same [package](/reference/android/content/ComponentName#getPackageName%28%29) 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](/reference/android/content/pm/PackageManager#FEATURE%5FCOMPANION%5FDEVICE%5FSETUP) declaration in the manifest

Parameters
component ComponentName

setDeviceId

public void setDeviceId (int associationId, DeviceId deviceId)

This method was deprecated in API level 36.1.
use [createAndSetDeviceId(int,DeviceId)](/reference/android/companion/CompanionDeviceManager#createAndSetDeviceId%28int,%20android.companion.DeviceId%29) instead.

Sets the [deviceId](/reference/android/companion/DeviceId) for this association.

This device id helps the system uniquely identify your device for efficient device management and prevents duplicate entries.

Parameters
associationId int: The unique ID assigned to the Association of the companion device recorded by CompanionDeviceManager.
deviceId DeviceId: to be used as device identifier to represent the associated device. This value may be null.

startSystemDataTransfer

public void startSystemDataTransfer (int associationId, Executor executor, OutcomeReceiver<Void, CompanionException> result)

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 attached](/reference/android/companion/CompanionDeviceManager#attachSystemDataTransport%28int,%20java.io.InputStream,%20java.io.OutputStream%29), and[the user consent dialog has prompted to the user](/reference/android/companion/CompanionDeviceManager#buildPermissionTransferUserConsentIntent%28int%29). The transfer will fail if the transport channel is disconnected or[detached](/reference/android/companion/CompanionDeviceManager#detachSystemDataTransport%28int%29) 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: The callback to notify the app of the result of the system data transfer. This value cannot be null.
Throws
DeviceNotAssociatedException Exception if the companion device is not associated