Expose new ContextHubService APIs
Also deprecates old APIs.
Bug: 67734082
Test: make update-api && make
Change-Id: I93166347ce2ec63f9c0cffd0b8b0bbaa488e5ea4
diff --git a/api/system-current.txt b/api/system-current.txt
index 3e78167..83d100b 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -1340,9 +1340,30 @@
package android.hardware.location {
+ public class ContextHubClient implements java.io.Closeable {
+ method public void close();
+ method public android.hardware.location.ContextHubInfo getAttachedHub();
+ method public int sendMessageToNanoApp(android.hardware.location.NanoAppMessage);
+ }
+
+ public class ContextHubClientCallback {
+ ctor public ContextHubClientCallback();
+ method public void onHubReset(android.hardware.location.ContextHubClient);
+ method public void onMessageFromNanoApp(android.hardware.location.ContextHubClient, android.hardware.location.NanoAppMessage);
+ method public void onNanoAppAborted(android.hardware.location.ContextHubClient, long, int);
+ method public void onNanoAppDisabled(android.hardware.location.ContextHubClient, long);
+ method public void onNanoAppEnabled(android.hardware.location.ContextHubClient, long);
+ method public void onNanoAppLoaded(android.hardware.location.ContextHubClient, long);
+ method public void onNanoAppUnloaded(android.hardware.location.ContextHubClient, long);
+ }
+
public class ContextHubInfo implements android.os.Parcelable {
ctor public ContextHubInfo();
method public int describeContents();
+ method public byte getChreApiMajorVersion();
+ method public byte getChreApiMinorVersion();
+ method public short getChrePatchVersion();
+ method public long getChrePlatformId();
method public int getId();
method public int getMaxPacketLengthBytes();
method public android.hardware.location.MemoryRegion[] getMemoryRegions();
@@ -1362,19 +1383,27 @@
}
public final class ContextHubManager {
- method public int[] findNanoAppOnHub(int, android.hardware.location.NanoAppFilter);
- method public int[] getContextHubHandles();
- method public android.hardware.location.ContextHubInfo getContextHubInfo(int);
- method public android.hardware.location.NanoAppInstanceInfo getNanoAppInstanceInfo(int);
- method public int loadNanoApp(int, android.hardware.location.NanoApp);
- method public int registerCallback(android.hardware.location.ContextHubManager.Callback);
- method public int registerCallback(android.hardware.location.ContextHubManager.Callback, android.os.Handler);
- method public int sendMessage(int, int, android.hardware.location.ContextHubMessage);
- method public int unloadNanoApp(int);
- method public int unregisterCallback(android.hardware.location.ContextHubManager.Callback);
+ method public android.hardware.location.ContextHubClient createClient(android.hardware.location.ContextHubInfo, android.hardware.location.ContextHubClientCallback, java.util.concurrent.Executor);
+ method public android.hardware.location.ContextHubClient createClient(android.hardware.location.ContextHubInfo, android.hardware.location.ContextHubClientCallback);
+ method public android.hardware.location.ContextHubTransaction<java.lang.Void> disableNanoApp(android.hardware.location.ContextHubInfo, long);
+ method public android.hardware.location.ContextHubTransaction<java.lang.Void> enableNanoApp(android.hardware.location.ContextHubInfo, long);
+ method public deprecated int[] findNanoAppOnHub(int, android.hardware.location.NanoAppFilter);
+ method public deprecated int[] getContextHubHandles();
+ method public deprecated android.hardware.location.ContextHubInfo getContextHubInfo(int);
+ method public java.util.List<android.hardware.location.ContextHubInfo> getContextHubs();
+ method public deprecated android.hardware.location.NanoAppInstanceInfo getNanoAppInstanceInfo(int);
+ method public deprecated int loadNanoApp(int, android.hardware.location.NanoApp);
+ method public android.hardware.location.ContextHubTransaction<java.lang.Void> loadNanoApp(android.hardware.location.ContextHubInfo, android.hardware.location.NanoAppBinary);
+ method public android.hardware.location.ContextHubTransaction<java.util.List<android.hardware.location.NanoAppState>> queryNanoApps(android.hardware.location.ContextHubInfo);
+ method public deprecated int registerCallback(android.hardware.location.ContextHubManager.Callback);
+ method public deprecated int registerCallback(android.hardware.location.ContextHubManager.Callback, android.os.Handler);
+ method public deprecated int sendMessage(int, int, android.hardware.location.ContextHubMessage);
+ method public deprecated int unloadNanoApp(int);
+ method public android.hardware.location.ContextHubTransaction<java.lang.Void> unloadNanoApp(android.hardware.location.ContextHubInfo, long);
+ method public deprecated int unregisterCallback(android.hardware.location.ContextHubManager.Callback);
}
- public static abstract class ContextHubManager.Callback {
+ public static abstract deprecated class ContextHubManager.Callback {
ctor protected ContextHubManager.Callback();
method public abstract void onMessageReceipt(int, int, android.hardware.location.ContextHubMessage);
}
@@ -1392,6 +1421,37 @@
field public static final android.os.Parcelable.Creator<android.hardware.location.ContextHubMessage> CREATOR;
}
+ public class ContextHubTransaction<T> {
+ method public int getType();
+ method public void setOnCompleteListener(android.hardware.location.ContextHubTransaction.OnCompleteListener<T>, java.util.concurrent.Executor);
+ method public void setOnCompleteListener(android.hardware.location.ContextHubTransaction.OnCompleteListener<T>);
+ method public static java.lang.String typeToString(int, boolean);
+ method public android.hardware.location.ContextHubTransaction.Response<T> waitForResponse(long, java.util.concurrent.TimeUnit) throws java.lang.InterruptedException, java.util.concurrent.TimeoutException;
+ field public static final int RESULT_FAILED_AT_HUB = 5; // 0x5
+ field public static final int RESULT_FAILED_BAD_PARAMS = 2; // 0x2
+ field public static final int RESULT_FAILED_BUSY = 4; // 0x4
+ field public static final int RESULT_FAILED_HAL_UNAVAILABLE = 8; // 0x8
+ field public static final int RESULT_FAILED_SERVICE_INTERNAL_FAILURE = 7; // 0x7
+ field public static final int RESULT_FAILED_TIMEOUT = 6; // 0x6
+ field public static final int RESULT_FAILED_UNINITIALIZED = 3; // 0x3
+ field public static final int RESULT_FAILED_UNKNOWN = 1; // 0x1
+ field public static final int RESULT_SUCCESS = 0; // 0x0
+ field public static final int TYPE_DISABLE_NANOAPP = 3; // 0x3
+ field public static final int TYPE_ENABLE_NANOAPP = 2; // 0x2
+ field public static final int TYPE_LOAD_NANOAPP = 0; // 0x0
+ field public static final int TYPE_QUERY_NANOAPPS = 4; // 0x4
+ field public static final int TYPE_UNLOAD_NANOAPP = 1; // 0x1
+ }
+
+ public static abstract interface ContextHubTransaction.OnCompleteListener<L> {
+ method public abstract void onComplete(android.hardware.location.ContextHubTransaction<L>, android.hardware.location.ContextHubTransaction.Response<L>);
+ }
+
+ public static class ContextHubTransaction.Response<R> {
+ method public R getContents();
+ method public int getResult();
+ }
+
public final class GeofenceHardware {
method public boolean addGeofence(int, int, android.hardware.location.GeofenceHardwareRequest, android.hardware.location.GeofenceHardwareCallback);
method public int[] getMonitoringTypes();
@@ -1508,6 +1568,25 @@
field public static final android.os.Parcelable.Creator<android.hardware.location.NanoApp> CREATOR;
}
+ public final class NanoAppBinary implements android.os.Parcelable {
+ ctor public NanoAppBinary(byte[]);
+ method public int describeContents();
+ method public byte[] getBinary();
+ method public byte[] getBinaryNoHeader();
+ method public int getFlags();
+ method public int getHeaderVersion();
+ method public long getHwHubType();
+ method public long getNanoAppId();
+ method public int getNanoAppVersion();
+ method public byte getTargetChreApiMajorVersion();
+ method public byte getTargetChreApiMinorVersion();
+ method public boolean hasValidHeader();
+ method public boolean isEncrypted();
+ method public boolean isSigned();
+ method public void writeToParcel(android.os.Parcel, int);
+ field public static final android.os.Parcelable.Creator<android.hardware.location.NanoAppBinary> CREATOR;
+ }
+
public class NanoAppFilter {
ctor public NanoAppFilter(long, int, int, long);
method public int describeContents();
@@ -1541,6 +1620,28 @@
field public static final android.os.Parcelable.Creator<android.hardware.location.NanoAppInstanceInfo> CREATOR;
}
+ public final class NanoAppMessage implements android.os.Parcelable {
+ method public static android.hardware.location.NanoAppMessage createMessageFromNanoApp(long, int, byte[], boolean);
+ method public static android.hardware.location.NanoAppMessage createMessageToNanoApp(long, int, byte[]);
+ method public int describeContents();
+ method public byte[] getMessageBody();
+ method public int getMessageType();
+ method public long getNanoAppId();
+ method public boolean isBroadcastMessage();
+ method public void writeToParcel(android.os.Parcel, int);
+ field public static final android.os.Parcelable.Creator<android.hardware.location.NanoAppMessage> CREATOR;
+ }
+
+ public final class NanoAppState implements android.os.Parcelable {
+ ctor public NanoAppState(long, int, boolean);
+ method public int describeContents();
+ method public long getNanoAppId();
+ method public long getNanoAppVersion();
+ method public boolean isEnabled();
+ method public void writeToParcel(android.os.Parcel, int);
+ field public static final android.os.Parcelable.Creator<android.hardware.location.NanoAppState> CREATOR;
+ }
+
}
package android.hardware.radio {
diff --git a/core/java/android/hardware/location/ContextHubClient.java b/core/java/android/hardware/location/ContextHubClient.java
index 4ba5e80..0a21083 100644
--- a/core/java/android/hardware/location/ContextHubClient.java
+++ b/core/java/android/hardware/location/ContextHubClient.java
@@ -17,6 +17,7 @@
import android.annotation.NonNull;
import android.annotation.RequiresPermission;
+import android.annotation.SystemApi;
import android.os.RemoteException;
import com.android.internal.util.Preconditions;
@@ -34,6 +35,7 @@
*
* @hide
*/
+@SystemApi
public class ContextHubClient implements Closeable {
/*
* The proxy to the client interface at the service.
diff --git a/core/java/android/hardware/location/ContextHubClientCallback.java b/core/java/android/hardware/location/ContextHubClientCallback.java
index 6c48ee9c..cc2fe65 100644
--- a/core/java/android/hardware/location/ContextHubClientCallback.java
+++ b/core/java/android/hardware/location/ContextHubClientCallback.java
@@ -15,15 +15,20 @@
*/
package android.hardware.location;
+import android.annotation.SystemApi;
+
+import java.util.concurrent.Executor;
+
/**
* A class for {@link android.hardware.location.ContextHubClient ContextHubClient} to
* receive messages and life-cycle events from nanoapps in the Context Hub at which the client is
* attached to.
*
- * This callback is registered through the
- * {@link android.hardware.location.ContextHubManager#createClient() creation} of
- * {@link android.hardware.location.ContextHubClient ContextHubClient}. Callbacks are
- * invoked in the following ways:
+ * This callback is registered through the {@link
+ * android.hardware.location.ContextHubManager#createClient(
+ * ContextHubInfo, ContextHubClientCallback, Executor) creation} of
+ * {@link android.hardware.location.ContextHubClient ContextHubClient}. Callbacks are invoked in
+ * the following ways:
* 1) Messages from nanoapps delivered through onMessageFromNanoApp may either be broadcasted
* or targeted to a specific client.
* 2) Nanoapp or Context Hub events (the remaining callbacks) are broadcasted to all clients, and
@@ -31,6 +36,7 @@
*
* @hide
*/
+@SystemApi
public class ContextHubClientCallback {
/**
* Callback invoked when receiving a message from a nanoapp.
diff --git a/core/java/android/hardware/location/ContextHubInfo.java b/core/java/android/hardware/location/ContextHubInfo.java
index c2b2800..36123e3 100644
--- a/core/java/android/hardware/location/ContextHubInfo.java
+++ b/core/java/android/hardware/location/ContextHubInfo.java
@@ -221,9 +221,6 @@
/**
* @return the CHRE platform ID as defined in chre/version.h
- *
- * TODO(b/67734082): Expose as public API
- * @hide
*/
public long getChrePlatformId() {
return mChrePlatformId;
@@ -231,9 +228,6 @@
/**
* @return the CHRE API's major version as defined in chre/version.h
- *
- * TODO(b/67734082): Expose as public API
- * @hide
*/
public byte getChreApiMajorVersion() {
return mChreApiMajorVersion;
@@ -241,9 +235,6 @@
/**
* @return the CHRE API's minor version as defined in chre/version.h
- *
- * TODO(b/67734082): Expose as public API
- * @hide
*/
public byte getChreApiMinorVersion() {
return mChreApiMinorVersion;
@@ -251,9 +242,6 @@
/**
* @return the CHRE patch version as defined in chre/version.h
- *
- * TODO(b/67734082): Expose as public API
- * @hide
*/
public short getChrePatchVersion() {
return mChrePatchVersion;
diff --git a/core/java/android/hardware/location/ContextHubManager.java b/core/java/android/hardware/location/ContextHubManager.java
index 237702b..be1efde 100644
--- a/core/java/android/hardware/location/ContextHubManager.java
+++ b/core/java/android/hardware/location/ContextHubManager.java
@@ -62,7 +62,11 @@
/**
* An interface to receive asynchronous communication from the context hub.
+ *
+ * @deprecated Use the more refined {@link android.hardware.location.ContextHubClientCallback}
+ * instead for notification callbacks.
*/
+ @Deprecated
public abstract static class Callback {
protected Callback() {}
@@ -101,8 +105,13 @@
/**
* Get a handle to all the context hubs in the system
+ *
* @return array of context hub handles
+ *
+ * @deprecated Use {@link #getContextHubs()} instead. The use of handles are deprecated in the
+ * new APIs.
*/
+ @Deprecated
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
public int[] getContextHubHandles() {
try {
@@ -119,7 +128,11 @@
* @return ContextHubInfo Information about the requested context hub.
*
* @see ContextHubInfo
+ *
+ * @deprecated Use {@link #getContextHubs()} instead. The use of handles are deprecated in the
+ * new APIs.
*/
+ @Deprecated
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
public ContextHubInfo getContextHubInfo(int hubHandle) {
try {
@@ -147,7 +160,10 @@
* -1 otherwise
*
* @see NanoApp
+ *
+ * @deprecated Use {@link #loadNanoApp(ContextHubInfo, NanoAppBinary)} instead.
*/
+ @Deprecated
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
public int loadNanoApp(int hubHandle, @NonNull NanoApp app) {
try {
@@ -171,7 +187,10 @@
*
* @return 0 if the command for unloading was sent to the context hub;
* -1 otherwise
+ *
+ * @deprecated Use {@link #unloadNanoApp(ContextHubInfo, long)} instead.
*/
+ @Deprecated
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
public int unloadNanoApp(int nanoAppHandle) {
try {
@@ -207,7 +226,11 @@
* does not exist
*
* @see NanoAppInstanceInfo
+ *
+ * @deprecated Use {@link #queryNanoApps(ContextHubInfo)} instead to explicitly query the hub
+ * for loaded nanoapps.
*/
+ @Deprecated
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
@Nullable public NanoAppInstanceInfo getNanoAppInstanceInfo(int nanoAppHandle) {
try {
@@ -226,7 +249,11 @@
* @see NanoAppFilter
*
* @return int[] Array of handles to any found nano apps
+ *
+ * @deprecated Use {@link #queryNanoApps(ContextHubInfo)} instead to explicitly query the hub
+ * for loaded nanoapps.
*/
+ @Deprecated
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
@NonNull public int[] findNanoAppOnHub(int hubHandle, @NonNull NanoAppFilter filter) {
try {
@@ -254,7 +281,14 @@
* @see ContextHubMessage
*
* @return int 0 on success, -1 otherwise
+ *
+ * @deprecated Use {@link android.hardware.location.ContextHubClient#sendMessageToNanoApp(
+ * NanoAppMessage)} instead, after creating a
+ * {@link android.hardware.location.ContextHubClient} with
+ * {@link #createClient(ContextHubInfo, ContextHubClientCallback, Executor)}
+ * or {@link #createClient(ContextHubInfo, ContextHubClientCallback)}.
*/
+ @Deprecated
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
public int sendMessage(int hubHandle, int nanoAppHandle, @NonNull ContextHubMessage message) {
try {
@@ -270,8 +304,6 @@
* @return the list of ContextHubInfo objects
*
* @see ContextHubInfo
- *
- * @hide
*/
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
@NonNull public List<ContextHubInfo> getContextHubs() {
@@ -349,8 +381,6 @@
* @throws NullPointerException if hubInfo or NanoAppBinary is null
*
* @see NanoAppBinary
- *
- * @hide
*/
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
@NonNull public ContextHubTransaction<Void> loadNanoApp(
@@ -380,8 +410,6 @@
* @return the ContextHubTransaction of the request
*
* @throws NullPointerException if hubInfo is null
- *
- * @hide
*/
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
@NonNull public ContextHubTransaction<Void> unloadNanoApp(
@@ -410,8 +438,6 @@
* @return the ContextHubTransaction of the request
*
* @throws NullPointerException if hubInfo is null
- *
- * @hide
*/
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
@NonNull public ContextHubTransaction<Void> enableNanoApp(
@@ -440,8 +466,6 @@
* @return the ContextHubTransaction of the request
*
* @throws NullPointerException if hubInfo is null
- *
- * @hide
*/
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
@NonNull public ContextHubTransaction<Void> disableNanoApp(
@@ -469,8 +493,6 @@
* @return the ContextHubTransaction of the request
*
* @throws NullPointerException if hubInfo is null
- *
- * @hide
*/
@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
@NonNull public ContextHubTransaction<List<NanoAppState>> queryNanoApps(
@@ -498,7 +520,12 @@
* @see Callback
*
* @return int 0 on success, -1 otherwise
+ *
+ * @deprecated Use {@link #createClient(ContextHubInfo, ContextHubClientCallback, Executor)}
+ * or {@link #createClient(ContextHubInfo, ContextHubClientCallback)} instead to
+ * register a {@link android.hardware.location.ContextHubClientCallback}.
*/
+ @Deprecated
@SuppressLint("Doclava125")
public int registerCallback(@NonNull Callback callback) {
return registerCallback(callback, null);
@@ -527,7 +554,12 @@
* @see Callback
*
* @return int 0 on success, -1 otherwise
+ *
+ * @deprecated Use {@link #createClient(ContextHubInfo, ContextHubClientCallback, Executor)}
+ * or {@link #createClient(ContextHubInfo, ContextHubClientCallback)} instead to
+ * register a {@link android.hardware.location.ContextHubClientCallback}.
*/
+ @Deprecated
@SuppressLint("Doclava125")
public int registerCallback(Callback callback, Handler handler) {
synchronized(this) {
@@ -606,7 +638,6 @@
* @throws IllegalStateException if there were too many registered clients at the service
* @throws NullPointerException if callback, hubInfo, or executor is null
*
- * @hide
* @see ContextHubClientCallback
*/
@NonNull public ContextHubClient createClient(
@@ -642,7 +673,7 @@
* @throws IllegalArgumentException if hubInfo does not represent a valid hub
* @throws IllegalStateException if there were too many registered clients at the service
* @throws NullPointerException if callback or hubInfo is null
- * @hide
+ *
* @see ContextHubClientCallback
*/
@NonNull public ContextHubClient createClient(
@@ -658,8 +689,12 @@
* @param callback method to deregister
*
* @return int 0 on success, -1 otherwise
+ *
+ * @deprecated Use {@link android.hardware.location.ContextHubClient#close()} to unregister
+ * a {@link android.hardware.location.ContextHubClientCallback}.
*/
@SuppressLint("Doclava125")
+ @Deprecated
public int unregisterCallback(@NonNull Callback callback) {
synchronized(this) {
if (callback != mCallback) {
diff --git a/core/java/android/hardware/location/ContextHubTransaction.java b/core/java/android/hardware/location/ContextHubTransaction.java
index 35ab4a9..bc7efef 100644
--- a/core/java/android/hardware/location/ContextHubTransaction.java
+++ b/core/java/android/hardware/location/ContextHubTransaction.java
@@ -18,6 +18,7 @@
import android.annotation.CallbackExecutor;
import android.annotation.IntDef;
import android.annotation.NonNull;
+import android.annotation.SystemApi;
import android.os.Handler;
import android.os.HandlerExecutor;
@@ -43,11 +44,13 @@
*
* @hide
*/
+@SystemApi
public class ContextHubTransaction<T> {
private static final String TAG = "ContextHubTransaction";
/**
* Constants describing the type of a transaction through the Context Hub Service.
+ * {@hide}
*/
@Retention(RetentionPolicy.SOURCE)
@IntDef(prefix = { "TYPE_" }, value = {
@@ -67,6 +70,7 @@
/**
* Constants describing the result of a transaction or request through the Context Hub Service.
+ * {@hide}
*/
@Retention(RetentionPolicy.SOURCE)
@IntDef(prefix = { "RESULT_" }, value = {
diff --git a/core/java/android/hardware/location/NanoAppBinary.java b/core/java/android/hardware/location/NanoAppBinary.java
index 934e9e4..ba01ca2 100644
--- a/core/java/android/hardware/location/NanoAppBinary.java
+++ b/core/java/android/hardware/location/NanoAppBinary.java
@@ -15,6 +15,7 @@
*/
package android.hardware.location;
+import android.annotation.SystemApi;
import android.os.Parcel;
import android.os.Parcelable;
import android.util.Log;
@@ -27,6 +28,7 @@
/**
* @hide
*/
+@SystemApi
public final class NanoAppBinary implements Parcelable {
private static final String TAG = "NanoAppBinary";
diff --git a/core/java/android/hardware/location/NanoAppMessage.java b/core/java/android/hardware/location/NanoAppMessage.java
index 2028674..716a194 100644
--- a/core/java/android/hardware/location/NanoAppMessage.java
+++ b/core/java/android/hardware/location/NanoAppMessage.java
@@ -15,6 +15,7 @@
*/
package android.hardware.location;
+import android.annotation.SystemApi;
import android.os.Parcel;
import android.os.Parcelable;
@@ -25,6 +26,7 @@
*
* @hide
*/
+@SystemApi
public final class NanoAppMessage implements Parcelable {
private long mNanoAppId;
private int mMessageType;
diff --git a/core/java/android/hardware/location/NanoAppState.java b/core/java/android/hardware/location/NanoAppState.java
index 644031b..d05277d 100644
--- a/core/java/android/hardware/location/NanoAppState.java
+++ b/core/java/android/hardware/location/NanoAppState.java
@@ -15,6 +15,7 @@
*/
package android.hardware.location;
+import android.annotation.SystemApi;
import android.os.Parcel;
import android.os.Parcelable;
@@ -23,6 +24,7 @@
*
* @hide
*/
+@SystemApi
public final class NanoAppState implements Parcelable {
private long mNanoAppId;
private int mNanoAppVersion;