class <SI-Namespace>::proxy::events::<Event>

use

The function SetReceiveHandler is used on the client side in scope <SI-Namespace>::proxy::events::<Event> to register a callback handler for incoming events [SWS_CM_00181]. Passed as parameter is a ara::com::EventReceiveHandler, which is defined as a parameterless function and is called by Communication Management upon event arrival [SWS_CM_00181]. The function has no return value (void) [SWS_CM_00181].

Error Handling and Exception Behavior

The operation is specified as noexcept and exception-safe (exception safe) [SWS_CM_00181]. If the passed callable does not exist or is null, this is treated as a InvalidHandlerViolation [SWS_CM_00181].

Execution context and interaction

Within the proxy interfaces, SetReceiveHandler belongs to the basic mechanisms alongside calls such as UnsetReceiveHandler() and GetNewSamples() ARAComAPI §5.3.1 “Proxy Class API’s”. If the handler is to be executed in a specified context, the template overload with ExecutorT is available [SWS_CM_11356] (ARAComAPI p. 10).

The same notification approach is also used for triggers via [SWS_CM_00250] (with context: [SWS_CM_00352]) as well as for fields via [SWS_CM_11605] (with context: [SWS_CM_11611]) ARAComAPI §4.2 “Means of Communication”.

The method SetSubscriptionStateChangeHandler in namespace proxy::events::<Event> registers a callback function that Communication Management calls as soon as the state ara::com::SubscriptionState of the event changes ([SWS_CM_00333]). The function is declared as noexcept and is considered exception-safe ([SWS_CM_00333]).

Usage and Asynchronous Semantics

Calls to Subscribe() operate asynchronously in principle; a successful subscription may only be considered completed once the registered handler or GetSubscriptionState() reports state kSubscribed ([SWS_CM_12006]). The handler is called with kSubscriptionPending if the subscription does not take effect immediately (for example, due to bus protocol latencies) or if the server instance is unreachable due to restarts or network errors ([SWS_CM_00313]). Deregistration of the handler is performed via UnsetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 “Proxy Class API’s”).

Error Handling and Boundary Conditions

If no valid callback object is passed or if it is null, error case InvalidHandlerViolation is present ([SWS_CM_00333]). Regarding the call order, the handler should expediently be registered before Subscribe() in order to reliably capture early state transitions. Question Q-3b9c25c6aa2d0a0f (open)

Interaction and Variants

For executing the handler in a specified thread or work context, the overloaded template variant with parameter ExecutorT is available ([SWS_CM_11354]). Parallel interfaces exist for proxy triggers ([SWS_CM_01107]), proxy fields ([SWS_CM_11607]), and at the skeleton level ([SWS_CM_12008]).

The template member function SetSubscriptionStateChangeHandler in scope proxy::events::<Event> serves to register a callback function for subscription state changes (ara::com::SubscriptionState) ([SWS_CM_11354], AP EXP ARAComAPI §5.3.1 “Proxy Class API’s”). In contrast to the base function [SWS_CM_00333], the handler is not executed in the internal context of Communication Management, but is passed via template parameter ExecutorT to a provided execution context executor ([SWS_CM_11360], AP EXP ARAComAPI §1.0 “SetSubscriptionState with ExecutorT”).

Parameters and Return Values

• handler: The callable to be invoked that is notified upon a change in the ara::com::SubscriptionState of the event ([SWS_CM_00333]).
• executor: The execution context according to [SWS_CM_11360] in which the handler is to be processed.
• Return value: The function has no return value (void).

Error Handling and Execution

The function is declared as noexcept and specified as exception-safe (exception safe). If the passed callable handler does not exist or is null, an InvalidHandlerViolation is thrown ([SWS_CM_11354]).

Interaction

The pattern of context-bound state monitoring with ExecutorT exists analogously for proxy triggers ([SWS_CM_01106]) as well as proxy fields ([SWS_CM_11608]). If no offloading to a specific context is required, variant [SWS_CM_00333] is available.

The member function SetTransportFaultConditionHandler serves on a proxy event ([SWS_CM_00099]) to register a callback function of type ara::com::e2e::TransportFaultConditionHandler. Via this handler, transmission errors detected on the transport level of the communication binding are reported ([SWS_CM_00211]).

Usage and semantics:

• Call and parameters: The function takes the callable handler object handler and returns no value ([SWS_CM_00099]). The method signature is declared as noexcept ([SWS_CM_00099]).
• Transmitted error states: In case of an error, the registered handler reports values of the enum ara::com::e2e::TransportFaultCondition, such as kSampleRejected in case of dropped samples of the underlying transport channel ([SWS_CM_00211]).
• Execution context: For asynchronous executions, a template overload with an additional executor object ExecutorT&& executor is available ([SWS_CM_00100]).

Error handling and constraints:

• Exception safety: The function is considered exception-safe (exception safe) ([SWS_CM_00099]).
• Violations: If the passed callable does not exist or is null, a InvalidHandlerViolation violation is present ([SWS_CM_00099]).
• Interaction: Equivalent interfaces for registering a TransportFaultConditionHandler also exist for triggers ([SWS_CM_00106]), field notifiers ([SWS_CM_00109]), and skeleton methods ([SWS_CM_00093]).

The template function SetTransportFaultConditionHandler registers an application-specific handler of type ara::com::e2e::TransportFaultConditionHandler along with a user-defined executor ([SWS_CM_00100]) on a proxy event. It represents the execution-context overload of the parameter-less base function ([SWS_CM_00099]).

Usage and parameters: The method is called on instances of <SI-Namespace>::proxy::events::<Event> and returns no value (void) ([SWS_CM_00100]). It takes the handler to be called (handler) and accepts an executor object (executor as universal reference ExecutorT&&), in whose context any asynchronous execution of the handler is initiated ([SWS_CM_00100]). The function signature is declared with noexcept ([SWS_CM_00100]).

Error handling: The operation is specified as exception safe ([SWS_CM_00100]). If an invalid or non-existent callable (null) is passed, a violation in the form of InvalidHandlerViolation is present ([SWS_CM_00100]). Via the registered handler, detected transport errors are reported, such as TransportFaultCondition::kSampleRejected when incoming data samples are dropped by the underlying transport entity ([SWS_CM_00211]).

Interaction: While [SWS_CM_00099] performs registration without an explicit executor, this overload enables execution in the desired thread or task context ([SWS_CM_00100]). Analogous overloads with an executor are available for skeleton methods ([SWS_CM_00094]) and skeleton fields ([SWS_CM_00097]), as well as on the proxy side for triggers ([SWS_CM_00107]) and field notifiers ([SWS_CM_00110]).

use

The method Subscribe registers the proxy element for receiving service events according to [SWS_CM_00141]. The call is asynchronous in nature: The return of the function merely confirms that Communication Management has accepted the registration request (AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 “Monitoring Event Subscription”). With the mandatory parameter maxSampleCount, the application bindingly communicates how many event samples it will hold at most simultaneously, thereby initializing the local receive buffer (AUTOSAR_AP_EXP_ARAComAPI p. 40).

Error Handling and Boundary Conditions

If the event is already in state kSubscribed or kSubscriptionPending upon the call and the passed value maxSampleCount matches the active subscription, the method returns successfully without action ([SWS_CM_00141]). If, on the other hand, the cache size differs upon renewed subscription, the call fails and returns the error code ComErrc::kMaxSampleCountNotRealizable in ara::core::Result ([SWS_CM_00141]). In case of missing access permissions, the call is rejected (InsufficientPermissionsViolation according to [SWS_CM_00141]). The signature is declared as noexcept and is considered exception-safe.

Interaction

The reserved cache capacity limits subsequent data reception via GetNewSamples ([SWS_CM_00701]); if the application holds more smart pointers than specified, the error ComErrc::kMaxSamplesExceeded is triggered ([SWS_CM_10432]). While field events are subscribed to identically via maxSampleCount ([SWS_CM_11601]), pure trigger events do not require a buffer size specification ([SWS_CM_00723]).

use

The function UnsetReceiveHandler is part of the event wrapper in scope <SI-Namespace>::proxy::events::<Event> and is included via header file #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00183]). It accepts no input parameters and has no return value (void). The call removes an application-specific receive handler for a service event that was previously registered with SetReceiveHandler (EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”). This allows the receiving application to switch at any time between event-driven reception (\"event-driven\") and active querying (\"polling style\") using GetNewSamples() (EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”).

Error handling

The method is declared with noexcept and possesses the property exception safe ([SWS_CM_00183]). It does not throw exceptions at runtime and does not report specific error codes.

Concurrency and Binding

While the registered callback handler does not need to be reentrant because Communication Management serializes calls (EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”), UnsetReceiveHandler deactivates the event trigger for receiving further notifications ([SWS_CM_00183]). In the context of the DDS binding, the method UnsetReceiveHandler() is mapped to the corresponding DataReader according to [SWS_CM_11141] in line with the specification [SWS_CM_11026].

Interaction

The function forms the direct counterpart to the registration via SetReceiveHandler ([SWS_CM_11140], EXP ARAComAPI §5.3.1 “Proxy Class API’s”). Related functions can be found in other proxy interfaces:

• For fields, an identically named function UnsetReceiveHandler exists in scope <SI-Namespace>::proxy::fields::<Field>, which is likewise defined as noexcept and exception safe ([SWS_CM_11606]).
• For triggers, UnsetReceiveHandler is available in scope <SI-Namespace>::proxy::triggers::<Trigger>, but is declared differently as not exception safe ([SWS_CM_11614]).

use

The member function UnsetSubscriptionStateChangeHandler serves to reset and unregister a previously set callback handler for changes of the subscription status (ara::com::SubscriptionState) on the proxy side ([SWS_CM_00334], EXP ARAComAPI §1.0). The function is part of the event interface and is located in the application-specific namespace under proxy::events ([SWS_CM_00334], SWS CommunicationManagement §8.3.2.2.4.5 “UnsetSubscriptionStateChangeHandler”). To use it, the generated proxy header file <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h is included ([SWS_CM_00334]). The call is synchronous, takes no parameters, and returns no value ([SWS_CM_00334]).

Error handling

According to the specification, the function is declared with the identifier noexcept and classified as exception-safe ("exception safe") ([SWS_CM_00334]). In case of error, it throws no C++ exceptions and reports no error codes back ([SWS_CM_00334]).

Concurrency and Interaction

The function is part of a suite of proxy APIs for service discovery and event management such as Subscribe(), Unsubscribe(), GetSubscriptionState(), and SetSubscriptionStateChangeHandler() (EXP ARAComAPI §5.3.1 “Proxy Class API’s”). As an interpretation, no further notifications via the unregistered handler should be triggered after the call. Question Q-6173c01e6ca93876 (open) Symmetrical counterparts for resetting handlers for status changes are defined in the specification for proxy fields ([SWS_CM_11609], SWS CommunicationManagement §8.3.3.2.4.5 “UnsetSubscriptionStateChangeHandler”) and triggers ([SWS_CM_01108]), as well as on the service provider side (skeleton) for events ([SWS_CM_12010]) and triggers ([SWS_CM_01112]).

use

The function UnsetTransportFaultConditionHandler in namespace <SI-Namespace>::proxy::events::<Event> serves to deregister a previously registered ara::com::e2e::TransportFaultConditionHandler for a specific proxy event [SWS_CM_00105]. The function declaration is provided via the header file <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.1.3 “UnsetTransportFaultConditionHandler”. The call takes no parameters and returns no value (void).

Error Handling and Exception Safety

The function is declared with identifier noexcept and specified as exception-safe (exception safe) [SWS_CM_00105]. Neither specific error codes nor notifications to error or diagnostic subsystems are defined in the standard.

Sequence and boundary conditions

The call is expected to be executed synchronously to immediately disable E2E error handling at the event level, for example when the event is no longer to be monitored or before the associated proxy object is released (interpretation). Question Q-ff00695fff5407fe (open) After execution, the communication layer no longer processes E2E transport errors via the previously registered callback of this event.

Interaction

Deregistering handlers for transport errors follows a uniform pattern across various communication elements:

• For notifiers of fields at the proxy level, the function [SWS_CM_00126] is used.
• For proxy triggers, the handler is deregistered via [SWS_CM_00108].
• On the skeleton side, analogous interfaces are available for all methods of a service interface ([SWS_CM_00095]) as well as for getters/setters of fields ([SWS_CM_00098]).

use

The method Unsubscribe() terminates the active subscription of a service event on the proxy side ([SWS_CM_00151], EXP_ARAComAPI §5.5). It is defined in scope <SI-Namespace>::proxy::events::<Event> and included via header file #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00151]). The function takes no input parameters and returns no return value (void). If the event was not subscribed at the time of the call, the method returns without taking any action ([SWS_CM_00151]).

Error Handling and Exception Safety

The operation is declared with the identifier noexcept and specified as exception-safe ([SWS_CM_00151]). A DanglingSamplesViolation is provided as a violation if the precondition according to [SWS_CM_00085] was violated prior to the method call ([SWS_CM_00151]).

Interaction and related interfaces

At the network layer, terminating the subscription initiates the sending of SOME/IP messages of type StopSubscribeEventgroup ([SWS_CM_10378], SWS_CommunicationManagement §7.2.1.2.6). Within the proxy interfaces, Unsubscribe() belongs to the group of subscription management methods (EXP_ARAComAPI §5.3.1). An identical unsubscribe semantics is also available for service triggers ([SWS_CM_00810], EXP_ARAComAPI §4) and field notifications ([SWS_CM_11602]).