Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit ac2cf8ba authored by Evan Chen's avatar Evan Chen
Browse files

Fix CompanionDeviceService doc

Test: m
Bug: 302149681
Flag: EXEMPT test improvement
Change-Id: Ibd6d79770c2d1c5f8b6764fa5d01f4b620288a68
parent 54552737
Loading
Loading
Loading
Loading
+22 −11
Original line number Diff line number Diff line
@@ -62,10 +62,11 @@ import java.util.concurrent.Executor;
 *
 * <p>
 * If the companion application has requested observing device presence (see
 * {@link CompanionDeviceManager#startObservingDevicePresence(String)}) the system will
 * <a href="https://developer.android.com/guide/components/bound-services"> bind the service</a>
 * when it detects the device nearby (for BLE devices) or when the device is connected
 * (for Bluetooth devices).
 * {@link CompanionDeviceManager#stopObservingDevicePresence(ObservingDevicePresenceRequest)})
 * the system will <a href="https://developer.android.com/guide/components/bound-services">
 * bind the service</a> when one of the {@link DevicePresenceEvent#EVENT_BLE_APPEARED},
 * {@link DevicePresenceEvent#EVENT_BT_CONNECTED},
 * {@link DevicePresenceEvent#EVENT_SELF_MANAGED_APPEARED} event is notified.
 *
 * <p>
 * The system binding {@link CompanionDeviceService} elevates the priority of the process that
@@ -102,15 +103,25 @@ public abstract class CompanionDeviceService extends Service {

    /**
     * An intent action for a service to be bound whenever this app's companion device(s)
     * are nearby.
     * are nearby or self-managed device(s) report app appeared.
     *
     * <p>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.</p>
     * <p>The app will be kept bound by the system when one of the
     * {@link DevicePresenceEvent#EVENT_BLE_APPEARED},
     * {@link DevicePresenceEvent#EVENT_BT_CONNECTED},
     * {@link DevicePresenceEvent#EVENT_SELF_MANAGED_APPEARED} event is notified.
     *
     * <p>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.</p>
     * If the app is not running when one of the
     * {@link DevicePresenceEvent#EVENT_BLE_APPEARED},
     * {@link DevicePresenceEvent#EVENT_BT_CONNECTED},
     * {@link DevicePresenceEvent#EVENT_SELF_MANAGED_APPEARED} event is notified, the app will be
     * kept bound by the system.</p>
     *
     * <p>Shortly, the service will be unbound if both
     * {@link DevicePresenceEvent#EVENT_BLE_DISAPPEARED} and
     * {@link DevicePresenceEvent#EVENT_BT_DISCONNECTED} are notified, or
     * {@link DevicePresenceEvent#EVENT_SELF_MANAGED_DISAPPEARED} event is notified.
     * The app will be eligible for cleanup, unless any other user-visible components are
     * running.</p>
     *
     * If running in background is not essential for the devices that this app can manage,
     * app should avoid declaring this service.</p>