Creates framework for new ContextHubService APIs (b9ae7bd8) · Commits · e / os / android_frameworks_base

core/java/android/hardware/location/ContextHubClient.java

0 → 100644

+95 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright 2017 The Android Open Source Project
		*
		* Licensed under the Apache License, Version 2.0 (the "License");
		* you may not use this file except in compliance with the License.
		* You may obtain a copy of the License at
		*
		* http://www.apache.org/licenses/LICENSE-2.0
		*
		* Unless required by applicable law or agreed to in writing, software
		* distributed under the License is distributed on an "AS IS" BASIS,
		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
		* See the License for the specific language governing permissions and
		* limitations under the License.
		*/
		package android.hardware.location;

		import android.annotation.RequiresPermission;
		import android.os.Handler;

		import java.io.Closeable;

		/**
		* A class describing a client of the Context Hub Service.
		*
		* Clients can send messages to nanoapps at a Context Hub through this object.
		*
		* @hide
		*/
		public class ContextHubClient implements Closeable {
		/*
		* The ContextHubClient interface associated with this client.
		*/
		// TODO: Implement this interface and associate with ContextHubClient object
		// private final IContextHubClient mClientInterface;

		/*
		* The listening callback associated with this client.
		*/
		private ContextHubClientCallback mCallback;

		/*
		* The Context Hub that this client is attached to.
		*/
		private ContextHubInfo mAttachedHub;

		/*
		* The handler to invoke mCallback.
		*/
		private Handler mCallbackHandler;

		ContextHubClient(ContextHubClientCallback callback, Handler handler, ContextHubInfo hubInfo) {
		mCallback = callback;
		mCallbackHandler = handler;
		mAttachedHub = hubInfo;
		}

		/**
		* Returns the hub that this client is attached to.
		*
		* @return the ContextHubInfo of the attached hub
		*/
		public ContextHubInfo getAttachedHub() {
		return mAttachedHub;
		}

		/**
		* Closes the connection for this client and the Context Hub Service.
		*
		* When this function is invoked, the messaging associated with this client is invalidated.
		* All futures messages targeted for this client are dropped at the service.
		*/
		public void close() {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		/**
		* Sends a message to a nanoapp through the Context Hub Service.
		*
		* This function returns TRANSACTION_SUCCESS if the message has reached the HAL, but
		* does not guarantee delivery of the message to the target nanoapp.
		*
		* @param message the message object to send
		*
		* @return the result of sending the message defined as in ContextHubTransaction.Result
		*
		* @see NanoAppMessage
		* @see ContextHubTransaction.Result
		*/
		@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
		@ContextHubTransaction.Result
		public int sendMessageToNanoApp(NanoAppMessage message) {
		throw new UnsupportedOperationException("TODO: Implement this");
		}
		}

core/java/android/hardware/location/ContextHubClientCallback.java

0 → 100644

+85 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright 2017 The Android Open Source Project
		*
		* Licensed under the Apache License, Version 2.0 (the "License");
		* you may not use this file except in compliance with the License.
		* You may obtain a copy of the License at
		*
		* http://www.apache.org/licenses/LICENSE-2.0
		*
		* Unless required by applicable law or agreed to in writing, software
		* distributed under the License is distributed on an "AS IS" BASIS,
		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
		* See the License for the specific language governing permissions and
		* limitations under the License.
		*/
		package android.hardware.location;

		/**
		* 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:
		* 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
		* the client can choose to ignore the event by filtering through the parameters.
		*
		* @hide
		*/
		public class ContextHubClientCallback {
		/**
		* Callback invoked when receiving a message from a nanoapp.
		*
		* The message contents of this callback may either be broadcasted or targeted to the
		* client receiving the invocation.
		*
		* @param message the message sent by the nanoapp
		*/
		public void onMessageFromNanoApp(NanoAppMessage message) {}

		/**
		* Callback invoked when the attached Context Hub has reset.
		*/
		public void onHubReset() {}

		/**
		* Callback invoked when a nanoapp aborts at the attached Context Hub.
		*
		* @param nanoAppId the ID of the nanoapp that had aborted
		* @param abortCode the reason for nanoapp's abort, specific to each nanoapp
		*/
		public void onNanoAppAborted(long nanoAppId, int abortCode) {}

		/**
		* Callback invoked when a nanoapp is loaded at the attached Context Hub.
		*
		* @param nanoAppId the ID of the nanoapp that had been loaded
		*/
		public void onNanoAppLoaded(long nanoAppId) {}

		/**
		* Callback invoked when a nanoapp is unloaded from the attached Context Hub.
		*
		* @param nanoAppId the ID of the nanoapp that had been unloaded
		*/
		public void onNanoAppUnloaded(long nanoAppId) {}

		/**
		* Callback invoked when a nanoapp is enabled at the attached Context Hub.
		*
		* @param nanoAppId the ID of the nanoapp that had been enabled
		*/
		public void onNanoAppEnabled(long nanoAppId) {}

		/**
		* Callback invoked when a nanoapp is disabled at the attached Context Hub.
		*
		* @param nanoAppId the ID of the nanoapp that had been disabled
		*/
		public void onNanoAppDisabled(long nanoAppId) {}
		}

core/java/android/hardware/location/ContextHubManager.java

+120 −1

Original line number	Diff line number	Diff line
		@@ -15,6 +15,7 @@
		*/
		package android.hardware.location;

		import android.annotation.Nullable;
		import android.annotation.RequiresPermission;
		import android.annotation.SuppressLint;
		import android.annotation.SystemApi;
		@@ -27,6 +28,8 @@ import android.os.ServiceManager;
		import android.os.ServiceManager.ServiceNotFoundException;
		import android.util.Log;

		import java.util.List;

		/**
		* A class that exposes the Context hubs on a device to applications.
		*
		@@ -38,7 +41,6 @@ import android.util.Log;
		@SystemApi
		@SystemService(Context.CONTEXTHUB_SERVICE)
		public final class ContextHubManager {

		private static final String TAG = "ContextHubManager";

		private final Looper mMainLooper;
		@@ -255,6 +257,100 @@ public final class ContextHubManager {
		}
		}

		/**
		* Returns the list of context hubs in the system.
		*
		* @return the list of context hub informations
		*
		* @see ContextHubInfo
		*
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
		public List<ContextHubInfo> getContextHubs() {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		/**
		* Loads a nanoapp at the specified Context Hub.
		*
		* After the nanoapp binary is successfully loaded at the specified hub, the nanoapp will be in
		* the enabled state.
		*
		* @param hubInfo the hub to load the nanoapp on
		* @param appBinary The app binary to load
		*
		* @return the ContextHubTransaction of the request
		*
		* @see NanoAppBinary
		*
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
		public ContextHubTransaction<Void> loadNanoApp(
		ContextHubInfo hubInfo, NanoAppBinary appBinary) {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		/**
		* Unloads a nanoapp at the specified Context Hub.
		*
		* @param hubInfo the hub to unload the nanoapp from
		* @param nanoAppId the app to unload
		*
		* @return the ContextHubTransaction of the request
		*
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
		public ContextHubTransaction<Void> unloadNanoApp(ContextHubInfo hubInfo, long nanoAppId) {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		/**
		* Enables a nanoapp at the specified Context Hub.
		*
		* @param hubInfo the hub to enable the nanoapp on
		* @param nanoAppId the app to enable
		*
		* @return the ContextHubTransaction of the request
		*
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
		public ContextHubTransaction<Void> enableNanoApp(ContextHubInfo hubInfo, long nanoAppId) {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		/**
		* Disables a nanoapp at the specified Context Hub.
		*
		* @param hubInfo the hub to disable the nanoapp on
		* @param nanoAppId the app to disable
		*
		* @return the ContextHubTransaction of the request
		*
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
		public ContextHubTransaction<Void> disableNanoApp(ContextHubInfo hubInfo, long nanoAppId) {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		/**
		* Requests a query for nanoapps loaded at the specified Context Hub.
		*
		* @param hubInfo the hub to query a list of nanoapps from
		*
		* @return the ContextHubTransaction of the request
		*
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.LOCATION_HARDWARE)
		public ContextHubTransaction<List<NanoAppState>> queryNanoApps(ContextHubInfo hubInfo) {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		/**
		* Set a callback to receive messages from the context hub
		*
		@@ -306,6 +402,29 @@ public final class ContextHubManager {
		return 0;
		}

		/**
		* Creates and registers a client and its callback with the Context Hub Service.
		*
		* A client is registered with the Context Hub Service for a specified Context Hub. When the
		* registration succeeds, the client can send messages to nanoapps through the returned
		* {@link ContextHubClient} object, and receive notifications through the provided callback.
		*
		* @param callback the notification callback to register
		* @param hubInfo the hub to attach this client to
		* @param handler the handler to invoke the callback, if null uses the current thread Looper
		*
		* @return the registered client object
		*
		* @see ContextHubClientCallback
		*
		* @hide
		*/
		public ContextHubClient createClient(
		ContextHubClientCallback callback, ContextHubInfo hubInfo, @Nullable Handler handler) {
		throw new UnsupportedOperationException(
		"TODO: Implement this, and throw an exception on error");
		}

		/**
		* Unregister a callback for receive messages from the context hub.
		*

core/java/android/hardware/location/ContextHubTransaction.java

0 → 100644

+229 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright 2017 The Android Open Source Project
		*
		* Licensed under the Apache License, Version 2.0 (the "License");
		* you may not use this file except in compliance with the License.
		* You may obtain a copy of the License at
		*
		* http://www.apache.org/licenses/LICENSE-2.0
		*
		* Unless required by applicable law or agreed to in writing, software
		* distributed under the License is distributed on an "AS IS" BASIS,
		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
		* See the License for the specific language governing permissions and
		* limitations under the License.
		*/
		package android.hardware.location;

		import android.annotation.IntDef;
		import android.os.Handler;

		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;
		import java.util.concurrent.TimeUnit;

		/**
		* A class describing a request sent to the Context Hub Service.
		*
		* This object is generated as a result of an asynchronous request sent to the Context Hub
		* through the ContextHubManager APIs. The caller can either retrieve the result
		* synchronously through a blocking call ({@link #waitForResponse(long, TimeUnit)}) or
		* asynchronously through a user-defined callback
		* ({@link #onComplete(ContextHubTransaction.Callback<T>, Handler)}).
		*
		* A transaction can be invalidated if the caller of the transaction is no longer active
		* and the reference to this object is lost, or if timeout period has passed in
		* {@link #waitForResponse(long, TimeUnit)}.
		*
		* @param <T> the type of the contents in the transaction response
		*
		* @hide
		*/
		public class ContextHubTransaction<T> {
		/**
		* Constants describing the type of a transaction through the Context Hub Service.
		*/
		@Retention(RetentionPolicy.SOURCE)
		@IntDef({
		TYPE_LOAD_NANOAPP,
		TYPE_UNLOAD_NANOAPP,
		TYPE_ENABLE_NANOAPP,
		TYPE_DISABLE_NANOAPP,
		TYPE_QUERY_NANOAPPS})
		public @interface Type {}
		public static final int TYPE_LOAD_NANOAPP = 0;
		public static final int TYPE_UNLOAD_NANOAPP = 1;
		public static final int TYPE_ENABLE_NANOAPP = 2;
		public static final int TYPE_DISABLE_NANOAPP = 3;
		public static final int TYPE_QUERY_NANOAPPS = 4;

		/**
		* Constants describing the result of a transaction or request through the Context Hub Service.
		*/
		@Retention(RetentionPolicy.SOURCE)
		@IntDef({
		TRANSACTION_SUCCESS,
		TRANSACTION_FAILED_UNKNOWN,
		TRANSACTION_FAILED_BAD_PARAMS,
		TRANSACTION_FAILED_UNINITIALIZED,
		TRANSACTION_FAILED_PENDING,
		TRANSACTION_FAILED_AT_HUB,
		TRANSACTION_FAILED_TIMEOUT})
		public @interface Result {}
		public static final int TRANSACTION_SUCCESS = 0;
		/**
		* Generic failure mode.
		*/
		public static final int TRANSACTION_FAILED_UNKNOWN = 1;
		/**
		* Failure mode when the request parameters were not valid.
		*/
		public static final int TRANSACTION_FAILED_BAD_PARAMS = 2;
		/**
		* Failure mode when the Context Hub is not initialized.
		*/
		public static final int TRANSACTION_FAILED_UNINITIALIZED = 3;
		/**
		* Failure mode when there are too many transactions pending.
		*/
		public static final int TRANSACTION_FAILED_PENDING = 4;
		/**
		* Failure mode when the request went through, but failed asynchronously at the hub.
		*/
		public static final int TRANSACTION_FAILED_AT_HUB = 5;
		/**
		* Failure mode when the transaction has timed out.
		*/
		public static final int TRANSACTION_FAILED_TIMEOUT = 6;

		/**
		* A class describing the response for a ContextHubTransaction.
		*
		* @param <R> the type of the contents in the response
		*/
		public static class Response<R> {
		/*
		* The result of the transaction.
		*/
		@ContextHubTransaction.Result
		private int mResult;

		/*
		* The contents of the response from the Context Hub.
		*/
		private R mContents;

		Response(@ContextHubTransaction.Result int result, R contents) {
		mResult = result;
		mContents = contents;
		}

		@ContextHubTransaction.Result
		public int getResult() {
		return mResult;
		}

		public R getContents() {
		return mContents;
		}
		}

		/**
		* An interface describing the callback to be invoked when a transaction completes.
		*
		* @param <C> the type of the contents in the transaction response
		*/
		@FunctionalInterface
		public interface Callback<C> {
		/**
		* The callback to invoke when the transaction completes.
		*
		* @param transaction the transaction that this callback was attached to.
		* @param response the response of the transaction.
		*/
		void onComplete(
		ContextHubTransaction<C> transaction, ContextHubTransaction.Response<C> response);
		}

		/*
		* The unique identifier representing the transaction.
		*/
		private int mTransactionId;

		/*
		* The type of the transaction.
		*/
		@Type
		private int mTransactionType;

		/*
		* The response of the transaction.
		*/
		private ContextHubTransaction.Response<T> mResponse;

		/*
		* The handler to invoke the aynsc response supplied by onComplete.
		*/
		private Handler mHandler = null;

		/*
		* The callback to invoke when the transaction completes.
		*/
		private ContextHubTransaction.Callback<T> mCallback = null;

		ContextHubTransaction(int id, @Type int type) {
		mTransactionId = id;
		mTransactionType = type;
		}

		/**
		* @return the type of the transaction
		*/
		@Type
		public int getType() {
		return mTransactionType;
		}

		/**
		* Waits to receive the asynchronous transaction result.
		*
		* This function blocks until the Context Hub Service has received a response
		* for the transaction represented by this object by the Context Hub, or a
		* specified timeout period has elapsed.
		*
		* If the specified timeout has passed, the transaction represented by this object
		* is invalidated by the Context Hub Service (resulting in a timeout failure in the
		* response).
		*
		* @param timeout the timeout duration
		* @param unit the unit of the timeout
		*
		* @return the transaction response
		*/
		public ContextHubTransaction.Response<T> waitForResponse(long timeout, TimeUnit unit) {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		/**
		* Sets a callback to be invoked when the transaction completes.
		*
		* This function provides an asynchronous approach to retrieve the result of the
		* transaction. When the transaction response has been provided by the Context Hub,
		* the given callback will be posted by the provided handler.
		*
		* If the transaction has already completed at the time of invocation, the callback
		* will be immediately posted by the handler. If the transaction has been invalidated,
		* the callback will never be invoked.
		*
		* @param callback the callback to be invoked upon completion
		* @param handler the handler to post the callback
		*/
		public void onComplete(ContextHubTransaction.Callback<T> callback, Handler handler) {
		throw new UnsupportedOperationException("TODO: Implement this");
		}

		private void setResponse(ContextHubTransaction.Response<T> response) {
		mResponse = response;
		throw new UnsupportedOperationException("TODO: Unblock waitForResponse");
		}
		}

core/java/android/hardware/location/NanoAppBinary.aidl

0 → 100644

+22 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright 2017 The Android Open Source Project
		*
		* Licensed under the Apache License, Version 2.0 (the "License");
		* you may not use this file except in compliance with the License.
		* You may obtain a copy of the License at
		*
		* http://www.apache.org/licenses/LICENSE-2.0
		*
		* Unless required by applicable law or agreed to in writing, software
		* distributed under the License is distributed on an "AS IS" BASIS,
		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
		* See the License for the specific language governing permissions and
		* limitations under the License.
		*/

		package android.hardware.location;

		/**
		* @hide
		*/
		parcelable NanoAppBinary;