# Print output for @column tags ?> CompanionDeviceManager - Android SDK | Android Developers

Most visited

Recently visited

CompanionDeviceManager

public final class CompanionDeviceManager
extends Object

java.lang.Object
   ↳ android.companion.CompanionDeviceManager


System level service for managing companion devices See this guide for a usage example.

To obtain an instance call Context#getSystemService(Context.COMPANION_DEVICE_SERVICE) Then, call associate(android.companion.AssociationRequest, android.companion.CompanionDeviceManager.Callback, android.os.Handler) to initiate the flow of associating current package with a device selected by user.

See also:

Summary

Nested classes

class CompanionDeviceManager.Callback

A callback to receive once at least one suitable device is found, or the search failed (e.g. timed out) 

Constants

String EXTRA_DEVICE

A device, returned in the activity result of the IntentSender received in Callback#onDeviceFound Type is:

Public methods

void associate(AssociationRequest request, CompanionDeviceManager.Callback callback, Handler handler)

Associate this app with a companion device, selected by user

Once at least one appropriate device is found, callback will be called with a PendingIntent that can be used to show the list of available devices for the user to select.

void disassociate(String deviceMacAddress)

Remove the association between this app and the device with the given mac address.

List<String> getAssociations()

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

boolean hasNotificationAccess(ComponentName component)

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

void requestNotificationAccess(ComponentName component)

Request notification access for the given component.

void startObservingDevicePresence(String deviceAddress)

Register to receive callbacks whenever the associated device comes in and out of range.

void stopObservingDevicePresence(String deviceAddress)

Unregister for receiving callbacks whenever the associated device comes in and out of range.

Inherited methods

Constants

EXTRA_DEVICE

public static final String EXTRA_DEVICE

A device, returned in the activity result of the IntentSender received in Callback#onDeviceFound Type is:

Constant Value: "android.companion.extra.DEVICE"

Public methods

associate

public void associate (AssociationRequest request, 
                CompanionDeviceManager.Callback callback, 
                Handler handler)

Associate this app with a companion device, selected by user

Once at least one appropriate device is found, callback will be called with a PendingIntent that can be used to show the list of available devices for the user to select. It should be started for result (i.e. using Activity.startIntentSenderForResult(IntentSender, int, Intent, int, int, int)), as the resulting Intent will contain extra EXTRA_DEVICE, with the selected device. (e.g. BluetoothDevice)

If your app needs to be excluded from battery optimizations (run in the background) or to have unrestricted data access (use data in the background) you can declare that you use the Manifest.permission.REQUEST_COMPANION_RUN_IN_BACKGROUND and Manifest.permission.REQUEST_COMPANION_USE_DATA_IN_BACKGROUND 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.

You can call getAssociations() to get the list of currently associated devices, and disassociate(String) to remove an association. 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

When using watch profile, caller must also hold Manifest.permission#REQUEST_COMPANION_PROFILE_WATCH

Parameters
request AssociationRequest: specific details about this request This value cannot be null.

callback CompanionDeviceManager.Callback: will be called once there's at least one device found for user to choose from This value cannot be null.

handler Handler: A handler to control which thread the callback will be delivered on, or null, to deliver it on main thread This value may be null.

See also:

disassociate

public void disassociate (String deviceMacAddress)

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 This value cannot be null.

getAssociations

public List<String> getAssociations ()

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Returns
List<String> a list of MAC addresses of devices that have been previously associated with the current app. You can use these with disassociate(String) This value cannot be null.

hasNotificationAccess

public boolean hasNotificationAccess (ComponentName component)

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

Returns
boolean whether the given component has the notification listener permission

requestNotificationAccess

public void requestNotificationAccess (ComponentName component)

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

Calling this API requires a uses-feature PackageManager#FEATURE_COMPANION_DEVICE_SETUP declaration in the manifest

Parameters
component ComponentName

startObservingDevicePresence

public void startObservingDevicePresence (String deviceAddress)

Register to receive callbacks whenever the associated device comes in and out of range. The provided device must be associated with the calling app before calling this method. Caller must implement a single CompanionDeviceService which will be bound to and receive callbacks to CompanionDeviceService#onDeviceAppeared and CompanionDeviceService#onDeviceDisappeared. The app doesn't need to remain running in order to receive its callbacks. Calling app must declare uses-permission 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. 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 Manifest.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE

Parameters
deviceAddress String: a previously-associated companion device's address This value cannot be null.

Throws
DeviceNotAssociatedException if the given device was not previously associated with this app.

stopObservingDevicePresence

public void stopObservingDevicePresence (String deviceAddress)

Unregister for receiving callbacks whenever the associated device comes in and out of range. The provided device must be associated with the calling app before calling this method. Calling app must declare uses-permission 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 Manifest.permission.REQUEST_OBSERVE_COMPANION_DEVICE_PRESENCE

Parameters
deviceAddress String: a previously-associated companion device's address This value cannot be null.

Throws
DeviceNotAssociatedException if the given device was not previously associated with this app.