Merge "contexthub: Make client registration API safer" into main (2fe2617f) · Commits · e / os / android_hardware_interfaces

contexthub/aidl/aidl_api/android.hardware.contexthub/current/android/hardware/contexthub/IContextHub.aidl

+1 −9

Original line number	Diff line number	Diff line
		@@ -51,14 +51,6 @@ interface IContextHub {
		void sendMessageDeliveryStatusToHub(in int contextHubId, in android.hardware.contexthub.MessageDeliveryStatus messageDeliveryStatus);
		List<android.hardware.contexthub.HubInfo> getHubs();
		List<android.hardware.contexthub.EndpointInfo> getEndpoints();
		void registerEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);
		void unregisterEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);
		void registerEndpointCallback(in android.hardware.contexthub.IEndpointCallback callback);
		int[2] requestSessionIdRange(int size);
		void openEndpointSession(int sessionId, in android.hardware.contexthub.EndpointId destination, in android.hardware.contexthub.EndpointId initiator, in @nullable String serviceDescriptor);
		void sendMessageToEndpoint(int sessionId, in android.hardware.contexthub.Message msg);
		void sendMessageDeliveryStatusToEndpoint(int sessionId, in android.hardware.contexthub.MessageDeliveryStatus msgStatus);
		void closeEndpointSession(int sessionId, in android.hardware.contexthub.Reason reason);
		void endpointSessionOpenComplete(int sessionId);
		@PropagateAllowBlocking android.hardware.contexthub.IEndpointCommunication registerEndpointHub(in android.hardware.contexthub.IEndpointCallback callback, in android.hardware.contexthub.HubInfo hubInfo);
		const int EX_CONTEXT_HUB_UNSPECIFIED = (-1) /* -1 */;
		}

contexthub/aidl/aidl_api/android.hardware.contexthub/current/android/hardware/contexthub/IEndpointCommunication.aidl

0 → 100644

+46 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2024 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.
		*/
		///////////////////////////////////////////////////////////////////////////////
		// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
		///////////////////////////////////////////////////////////////////////////////

		// This file is a snapshot of an AIDL file. Do not edit it manually. There are
		// two cases:
		// 1). this is a frozen version file - do not edit this in any case.
		// 2). this is a 'current' file. If you make a backwards compatible change to
		// the interface (from the latest frozen version), the build system will
		// prompt you to update this file with `m <name>-update-api`.
		//
		// You must not make a backward incompatible change to any AIDL file built
		// with the aidl_interface module type with versions property set. The module
		// type is used to build AIDL files in a way that they can be used across
		// independently updatable components of the system. If a device is shipped
		// with such a backward incompatible change, it has a high risk of breaking
		// later when a module using the interface is updated, e.g., Mainline modules.

		package android.hardware.contexthub;
		@VintfStability
		interface IEndpointCommunication {
		void registerEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);
		void unregisterEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);
		int[2] requestSessionIdRange(int size);
		void openEndpointSession(int sessionId, in android.hardware.contexthub.EndpointId destination, in android.hardware.contexthub.EndpointId initiator, in @nullable String serviceDescriptor);
		void sendMessageToEndpoint(int sessionId, in android.hardware.contexthub.Message msg);
		void sendMessageDeliveryStatusToEndpoint(int sessionId, in android.hardware.contexthub.MessageDeliveryStatus msgStatus);
		void closeEndpointSession(int sessionId, in android.hardware.contexthub.Reason reason);
		void endpointSessionOpenComplete(int sessionId);
		void unregister();
		}

contexthub/aidl/android/hardware/contexthub/IContextHub.aidl

+15 −121

Original line number	Diff line number	Diff line
		@@ -18,19 +18,16 @@ package android.hardware.contexthub;

		import android.hardware.contexthub.ContextHubInfo;
		import android.hardware.contexthub.ContextHubMessage;
		import android.hardware.contexthub.EndpointId;
		import android.hardware.contexthub.EndpointInfo;
		import android.hardware.contexthub.HostEndpointInfo;
		import android.hardware.contexthub.HubInfo;
		import android.hardware.contexthub.IContextHubCallback;
		import android.hardware.contexthub.IEndpointCallback;
		import android.hardware.contexthub.Message;
		import android.hardware.contexthub.IEndpointCommunication;
		import android.hardware.contexthub.MessageDeliveryStatus;
		import android.hardware.contexthub.NanSessionStateUpdate;
		import android.hardware.contexthub.NanoappBinary;
		import android.hardware.contexthub.NanoappInfo;
		import android.hardware.contexthub.Reason;
		import android.hardware.contexthub.Service;
		import android.hardware.contexthub.Setting;

		@VintfStability
		@@ -271,125 +268,22 @@ interface IContextHub {
		List<EndpointInfo> getEndpoints();

		/**
		* Publishes an endpoint from the calling side (e.g. Android). Endpoints must be registered
		* prior to starting a session.
		*/
		void registerEndpoint(in EndpointInfo endpoint);

		/**
		* Teardown an endpoint from the calling side (e.g. Android). This endpoint must have already
		* been published via registerEndpoint().
		*/
		void unregisterEndpoint(in EndpointInfo endpoint);

		/**
		* Attaches a callback interface to receive events targeted at endpoints registered by the
		* caller.
		*/
		void registerEndpointCallback(in IEndpointCallback callback);

		/**
		* Request a range of session IDs for the caller to use when initiating sessions. This may be
		* called more than once, but typical usage is to request a large enough range to accommodate
		* the maximum expected number of concurrent sessions, but not overly large as to limit other
		* clients.
		* Registers a new hub for endpoint communication which will receive events for its endpoints
		* over the given callback. Returns an interface for the hub to register endpoints, start
		* sessions, and send messages.
		*
		* @param size The number of sessionId reserved for host-initiated sessions. This number should
		* be less than or equal to 1024.
		*
		* @return An array with two elements representing the smallest and largest possible session id
		* available for host.
		*
		* @throws EX_ILLEGAL_ARGUMENT if the size is invalid.
		* @throws EX_SERVICE_SPECIFIC if the id range requested cannot be allocated.
		*/
		int[2] requestSessionIdRange(int size);

		/**
		* Request to open a session for communication between an endpoint previously registered by the
		* caller and a target endpoint found in getEndpoints(), optionally scoped to a service
		* published by the target endpoint.
		*
		* Upon returning from this function, the session is in pending state, and the final result will
		* be given by an asynchronous call to onEndpointSessionOpenComplete() on success, or
		* onCloseEndpointSession() on failure.
		*
		* @param sessionId Caller-allocated session identifier, which must be unique across all active
		* sessions, and must fall in a range allocated via requestSessionIdRange().
		* @param destination The EndpointId representing the destination side of the session.
		* @param initiator The EndpointId representing the initiating side of the session, which
		* must've already been published through registerEndpoint().
		* @param serviceDescriptor Descriptor for the service specification for scoping this session
		* (nullable). Null indicates a fully custom marshalling scheme. The value should match
		* a published descriptor for both destination and initiator.
		*
		* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
		* arguments is invalid.
		* @throws EX_SERVICE_SPECIFIC on other errors
		* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
		*/
		void openEndpointSession(int sessionId, in EndpointId destination, in EndpointId initiator,
		in @nullable String serviceDescriptor);

		/**
		* Send a message from one endpoint to another on the (currently open) session.
		* It is valid for the same callback to be registered for multiple hubs, as the
		* IEndpointCallback events provide sufficient information to determine which hub the event is
		* intended for:
		* * session ids are allocated to a specific hub and are unique
		* * endpoints are identified by hub and endpoint id
		*
		* @param sessionId The integer representing the communication session, previously set in
		* openEndpointSession() or onEndpointSessionOpenRequest().
		* @param msg The Message object representing a message to endpoint from the endpoint on host.
		* @param callback Interface to send endpoint events targeting the caller
		* @param hubInfo Details of the hub being registered
		* @return Interface for the hub to interact with other endpoint hubs
		*
		* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
		* arguments is invalid.
		* @throws EX_SERVICE_SPECIFIC on other errors
		* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
		*/
		void sendMessageToEndpoint(int sessionId, in Message msg);

		/**
		* Sends a message delivery status to the endpoint in response to receiving a Message with flag
		* FLAG_REQUIRES_DELIVERY_STATUS. Each message with the flag should have a MessageDeliveryStatus
		* response. This method sends the message delivery status back to the remote endpoint for a
		* session.
		*
		* @param sessionId The integer representing the communication session, previously set in
		* openEndpointSession() or onEndpointSessionOpenRequest().
		* @param msgStatus The MessageDeliveryStatus object representing the delivery status for a
		* specific message (identified by the sequenceNumber) within the session.
		*
		* @throws EX_UNSUPPORTED_OPERATION if ContextHubInfo.supportsReliableMessages is false for
		* the hub involved in this session.
		*/
		void sendMessageDeliveryStatusToEndpoint(int sessionId, in MessageDeliveryStatus msgStatus);

		/**
		* Closes a session previously opened by openEndpointSession() or requested via
		* onEndpointSessionOpenRequest(). Processing of session closure must be ordered/synchronized
		* with message delivery, such that if this session was open, any messages previously passed to
		* sendMessageToEndpoint() that are still in-flight must still be delivered before the session
		* is closed. Any in-flight messages to the endpoint that requested to close the session will
		* not be delivered.
		*
		* @param sessionId The integer representing the communication session, previously set in
		* openEndpointSession() or onEndpointSessionOpenRequest().
		* @param reason The reason for this close endpoint session request.
		*
		* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
		* arguments is invalid.
		* @throws EX_SERVICE_SPECIFIC on other errors
		* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
		*/
		void closeEndpointSession(int sessionId, in Reason reason);

		/**
		* Notifies the HAL that the session requested by onEndpointSessionOpenRequest is ready to use.
		*
		* @param sessionId The integer representing the communication session, previously set in
		* onEndpointSessionOpenRequest(). This id is assigned by the HAL.
		*
		* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
		* arguments is invalid.
		* @throws EX_SERVICE_SPECIFIC on other errors
		* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
		* @throws EX_ILLEGAL_STATE if hubInfo.hubId has already been registered
		*/
		void endpointSessionOpenComplete(int sessionId);
		@PropagateAllowBlocking
		IEndpointCommunication registerEndpointHub(in IEndpointCallback callback, in HubInfo hubInfo);
		}

contexthub/aidl/android/hardware/contexthub/IEndpointCommunication.aidl

0 → 100644

+152 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2024 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.contexthub;

		import android.hardware.contexthub.EndpointId;
		import android.hardware.contexthub.EndpointInfo;
		import android.hardware.contexthub.IEndpointCallback;
		import android.hardware.contexthub.Message;
		import android.hardware.contexthub.MessageDeliveryStatus;
		import android.hardware.contexthub.Reason;
		import android.hardware.contexthub.Service;

		@VintfStability
		interface IEndpointCommunication {
		/**
		* Publishes an endpoint from the calling side (e.g. Android). Endpoints must be registered
		* prior to starting a session.
		*/
		void registerEndpoint(in EndpointInfo endpoint);

		/**
		* Teardown an endpoint from the calling side (e.g. Android). This endpoint must have already
		* been published via registerEndpoint().
		*/
		void unregisterEndpoint(in EndpointInfo endpoint);

		/**
		* Request a range of session IDs for the caller to use when initiating sessions. This may be
		* called more than once, but typical usage is to request a large enough range to accommodate
		* the maximum expected number of concurrent sessions, but not overly large as to limit other
		* clients.
		*
		* @param size The number of sessionId reserved for host-initiated sessions. This number should
		* be less than or equal to 1024.
		*
		* @return An array with two elements representing the smallest and largest possible session id
		* available for host.
		*
		* @throws EX_ILLEGAL_ARGUMENT if the size is invalid.
		* @throws EX_SERVICE_SPECIFIC if the id range requested cannot be allocated.
		*/
		int[2] requestSessionIdRange(int size);

		/**
		* Request to open a session for communication between an endpoint previously registered by the
		* caller and a target endpoint found in getEndpoints(), optionally scoped to a service
		* published by the target endpoint.
		*
		* Upon returning from this function, the session is in pending state, and the final result will
		* be given by an asynchronous call to onEndpointSessionOpenComplete() on success, or
		* onCloseEndpointSession() on failure.
		*
		* @param sessionId Caller-allocated session identifier, which must be unique across all active
		* sessions, and must fall in a range allocated via requestSessionIdRange().
		* @param destination The EndpointId representing the destination side of the session.
		* @param initiator The EndpointId representing the initiating side of the session, which
		* must've already been published through registerEndpoint().
		* @param serviceDescriptor Descriptor for the service specification for scoping this session
		* (nullable). Null indicates a fully custom marshalling scheme. The value should match
		* a published descriptor for both destination and initiator.
		*
		* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
		* arguments is invalid.
		* @throws EX_SERVICE_SPECIFIC on other errors
		* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
		*/
		void openEndpointSession(int sessionId, in EndpointId destination, in EndpointId initiator,
		in @nullable String serviceDescriptor);

		/**
		* Send a message from one endpoint to another on the (currently open) session.
		*
		* @param sessionId The integer representing the communication session, previously set in
		* openEndpointSession() or onEndpointSessionOpenRequest().
		* @param msg The Message object representing a message to endpoint from the endpoint on host.
		*
		* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
		* arguments is invalid.
		* @throws EX_SERVICE_SPECIFIC on other errors
		* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
		*/
		void sendMessageToEndpoint(int sessionId, in Message msg);

		/**
		* Sends a message delivery status to the endpoint in response to receiving a Message with flag
		* FLAG_REQUIRES_DELIVERY_STATUS. Each message with the flag should have a MessageDeliveryStatus
		* response. This method sends the message delivery status back to the remote endpoint for a
		* session.
		*
		* @param sessionId The integer representing the communication session, previously set in
		* openEndpointSession() or onEndpointSessionOpenRequest().
		* @param msgStatus The MessageDeliveryStatus object representing the delivery status for a
		* specific message (identified by the sequenceNumber) within the session.
		*
		* @throws EX_UNSUPPORTED_OPERATION if ContextHubInfo.supportsReliableMessages is false for
		* the hub involved in this session.
		*/
		void sendMessageDeliveryStatusToEndpoint(int sessionId, in MessageDeliveryStatus msgStatus);

		/**
		* Closes a session previously opened by openEndpointSession() or requested via
		* onEndpointSessionOpenRequest(). Processing of session closure must be ordered/synchronized
		* with message delivery, such that if this session was open, any messages previously passed to
		* sendMessageToEndpoint() that are still in-flight must still be delivered before the session
		* is closed. Any in-flight messages to the endpoint that requested to close the session will
		* not be delivered.
		*
		* @param sessionId The integer representing the communication session, previously set in
		* openEndpointSession() or onEndpointSessionOpenRequest().
		* @param reason The reason for this close endpoint session request.
		*
		* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
		* arguments is invalid.
		* @throws EX_SERVICE_SPECIFIC on other errors
		* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
		*/
		void closeEndpointSession(int sessionId, in Reason reason);

		/**
		* Notifies the HAL that the session requested by onEndpointSessionOpenRequest is ready to use.
		*
		* @param sessionId The integer representing the communication session, previously set in
		* onEndpointSessionOpenRequest(). This id is assigned by the HAL.
		*
		* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
		* arguments is invalid.
		* @throws EX_SERVICE_SPECIFIC on other errors
		* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
		*/
		void endpointSessionOpenComplete(int sessionId);

		/**
		* Unregisters this hub. Subsequent calls on this interface will fail.
		*
		* @throws EX_ILLEGAL_STATE if this interface was already unregistered.
		*/
		void unregister();
		}

contexthub/aidl/default/ContextHub.cpp

+75 −26

File changed.

Preview size limit exceeded, changes collapsed.