class <SI-Namespace>::proxy::<SI>Proxy

Usage and Semantics

The static factory method Create serves according to [SWS_CM_10438] for the exception-free creation of a proxy instance (<SI>Proxy) following the named constructor idiom. As parameter handle, it requires a previously determined service handle according to [SWS_CM_00131]. The call is synchronous and declared as noexcept. The result is returned in a ara::core::Result, which contains the operational proxy instance in case of success.

Error handling

If an error occurs during instantiation, Create returns an error code of type ara::com::ComErrc via ara::core::Result [SWS_CM_10438]:

• ComErrc::kServiceNotAvailable: The service is no longer available after previously being offered via OfferService().
• ComErrc::kCommunicationFailure: The network binding reports a recoverable communication error or the failure of a secured connection.

Both errors exhibit rollback semantics [SWS_CM_10438]. For structural or security-related errors, specified violations take effect: If the passed handle is null or corrupted, a ErroneousServiceHandleViolation is present. If the calling process lacks the necessary permissions for the instance under grant enforcement, the request is rejected and treated as InsufficientPermissionsViolation (SWS CommunicationManagement §8 “Security”, [SWS_CM_10438]).

Concurrency and Constraints

Interpretation: Since Create operates synchronously and binds communication resources, the call is likely reentrant for different handles, but should not be executed in time-critical hard real-time loops due to possible network initializations. Question Q-f7ba23670f562788 (open)

The static method FindService of the proxy class serves to synchronously find available service instances based on an ara::com::InstanceIdentifier ([SWS_CM_00122]). The call returns the result immediately as ara::core::Result, which upon successful execution contains an ara::com::ServiceHandleContainer ([SWS_CM_00122]). Depending on the current offering state, this container—typically implemented as ara::core::Vector ([SWS_CM_00304])—can be empty, contain a single instance handle, or comprise multiple handles (ARAComAPI §6.5 “Service Discovery”).

In case of an error, the ara::core::Result returns an error code from ara::com::ComErrc, namely ComErrc::kCommunicationFailure, if the network binding reports a recoverable transmission error or a problem with secure communication ([SWS_CM_00122]). In addition, access is subject to permission checks; insufficient permissions result in a InsufficientPermissionsViolation ([SWS_CM_00122]).

Regarding the sequence and concurrency, the following conditions apply:

• Call context and synchronicity: Since the search is executed immediately, only those instances are found for which OfferService() was previously called on the server side (ARAComAPI §6.5 “Service Discovery”).
• Exception safety and reentrancy: The function is specified as noexcept and is exception-safe ([SWS_CM_00122]). Since the method is static and requires no mutable object state, it is likely reentrant and callable in a thread-safe manner. Question Q-3228cc998c4a737e (open)
• Further processing: Found handles serve to instantiate proxy objects via constructor Proxy(const HandleType &handle) ([SWS_CM_00131]). Alternatively, the overload with ara::core::InstanceSpecifier is available for a model-based search ([SWS_CM_00622]).

According to [SWS_CM_00622], the static function FindService of the proxy class serves for synchronously finding available service instances based on an ara::core::InstanceSpecifier with immediate return (\"immediately returned request\"). A prerequisite for discovery is that the respective service skeleton instance was previously provided via OfferService() (ARAComAPI p. 103 “Figure 6.5: Service Discovery”).

Return Values and Interaction

As a result, the call returns a ara::core::Result with a ara::com::ServiceHandleContainer according to [SWS_CM_00622], which is based on ara::core::Vector by default [SWS_CM_00304]. This container can be empty, contain a single handle, or contain multiple found instances (ARAComAPI p. 103 “Figure 6.5: Service Discovery”). The determined service handles are subsequently passed to the constructor to instantiate the proxy object [SWS_CM_00131]. For an event-driven, asynchronous search with notification, StartFindService is alternatively available [SWS_CM_00623], whereas for instance specifiers the overload from [SWS_CM_00122] is used.

Error Handling and Boundary Conditions

The function is declared as noexcept and considered exception-safe (\"exception safe\") according to [SWS_CM_00622]. In the event of an error, the Result object contains the error code ComErrc::kCommunicationFailure, such as in the case of communication disruptions of the network binding [SWS_CM_00622]. In addition, [SWS_CM_00622] defines model and permission violations such as InstanceSpecifierMappingIntegrityViolation, PortInterfaceMappingViolation, ProcessMappingViolation, InstanceSpecifierAlreadyInUseViolation, and InsufficientPermissionsViolation.

Interpretation: Because of the synchronous and immediate return, the method is likely suitable primarily for initial initialization phases or targeted polling, provided that continuous observation via callback is not required. Question Q-ea5b242a6fe41d20 (open)

use

The explicit constructor <SI>Proxy instantiates the type-specific service proxy class in namespace <SI-Namespace>::proxy [SWS_CM_00131]. Within the proxy-skeleton pattern, this generated object serves on the service consumer side as a local facade that forwards method calls to the actual service implementation ARAComAPI Figure 5.1 “Proxy Skeleton Pattern”.

For construction, a reference to a valid HandleType is passed as a parameter [SWS_CM_00131]. This identifier must previously have been obtained via Service Discovery mechanisms — either synchronously via FindService() [SWS_CM_00122] or asynchronously via the registered callback of StartFindService() [SWS_CM_00123].

Error handling

Construction is not exception safe (not exception safe) [SWS_CM_00131]. If the referenced service cannot be reached, a ara::com::ComException is raised according to ara::com::ComErrc::kServiceNotAvailable [SWS_CM_00131]. Furthermore, the following violations are defined:

• ErroneousServiceHandleViolation: Occurs if the passed HandleType object is null or corrupted [SWS_CM_00131].
• InsufficientPermissionsViolation: Occurs if creation is denied by grant enforcement (Grant Enforcement) [SWS_CM_00131].

Constraints and Lifecycle

For the proxy class, the copy constructor is explicitly deleted (=delete) [SWS_CM_00136]. Passing the instance is permitted exclusively via the move constructor, which is also specified as not exception safe [SWS_CM_00137]. At runtime, following successful creation, communication management automatically updates the transport layer addressing of the existing proxy instance in the background in the event of temporary failure and re-availability of the target service ARAComAPI Figure 6.1 “Auto Updating of Proxy Instance”.

The destructor ~<SI>Proxy () terminates the lifecycle of a service proxy instance and releases the associated local resources [SWS_CM_99444]. A service proxy serves on the consumer side as a local facade for interacting with a potentially remote service implementation and forwards calls ARAComAPI §5.1 “Proxy Skeleton Pattern”. The proxy object is previously instantiated via a resolved service handle [SWS_CM_00131], which was provided via service discovery functions such as FindService [SWS_CM_00122].

The following specifications and boundary conditions apply to the destruction and runtime behavior:

• Lifecycle and semantics: Destruction occurs synchronously upon leaving the scope or upon explicit deletion of the instance. While the copy constructor of the proxy class is deleted [SWS_CM_00136], the object can be moved via move semantics prior to its destruction [SWS_CM_00137].
• Exception safety: The destructor is specified as not exception safe [SWS_CM_99444].
• Preconditions and error behavior: If precondition [SWS_CM_00087] is violated, this results in a DanglingSamplesViolation [SWS_CM_99444]. (Interpretation: Prior to calling the destructor, all sample references or data pointers held by the consumer presumably have to be released in order to prevent invalid references.) Question Q-5488797b732d9be6 (open)
• Interaction: If asynchronous service searches are used, they should be terminated via StopFindService before releasing the usage context if necessary [SWS_CM_00125]. In addition, error handling handlers registered for events, triggers, and fields can be reset in advance [SWS_CM_00105] [SWS_CM_00108] [SWS_CM_00126].

The static method StartFindService [SWS_CM_00123] of the proxy class starts the asynchronous search for service instances based on an ara::com::InstanceIdentifier with registration of a callback handler (ARAComAPI §6.5 “Service Discovery”). A ara::com::FindServiceHandler and the sought ara::com::InstanceIdentifier are passed to the call [SWS_CM_00123].

In case of success, the function returns a ara::core::Result with a ara::com::FindServiceHandle [SWS_CM_00123]. This identifier represents the active search request and is mandatory in order to terminate the monitoring of service availability and subsequent handler invocations later using StopFindService [SWS_CM_00125].

If a communication problem occurs during connection establishment, the method returns the error code ComErrc::kCommunicationFailure in the ara::core::Result [SWS_CM_00123]. If the passed callable instance is invalid or null, this is treated as InvalidHandlerViolation; missing access permissions result in a InsufficientPermissionsViolation [SWS_CM_00123].

As soon as a matching service instance becomes available in the system, communication management calls the registered handler with the corresponding service handles [SWS_CM_00123]. Based on a reported HandleType, the application can create a concrete proxy instance via the named constructor method Create [SWS_CM_10438]. Interpretation: The handler is presumably executed asynchronously in a thread of communication management, which is why access to shared resources in the handler should be thread-safe. Question Q-9dc570d7e65fc808 (open) For searching via a model-based identifier, StartFindService with InstanceSpecifier is alternatively available [SWS_CM_00623].

The static method StartFindService of the proxy class starts the continuous search for service instances based on a modeled ara::core::InstanceSpecifier [SWS_CM_00623]. Upon call, the InstanceSpecifier as well as a callback function of type ara::com::FindServiceHandler are passed [SWS_CM_00623]. As return value, the function returns a ara::core::Result<ara::com::FindServiceHandle> [SWS_CM_00623], which provides a search handle for managing the search upon successful registration.

Error handling is performed via the returned ara::core::Result. If a recoverable communication error or an error of secure communication occurs in the network binding, the result contains the error code ComErrc::kCommunicationFailure [SWS_CM_00623]. In addition, specific violations are specified: InvalidHandlerViolation if the passed handler is invalid or null, InsufficientPermissionsViolation in case of missing permissions due to grant enforcement, as well as modeling violations such as InstanceSpecifierMappingIntegrityViolation or PortInterfaceMappingViolation [SWS_CM_00623].

Regarding concurrency and boundary conditions, the function is declared as noexcept and specified as exception-safe [SWS_CM_00623]. The execution of the registered handler is presumably expected to occur asynchronously by Communication Management as soon as matching service instances are detected in the system. Question Q-79fb3ff78d517714 (open)

In interaction with related interfaces, the following points apply:

• The returned ara::com::FindServiceHandle must be kept in order to stop the ongoing search via StopFindService [SWS_CM_00125] and prevent the receipt of further notifications.
• The handles (HandleType) provided via the callback typically serve to instantiate the proxy object via the factory method Create [SWS_CM_10438].
• As an alternative to searching via an InstanceSpecifier, a search can also be initiated with an ara::com::InstanceIdentifier [SWS_CM_00123].

The method SetServiceStateChangeHandler is used on a proxy instance to register a callback function for monitoring availability changes of the respective service ([SWS_CM_01074], SWS CommunicationManagement §8.3.8.2.4.6 “SetServiceStateChangeHandler(ara::com::ServiceStateHandler)”). Communication Management calls this handler as soon as the service availability state (ServiceState) changes ([SWS_CM_01074]).

A function object of type ara::com::ServiceStateHandler specified as std::function<void(ServiceState)> is passed as a parameter ([SWS_CM_01072]). The function has no return value. An already registered handler may be overwritten at runtime by calling again ([SWS_CM_01074]).

Regarding error handling, the function is declared exception-safe (noexcept) ([SWS_CM_01074]). If the passed callable does not exist or is null, the violation InvalidHandlerViolation is present ([SWS_CM_01074]).

Regarding the execution environment, [SWS_CM_01074] represents the base interface. Since no executor can be passed here, the callback is likely executed in the internal thread context of Communication Management. Question Q-7833435e7aa1da9f (open) If execution in a specific application context is required, the overloaded template variant with a executor according to [SWS_CM_01076] is available as an alternative (SWS CommunicationManagement §8.3.8.2.4.5 “SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)”).

Usage and Call Context

The template method SetServiceStateChangeHandler serves to register a callback on the generated proxy class <SI-Namespace>::proxy::<SI>Proxy for monitoring service availability [SWS_CM_01076]. The function takes two parameters AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.5 “SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)”:

• handler: A functor of type ara::com::ServiceStateHandler (defined as std::function<void(ServiceState)>) that is called on every change of the availability status [SWS_CM_01072], [SWS_CM_01074].
• executor: An execution context of template type ExecutorT according to [SWS_CM_11360], in which the registered handler is executed [SWS_CM_01076].

The function has no return value (void) [SWS_CM_01076].

Error Handling and Exception Safety

The function is declared as noexcept and specified as exception safe [SWS_CM_01076]. If the passed callable handler does not exist or is null, a InvalidHandlerViolation is triggered [SWS_CM_01076].

Concurrency and Limitations

A registered handler can be overwritten at runtime [SWS_CM_01074]. Because execution takes place via the passed executor object [SWS_CM_01076], the notification is presumably processed asynchronously in the thread or dispatch context provided by the user. Question Q-349c5224c3b9cc20 (open)

Interaction

The method extends the elementary variant [SWS_CM_01074] with the explicit specification of the execution context [SWS_CM_01076]. Header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h is required for inclusion, whereas the handler type originates from ara/com/types.h [SWS_CM_01072].

The static template method StartFindService starts the asynchronous background monitoring for finding instances of a service based on an ara::com::InstanceIdentifier ([SWS_CM_11352], EXP_ARAComAPI §5.3.3 “Proxy Class API’s”). In addition to the target instance (instance according to [SWS_CM_00122]), a callback function (handler according to [SWS_CM_00123]) and an execution context (executor of template type ExecutorT according to [SWS_CM_11360]) are registered ([SWS_CM_11352]). The callback notifications are likely processed in the thread or task context of the passed executor ([SWS_CM_11352]). Question Q-1db520123c1e49a4 (open)

As return value, the call delivers a ara::com::FindServiceHandle ([SWS_CM_11352]). This handle identifies the running search activity and is required to explicitly terminate the background activity later via [SWS_CM_00125] (StopFindService) (EXP_ARAComAPI §5.3.3 “Proxy Class API’s”). Service handles (HandleType) received via the registered callback subsequently serve to construct the associated proxy instances ([SWS_CM_00131]).

The function is declared as noexcept and specified as exception safe (exception safe) ([SWS_CM_11352]). The following runtime violations (Violations) are defined:

• InvalidHandlerViolation: Occurs if the passed handler function is invalid or corresponds to null ([SWS_CM_11352]).
• InsufficientPermissionsViolation: Occurs if access is denied by the authorization system (Grant Enforcement) ([SWS_CM_11352]).

If a service is instead to be searched via a model-based ara::core::InstanceSpecifier, the function variant [SWS_CM_11365] is alternatively available.

The static template function StartFindService starts the continuous, asynchronous search for service instances based on an ara::core::InstanceSpecifier while registering a notification handler in a passed execution context [SWS_CM_11365]. In contrast to synchronous one-time searches, it initiates a background activity to monitor service availability and returns a ara::com::FindServiceHandle EXP_ARAComAPI §5.3 “Proxy Class APIs”.

Parameters and execution

The function accepts three parameters [SWS_CM_11365]:

• handler: Callback function of type ara::com::FindServiceHandler according to [SWS_CM_00123], which is called upon changes in instance availability.
• instance: The ara::core::InstanceSpecifier to search for according to [SWS_CM_00123].
• executor: An execution context of template type ExecutorT according to [SWS_CM_11360]. Interpretation: The template argument ExecutorT is likely to determine in which thread or task context the registered callback is executed. Question Q-6d46f67d536a391e (open)

Error Handling and Boundary Conditions

The signature is declared as noexcept and specified as exception safe [SWS_CM_11365]. From a specification standpoint, functional violations (Violations) are defined: InstanceSpecifierMappingIntegrityViolation (resolution in executable context failed or no PortPrototype), PortInterfaceMappingViolation and ProcessMappingViolation (mismatched PortInterface mappings), InstanceSpecifierAlreadyInUseViolation, InvalidHandlerViolation (invalid or non-existent handler), and InsufficientPermissionsViolation in case of missing access permission [SWS_CM_11365].

Interaction

The received FindServiceHandle serves to terminate the running background monitoring in a controlled manner by passing it to StopFindService [SWS_CM_00125]. The handles reported to the handler are used to instantiate concrete service proxies via Proxy(handle) [SWS_CM_00131]. For searches using ara::com::InstanceIdentifier, an alternative overload [SWS_CM_11352] exists.

The static function StopFindService of the proxy class terminates an asynchronous service search previously started with StartFindService and stops the receipt of further notifications for the passed handle [SWS_CM_00125]. The ongoing background activity for monitoring service availability by the technical binding is thus discontinued AP EXP ARAComAPI §5.3 “Proxy Class API’s”.

Usage and Semantics

• Parameters: As an input parameter, the function expects a ara::com::FindServiceHandle that was previously obtained by one of the StartFindService methods ([SWS_CM_00123], [SWS_CM_00623], [SWS_CM_11352], [SWS_CM_11365], [SWS_CM_00125]).
• Return value and exception safety: The function returns no value (void), is declared with noexcept, and specified as exception-safe [SWS_CM_00125].
• Concurrency and calling context: Invoking StopFindService is explicitly also permitted directly within the user-defined callback function FindServiceHandler [SWS_CM_00383] AP EXP ARAComAPI §5.3 “Proxy Class API’s”. For this purpose, the respective FindServiceHandle is passed to the handler as a parameter [SWS_CM_00383]. Since the callback itself does not need to be reentrant, serialization of consecutive calls must be ensured by the binding implementer AP EXP ARAComAPI §5.3 “Proxy Class API’s”.

The member function UnsetServiceStateChangeHandler is part of the generated proxy class in namespace <SI-Namespace>::proxy::<SI>Proxy according to [SWS_CM_01075] (AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.12 “UnsetServiceStateChangeHandler”). It is included via header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h".

With regard to usage, behavior, and concurrency, the following provisions apply:

• Usage: The method has the signature void UnsetServiceStateChangeHandler() noexcept;. It takes no parameters and returns no value. Interpretation: According to the identifier and the reference to [SWS_CM_01074], the call serves to reset or unregister a previously registered callback handler for service state changes on the proxy instance. Question Q-6eb71298a6f37ad9 (open)
• Error handling and exception safety: The operation is declared as noexcept and specified as exception safe ([SWS_CM_01075]). It throws no exceptions and reports no error codes back to the caller.
• Interaction and constraints: The functional semantics reference the definition in [SWS_CM_01074]. Interpretation: The unregistration is likely to take effect synchronously, such that after the function call returns, no further state changes are delivered via the previous callback. Question Q-31348a50d9be537d (open)