diff --git a/core/java/android/companion/CompanionDeviceService.java b/core/java/android/companion/CompanionDeviceService.java index 12ced96a0ffb5..610b7ee5befac 100644 --- a/core/java/android/companion/CompanionDeviceService.java +++ b/core/java/android/companion/CompanionDeviceService.java @@ -31,29 +31,71 @@ import android.util.Log; import java.util.Objects; /** - * Service to be implemented by apps that manage a companion device. + * A service that receives calls from the system when the associated companion device appears + * nearby or is connected, as well as when the device is no longer "present" or connected. + * See {@link #onDeviceAppeared(AssociationInfo)}/{@link #onDeviceDisappeared(AssociationInfo)}. * - * System will keep this service bound whenever an associated device is nearby for Bluetooth - * devices or companion app manages the connectivity and reports disappeared, ensuring app stays - * alive + *

+ * Additionally, the service will receive a call from the system, if and when the system needs to + * transfer data to the companion device. + * See {@link #dispatchMessage(int, int, byte[])}). * - * An app must be {@link CompanionDeviceManager#associate associated} with at leas one device, - * before it can take advantage of this service. + *

+ * Companion applications must create a service that {@code extends} + * {@link CompanionDeviceService}, and declare it in their AndroidManifest.xml with the + * "android.permission.BIND_COMPANION_DEVICE_SERVICE" permission + * (see {@link android.Manifest.permission#BIND_COMPANION_DEVICE_SERVICE}), + * as well as add an intent filter for the "android.companion.CompanionDeviceService" action + * (see {@link #SERVICE_INTERFACE}). * - * You must declare this service in your manifest with an - * intent-filter action of {@link #SERVICE_INTERFACE} and - * permission of {@link android.Manifest.permission#BIND_COMPANION_DEVICE_SERVICE} + *

+ * Following is an example of such declaration: + * 

{@code
+ * 
+ *    
+ *        
+ *    
+ * 
+ * }
* - *

If you want to declare more than one of these services, you must declare the meta-data in the - * service of your manifest with the corresponding name and value to true to indicate the - * primary service. - * Only the primary one will get the callback from - * {@link #onDeviceAppeared(AssociationInfo associationInfo)}.

+ *

+ * If the companion application has requested observing device presence (see + * {@link CompanionDeviceManager#startObservingDevicePresence(String)}) the system will + * bind the service + * when it detects the device nearby (for BLE devices) or when the device is connected + * (for Bluetooth devices). * - * Example: + *

+ * The system binding {@link 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 {@link CompanionDeviceService}-s. + * In such case, the system will bind all declared services, but will deliver + * {@link #onDeviceAppeared(AssociationInfo)}, {@link #onDeviceDisappeared(AssociationInfo)} and + * {@link #dispatchMessage(int, int, byte[])} only to one "primary" services. + * Applications that declare multiple {@link CompanionDeviceService}-s should indicate the "primary" + * service using "android.companion.primary" tag. + * 

{@code
  * 
+ *       android:name="android.companion.primary"
+ *       android:value="true" />
+ * }
+ * + *

+ * If the application declares multiple {@link 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" {@link CompanionDeviceService}-s, the system + * will pick single one of them to use as "primary". */ public abstract class CompanionDeviceService extends Service { diff --git a/services/companion/java/com/android/server/companion/CompanionDevicePresenceController.java b/services/companion/java/com/android/server/companion/CompanionDevicePresenceController.java index 4447684916604..fc6681705cb6f 100644 --- a/services/companion/java/com/android/server/companion/CompanionDevicePresenceController.java +++ b/services/companion/java/com/android/server/companion/CompanionDevicePresenceController.java @@ -48,7 +48,7 @@ import java.util.Objects; public class CompanionDevicePresenceController { private static final String LOG_TAG = "CompanionDevicePresenceController"; PerUser>> mBoundServices; - private static final String META_DATA_KEY_PRIMARY = "primary"; + private static final String META_DATA_KEY_PRIMARY = "android.companion.primary"; private final CompanionDeviceManagerService mService; public CompanionDevicePresenceController(CompanionDeviceManagerService service) { diff --git a/services/companion/java/com/android/server/companion/PackageUtils.java b/services/companion/java/com/android/server/companion/PackageUtils.java index 985daa356a537..fcb14a4f04d0f 100644 --- a/services/companion/java/com/android/server/companion/PackageUtils.java +++ b/services/companion/java/com/android/server/companion/PackageUtils.java @@ -53,7 +53,7 @@ import java.util.Map; final class PackageUtils { private static final Intent COMPANION_SERVICE_INTENT = new Intent(CompanionDeviceService.SERVICE_INTERFACE); - private static final String META_DATA_KEY_PRIMARY = "primary"; + private static final String META_DATA_PRIMARY_TAG = "android.companion.primary"; static @Nullable PackageInfo getPackageInfo(@NonNull Context context, @UserIdInt int userId, @NonNull String packageName) { @@ -121,6 +121,6 @@ final class PackageUtils { } private static boolean isPrimaryCompanionDeviceService(ServiceInfo service) { - return service.metaData != null && service.metaData.getBoolean(META_DATA_KEY_PRIMARY); + return service.metaData != null && service.metaData.getBoolean(META_DATA_PRIMARY_TAG); } }