Snap for 13258483 from f110c31a56459e11e0ba4164e24a2e3dbbd5ab9a to 25Q2-release
Change-Id: Ied04aa78eee998eda31b2fba5a48c3428d0466d1
diff --git a/chre_api/include/chre_api/chre/msg.h b/chre_api/include/chre_api/chre/msg.h
index da4e3f4..f02fd40 100644
--- a/chre_api/include/chre_api/chre/msg.h
+++ b/chre_api/include/chre_api/chre/msg.h
@@ -22,32 +22,65 @@
/**
* @file
- * Context Hub Runtime Environment API dealing with generic endpoint messages.
- *
- * These APIs are used to send and receive messages to and from generic
- * endpoints. This API is a single interface to nanoapps to communicate with
- * other nanoapps (endpoints of CHRE), other embedded endpoints, or host
+ * Context Hub Runtime Environment API for session-based messaging with generic
* endpoints.
*
- * Nanoapps should use these APIs to communicate with other nanoapps, local
- * endpoints, or host endpoints instead of chreSendEvent() or any other
- * messaging APIs if they do not need to support Android versions prior to
- * Android 16 nor CHRE APIs older than v1.11.
+ * Key concepts:
+ * - **Endpoint**: an entity in the system that can send and receive messages.
+ * Example endpoints include nanoapps, other offload components outside of
+ * CHRE, privileged Android applications or Android system components
+ * (registered via the ContextHubManager.registerEndpoint() API), vendor
+ * processes (e.g. HALs) registered with the Context Hub HAL, etc.
+ * - **Message**: a datagram sent over a session.
+ * - **Session**: an active connection between two endpoints, optionally scoped
+ * to a specific service. All messages must be sent over an established
+ * session. A session will be automatically closed if sending a message fails
+ * or the remote endpoint otherwise disconnects.
+ * - **Service**: a defined interface and wire format associated with some
+ * functionality. Endpoints can choose to not register any services, for
+ * example in cases where the endpoint only functions as a client, or if its
+ * interface is implied and internal (e.g. a nanoapp that is tightly coupled
+ * with its host-side code). Endpoints may also register 1 or more services,
+ * and multiple endpoints may register the same service. This enables
+ * abstraction between the interface/functionality and the entity/endpoint
+ * that implements it.
*
- * This API uses sessions to organize groups of messages between endpoints.
- * Sessions are created when an endpoint is connected to another endpoint and
- * represent an active connection between the endpoints. Messages are sent
- * between endpoints using the session ID. A session will be automatically
- * closed if an error occurs or an endpoint disconnects.
+ * This API provides a single interface for nanoapps to communicate with other
+ * parts of the system, regardless of location. Nanoapps should use these APIs
+ * rather than chreSendEvent(), chreSendMessageToHostEndpoint(), and related
+ * APIs if they do not need to support Android versions prior to Android 16 nor
+ * CHRE APIs older than v1.11.
*
- * The general order of API usage is:
+ * The general order of API usage as a client (session initiator) is:
*
- * 1. Use one of the query APIs to find an endpoint to communicate with. The
- * nanoapp may also know the message hub ID and endpoint ID of the endpoint
- * it wants to communicate with.
- * 2. chreMsgSessionOpenAsync() - to open a session with an endpoint.
- * 3. chreMsgSend() - to send a message to an endpoint.
- * 4. chreMsgSessionCloseAsync() - to close a session with an endpoint.
+ * 1. The nanoapp should know the target service and/or endpoint ID it wants to
+ * interact with, and optionally the target hub ID, and provide this to
+ * chreMsgConfigureEndpointReadyEvents() or
+ * chreMsgConfigureServiceReadyEvents().
+ * 2. The nanoapp will receive an event when a suitable endpoint is found. The
+ * nanoapp then calls chreMsgSessionOpenAsync() to initiate communication.
+ * 3. Once the session is established, the nanoapp receives a
+ * CHRE_EVENT_MSG_SESSION_OPENED event. If a failure occurred or the target
+ * endpoint did not accept the session, a CHRE_EVENT_MSG_SESSION_CLOSED event
+ * will be provided instead.
+ * 4. Assuming the session was opened successfully, the nanoapp can now send
+ * messages over the session using chreMsgSend() and will receive messages
+ * via CHRE_EVENT_MSG_FROM_ENDPOINT.
+ * 5. The session may be left open indefinitely, or closed by either endpoint,
+ * or by the system on error or if one endpoint crashes/disconnects. If the
+ * target endpoint crashes and then recovers, a new ready event will be
+ * generated and communication can resume at step 2.
+ *
+ * As a server (session responder), the high-level flow is:
+ *
+ * 1. (Optional) Register one or more services via chreMsgPublishServices().
+ * 2. The nanoapp receives CHRE_EVENT_MSG_SESSION_OPENED when another endpoint
+ * initiates a session. The session can either be used immediately, or the
+ * nanoapp can use chreMsgSessionCloseAsync() to reject the session.
+ * 3. Once a session is established, it functions the same regardless of which
+ * endpoint initiated the session.
+ *
+ * @since v1.11
*/
#include <stdbool.h>
@@ -134,7 +167,7 @@
#define CHRE_MSG_MAX_NAME_LEN (51)
/**
- * The maximum length of a service descriptor.
+ * The maximum length of a service descriptor (including null terminator).
*/
#define CHRE_MSG_MAX_SERVICE_DESCRIPTOR_LEN (128)
@@ -401,25 +434,24 @@
struct chreMsgEndpointInfo *info);
/**
- * Configures whether this nanoapp will receive updates regarding an
- * endpoint that is connected with a message hub and a specific service.
- * The hubId can be CHRE_MSG_HUB_ID_ANY to configure notifications
- * for all endpoints that are connected with any message hub. The endpoint ID
- * can be CHRE_MSG_ENDPOINT_ID_ANY to configure notifications for all
- * endpoints that match the given hub.
+ * Configures whether this nanoapp will receive updates regarding an endpoint
+ * that is connected with a message hub and a specific service. The hubId can
+ * be CHRE_MSG_HUB_ID_ANY to configure notifications for matching endpoints that
+ * are connected with any message hub. The endpoint ID can be
+ * CHRE_MSG_ENDPOINT_ID_ANY to configure notifications for all endpoints that
+ * match the given hub.
*
- * If this API succeeds, the nanoapp will receive endpoint
- * notifications, via the CHRE_EVENT_MSG_ENDPOINT_READY event with an
- * eventData of type chreMsgEndpointReadyEvent.
+ * If this API succeeds, the nanoapp will receive endpoint notifications via
+ * CHRE_EVENT_MSG_ENDPOINT_READY with chreMsgEndpointReadyEvent.
*
* If one or more endpoints matching the filter are already ready when this
* function is called, CHRE_EVENT_MSG_ENDPOINT_READY will be immediately
* posted to this nanoapp.
*
* @param hubId The message hub ID of the endpoint for which to configure
- * notifications for all endpoints that are connected with any message hub.
+ * notifications for all endpoints that are connected with any message hub.
* @param endpointId The endpoint ID of the endpoint for which to configure
- * notifications.
+ * notifications.
* @param enable true to enable notifications.
*
* @return true on success
@@ -430,30 +462,27 @@
bool enable);
/**
- * Configures whether this nanoapp will receive updates regarding all
- * endpoints that are connected with the message hub that provide the specified
- * service.
+ * Configures whether this nanoapp will receive updates regarding all endpoints
+ * that are connected with the message hub that provide the specified service.
*
- * If this API succeeds, the nanoapp will receive endpoint
- * notifications, via the CHRE_EVENT_MSG_SERVICE_READY event
- * with an eventData of type chreMsgServiceReadyEvent.
+ * If this API succeeds, the nanoapp will receive endpoint notifications via
+ * CHRE_EVENT_MSG_SERVICE_READY with chreMsgServiceReadyEvent.
*
* If one or more endpoints matching the filter are already ready when this
- * function is called, CHRE_EVENT_MSG_SERVICE_READY will be
- * immediately posted to this nanoapp.
+ * function is called, CHRE_EVENT_MSG_SERVICE_READY will be immediately posted
+ * to this nanoapp.
*
* @param hubId The message hub ID of the endpoint for which to configure
- * notifications for all endpoints that are connected with any message hub.
+ * notifications for all endpoints that are connected with any message hub.
* @param serviceDescriptor The descriptor of the service associated with the
- * endpoint for which to configure notifications, a null-terminated ASCII
- * string. If not NULL, the underlying memory must outlive the notifications
- * configuration. If NULL, this will return false.
+ * endpoint for which to configure notifications, a null-terminated ASCII
+ * string. If not NULL, the underlying memory must outlive the notifications
+ * configuration. If NULL, this will return false.
* @param enable true to enable notifications.
*
* @return true on success
*
* @see chreMsgConfigureEndpointReadyEvents
- *
* @since v1.11
*/
bool chreMsgConfigureServiceReadyEvents(uint64_t hubId,
@@ -461,13 +490,11 @@
bool enable);
/**
- * Retrieves metadata for a given session ID. Sessions represent an active
- * connection between a nanoapp and an endpoint. The nanoapp will use this
- * session ID to send messages to the endpoint.
+ * Retrieves metadata for a currently active session ID.
*
* If the given session ID is not associated with a valid session or if the
- * caller nanoapp is not a participant in the session, this method
- * will return false and info will not be populated.
+ * caller nanoapp is not a participant in the session, this method will return
+ * false and info will not be populated.
*
* @param sessionId The session ID of the session for which to get info.
* @param info The non-null pointer to where the metadata will be stored.
@@ -479,17 +506,16 @@
bool chreMsgSessionGetInfo(uint16_t sessionId, struct chreMsgSessionInfo *info);
/**
- * Publishes services from this nanoapp.
+ * Publishes services exposed by this nanoapp, which will be included with the
+ * endpoint metadata visible to other endpoints in the system.
*
- * When this API is invoked, the list of services will be provided to
- * host applications and endpoints interacting with the nanoapp.
- *
- * This function must be invoked from nanoappStart(), to guarantee stable output
- * of the list of services supported by the nanoapp.
+ * This function must be invoked from nanoappStart(), which ensures stable
+ * output of the list of services supported by the nanoapp. Calls made outside
+ * of nanoappStart() will have no effect.
*
* Although nanoapps are recommended to only call this API once with all
- * services it intends to publish, if it is called multiple times, each
- * call will append to the list of published services.
+ * services it intends to publish, if called multiple times, each call will
+ * append to the list of published services.
*
* The implementation must allow for a nanoapp to publish at least
* CHRE_MSG_MINIMUM_SERVICE_LIMIT services and at most UINT8_MAX services. If
@@ -498,7 +524,7 @@
*
* @param services A non-null pointer to the list of services to publish.
* @param numServices The number of services to publish, i.e. the length of the
- * services array.
+ * services array.
*
* @return true if the publishing is successful.
*
@@ -510,23 +536,29 @@
/**
* Opens a session with an endpoint.
*
- * The nanoapp will receive a CHRE_EVENT_MSG_SESSION_OPENED event or a
- * CHRE_EVENT_MSG_SESSION_CLOSED event upon the response from the other
- * hub and endpoint. The event may have a session ID of UINT16_MAX if the
- * session could not be opened before sending any request to the other hub and
- * endpoint, i.e. if the given message hub ID and endpoint ID are not associated
- * with a valid endpoint.
+ * If this function returns true, the result of session initiation will be
+ * provided by a CHRE_EVENT_MSG_SESSION_OPENED or CHRE_EVENT_MSG_SESSION_CLOSED
+ * event containing the same hub ID, endpoint ID, and service descriptor
+ * parameters. Nanoapps may only open one session for each unique combination of
+ * parameters.
*
- * @param hubId The message hub ID of the endpoint. Can be
- * CHRE_MSG_HUB_ID_ANY to open a session with the default endpoint.
+ * @param hubId The message hub ID of the endpoint. Can be CHRE_MSG_HUB_ID_ANY
+ * to open a session with the default endpoint.
* @param endpointId The endpoint ID of the endpoint. Can be
- * CHRE_MSG_ENDPOINT_ID_ANY to open a session with a specified service. The
- * service cannot be NULL in this case.
+ * CHRE_MSG_ENDPOINT_ID_ANY to open a session with a specified service. The
+ * service cannot be NULL in this case.
* @param serviceDescriptor The descriptor of the service associated with the
- * endpoint with which to open the session, a null-terminated ASCII
- * string. Can be NULL. The underlying memory must outlive the session.
+ * endpoint with which to open the session, a null-terminated ASCII string.
+ * Can be NULL. The underlying memory must remain valid at least until the
+ * session is closed - for example, it should be a pointer to a static const
+ * variable hard-coded in the nanoapp.
+ * NOTE: as event data supplied to nanoapps does not live beyond the
+ * nanoappHandleEvent() invocation, it is NOT valid to use the serviceData
+ * array provided inside chreMsgServiceReadyEvent here.
*
- * @return whether the request was successfully processed.
+ * @return true if the request was successfully dispatched, or false if a
+ * synchronous error occurred, in which case no subsequent event will be
+ * sent.
*
* @since v1.11
*/
@@ -537,34 +569,67 @@
* Closes a session with an endpoint.
*
* If the given session ID is not associated with a valid session or if the
- * caller nanoapp is not a participant in the session, this method
- * will return false.
+ * calling nanoapp is not a participant in the session, this method will return
+ * false.
*
- * The nanoapp will receive a CHRE_EVENT_MSG_SESSION_CLOSED event upon
- * successful closure of the session.
+ * The nanoapp will receive a CHRE_EVENT_MSG_SESSION_CLOSED event when the
+ * session teardown is complete. The session is immediately unavailable for
+ * sending. It is unspecified whether any in-flight messages sent by the
+ * other endpoint will be received prior to CHRE_EVENT_MSG_SESSION_CLOSED, but
+ * once this event is delivered, no further data will be received.
*
- * @param sessionId The session ID of the session to close.
+ * @param sessionId ID of the session to close.
*
- * @return true if the session was successfully closed.
+ * @return true if the session closure process was initiated.
*
* @since v1.11
*/
bool chreMsgSessionCloseAsync(uint16_t sessionId);
/**
- * Send a reliable message to an endpoint.
+ * Send a message to an endpoint over an active session.
*
- * This function is similar to sending a reliable message using
- * chreSendReliableMessageAsync() with the difference that the message can be
- * sent to any registered endpoint and the nanoapp will not receive the
- * CHRE_EVENT_RELIABLE_MSG_ASYNC_RESULT event. Instead, when the message is
- * successfully processed by the receiving message hub and endpoint, the
- * freeCallback will be invoked. If the receiving message hub sends the message
- * further, i.e. in the case of the host message hub, if the message will be
- * sent reliably. A failure in reliable message delivery will be indicated
- * by the corresponding session closing.
+ * This is similar to the stateless host message APIs, such as
+ * chreSendMessageWithPermissions(), but it supports sending data to an
+ * arbitrary endpoint, which could be a host app, another nanoapp, or something
+ * else.
*
- * @see chreSendReliableMessageAsync
+ * Messages are guaranteed to be delivered in the order they were sent. If an
+ * error occurs while attempting to deliver the message, the session will be
+ * closed by the system with a suitable reason provided in the data sent with
+ * CHRE_EVENT_MSG_SESSION_CLOSED. While this covers most scenarios, no explicit
+ * end-to-end acknowledgement is provided, and any internal timeouts and/or
+ * retries are implementation-dependent. Similar to chreMsgSessionCloseAsync(),
+ * if the session is closed by the other endpoint or system, it is unspecified
+ * whether any in-flight messages were delivered. The option to send reliable
+ * messages over a socket is planned for a future release. In the meantime, if
+ * full reliability is desired for host communication, use
+ * chreSendReliableMessageAsync().
+ *
+ * @param message Pointer to a block of memory to send to the other endpoint in
+ * this session. NULL is acceptable only if messageSize is 0. This function
+ * transfers ownership of the provided memory to the system, so the data
+ * must stay valid and unmodified until freeCallback is invoked.
+ * @param messageSize The size, in bytes, of the given message. Maximum allowed
+ * size for the destination endpoint is provided in chreMsgEndpointInfo.
+ * @param messageType An opaque value passed along with the message payload,
+ * using an application/service-defined scheme.
+ * @param sessionId The session over which to send this message, which also
+ * implicitly identifies the destination service (if used), endpoint, and
+ * hub. Provided in chreMsgSessionInfo.
+ * @param messagePermissions Bitmask of permissions that must be held to receive
+ * this message, and will be attributed to the recipient. Primarily relevant
+ * when the destination endpoint is an Android application. Refer to
+ * CHRE_MESSAGE_PERMISSIONS.
+ * @param freeCallback Invoked when the system no longer needs the memory
+ * holding the message. Note that this does not necessarily mean that the
+ * message has been delivered. If message is non-NULL, this must be
+ * non-NULL, and if message is NULL, this must be NULL.
+ *
+ * @return true if the message was accepted for transmission, false otherwise.
+ * Note that even if this method returns false, the freeCallback will be
+ * invoked, if non-NULL. In either case, the freeCallback may be invoked
+ * synchronously, so it must not call chreMsgSend() to avoid recursion.
*
* @since v1.11
*/