struct ara::com::FindServiceHandle

The structure ara::com::FindServiceHandle serves as a unique control token for controlling service monitoring running in the background (AUTOSAR_AP_EXP_ARAComAPI p. 34). Because the default constructor is deleted ([SWS_CM_00353]), the handle is created exclusively by StartFindService and, after receipt of asynchronous status callbacks, enables terminating the search specifically via StopFindService (AUTOSAR_AP_EXP_ARAComAPI p. 30). Supported comparison operators also ensure the storable management of multiple search requests in standard containers ([SWS_CM_11526], [SWS_CM_11527]).

more ›

Context

The structure ara::com::FindServiceHandle functions in module com of the Adaptive Platform as a unique identifier and control token for an asynchronous, continuous service search. While a synchronous query via FindService determines matching service instances on a one-off basis and returns handle containers directly, StartFindService initiates permanent monitoring of service availability in the background (AUTOSAR_AP_EXP_ARAComAPI p. 34). Typically, the application instance, the type-specific proxy class (for example RadarServiceProxy), and a user-defined callback function of type FindServiceHandler are involved in this process (AUTOSAR_AP_EXP_ARAComAPI p. 30). The concrete internal representation of ara::com::FindServiceHandle is designed specifically for the implementation of the respective Communication Management, but provides standardized C++ interfaces for handling.

Lifecycle

The lifecycle of a ara::com::FindServiceHandle is tightly coupled to the active search process in Communication Management:

• Creation: The default constructor is explicitly deleted ([SWS_CM_00353]). An application thus cannot create handle instances uninitialized or arbitrarily. Instead, a valid handle is generated exclusively as the payload of a ara::core::Result by the static method StartFindService (AUTOSAR_AP_EXP_ARAComAPI p. 30).
• Management and ownership: A handle supports assignment via the copy assignment operator [SWS_CM_11528]. To enable the application to store and organize multiple search requests in standard containers (such as ordered sets or associative maps), the type satisfies the C++ concepts [equalitycomparable] and [lessthancomparable] via the operators operator== ([SWS_CM_11526]) and operator< ([SWS_CM_11527]).
• Termination and destruction: The handle retains its validity as long as background monitoring is active. Terminating the search is carried out by passing the handle to StopFindService (AUTOSAR_AP_EXP_ARAComAPI p. 30, AUTOSAR_AP_EXP_ARAComAPI p. 34). After this call, the handle no longer represents an ongoing search process.

Usage Path

The regular sequence comprises registering the search request, continuously receiving availability updates, and orderly stopping the monitoring process:

1. Search start: The application registers a FindServiceHandler via StartFindService to be informed about newly available or discontinued service instances (AUTOSAR_AP_EXP_ARAComAPI p. 30, AUTOSAR_AP_EXP_ARAComAPI p. 34).
2. Handle receipt: Upon a successful start, the call returns an ara::core::Result with the FindServiceHandle (AUTOSAR_AP_EXP_ARAComAPI p. 30), which the application retains for later control calls.
3. Asynchronous notification: Communication Management executes the background search and invokes the provided handler upon status changes (AUTOSAR_AP_EXP_ARAComAPI p. 34).
4. Search stop: As soon as the instances have been found or monitoring is no longer required, the application passes the handle to StopFindService (AUTOSAR_AP_EXP_ARAComAPI p. 30, AUTOSAR_AP_EXP_ARAComAPI p. 34).

Sequence diagram: Typical sequence of asynchronous service discovery from registration via notifications to termination via FindServiceHandle. Sources: AUTOSAR_AP_EXP_ARAComAPI p. 30, AUTOSAR_AP_EXP_ARAComAPI p. 34.

Error Scenarios

When using ara::com::FindServiceHandle, the following system-specific boundary conditions must be observed:

• Failed search start: If technical bindings are not available or the service deployment configuration is faulty (AUTOSAR_AP_EXP_ARAComAPI p. 34), StartFindService fails. In this case, the returned ara::core::Result does not contain a valid handle, but an error code (AUTOSAR_AP_EXP_ARAComAPI p. 30).
• Exception safety: The implemented comparison and assignment operators operator== ([SWS_CM_11526]), operator< ([SWS_CM_11527]), and operator= ([SWS_CM_11528]) are explicitly declared in the specification as not exception safe (not exception safe).
• Multiple stops: A repeated call to StopFindService with the same handle is presumed to have no effect or lead to a runtime error, since the underlying monitoring activity has already been removed. Question Q-f44130c33fa1caea (open)