class <SI-Namespace>::proxy::triggers::<Trigger>

use

The function SetReceiveHandler is called in the scope of the trigger class of a service proxy (<SI-Namespace>::proxy::triggers::<Trigger>) and included via header <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h [SWS_CM_00250]. Alongside events, methods, and fields, triggers form one of the four communication mechanisms in ara::com EXP_ARAComAPI §4.2 “Means of Communication”.

The parameter handler of type ara::com::TriggerReceiveHandler accepts a callable object that is called by Communication Management when a trigger arrives. The handler itself has no parameters; to query the current trigger count, the method GetNewTriggers of the specific trigger class must be called within the callback function [SWS_CM_00250].

Error Handling and Exception Safety

Registration returns no return value (void) and is defined as noexcept as well as exception safe [SWS_CM_00250]. A violation of the calling convention in the form of a InvalidHandlerViolation occurs if the passed callable does not exist or is null [SWS_CM_00250].

Interaction and Variants

For scenarios in which the trigger handler is to be processed in a defined execution context, the template overload with ExecutorT exists [SWS_CM_00352]. Comparable registration methods for callbacks are also available on proxy level for events ([SWS_CM_00181], [SWS_CM_11356]) and fields ([SWS_CM_11605], [SWS_CM_11611]) EXP_ARAComAPI §5.3.1 “Proxy Class API’s”.

use

The template function SetSubscriptionStateChangeHandler in scope <SI-Namespace>::proxy::triggers::<Trigger> registers a callback for notification of changes to the subscription state ([SWS_CM_01106]). It is declared via the header file <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h and accepts two parameters:

• handler: The callable entity of type ara::com::SubscriptionStateChangeHandler to be executed upon a state change ([SWS_CM_01107]).
• executor: An execution context of type ExecutorT ([SWS_CM_11360]) in which the execution of the handler must occur.

The registration itself behaves synchronously and has no return value (void). The registered callback is executed in the specified execution context upon state changes.

Error Handling and Exception Safety

The method is declared as noexcept and specified as exception safe ([SWS_CM_01106]). If the passed callable instance does not exist or is null, a InvalidHandlerViolation is present ([SWS_CM_01106]). Since no exceptions are thrown, an invalid handler presumably leads to a platform-specific error path (interpretation). Question Q-cbb90bfbfa10338d (open)

Concurrency and Interaction

By passing the executor ([SWS_CM_11360]), the application itself controls the execution context for state callbacks. This is likely to prevent long-running handler invocations from blocking the internal event processing of Communication Management (interpretation). Question (open) The function extends the contextless variant [SWS_CM_01107] and forms the trigger counterpart to the executor-based interfaces for proxy events ([SWS_CM_11354]), proxy fields ([SWS_CM_11608]), and skeleton triggers ([SWS_CM_11111]).

With the function [SWS_CM_01107], a callback handler is registered in the proxy area of a trigger (<SI-Namespace>::proxy::triggers::<Trigger>), which Communication Management calls upon every change of the subscription state (ara::com::SubscriptionState). The function has no return value and is specified as exception-safe (noexcept).

Since subscribing must fundamentally be treated as an asynchronous process, the application may only assume a successful subscription once the handler registered via [SWS_CM_01107] or the polling function GetSubscriptionState() reports the state kSubscribed [SWS_CM_12006]. In case of time delays or if the server is temporarily unavailable due to a restart or network problem, Communication Management activates the handler with the state kSubscriptionPending [SWS_CM_00313].

The following boundary conditions apply to error handling and integration:

• Error handling: Passing a non-existent or empty callable (null) is invalid and leads to a InvalidHandlerViolation [SWS_CM_01107].
• Execution context: If the handler is not to be executed in the default context, but within a specific execution context, the template overload with ExecutorT&& is available [SWS_CM_01106].
• Interaction: For service events, the analogous interface [SWS_CM_00333] exists as part of the general proxy class APIs ARAComAPI §5.3.1 “Proxy Class API’s”.

The function SetTransportFaultConditionHandler serves on an instance of proxy::triggers::<Trigger> to register a callback function of type ara::com::e2e::TransportFaultConditionHandler ([SWS_CM_00106]). It takes the parameter handler, has no return value, and is specified as noexcept as well as exception safe ([SWS_CM_00106]).

Via the registered handler, the communication layer signals detected transmission layer errors. In the DDS network binding, the handler reports events of the underlying DataReader entity as TransportFaultCondition ([SWS_CM_00212]):

• TransportFaultCondition::kSampleRejected for dropped samples (e.g. due to memory shortage or data corruption),
• TransportFaultCondition::kDeadlineMissed for violated receive deadlines (REQUESTED_DEADLINE_MISSED),
• TransportFaultCondition::kSampleLost upon loss of detected data samples ([SWS_CM_00212]).

If a non-existent or empty handler is passed instead of a valid callable, the runtime environment reports a InvalidHandlerViolation ([SWS_CM_00106]). Since the function signature is declared noexcept, this violation presumably leads to platform-side error handling instead of a C++ exception. Question Q-ebaf44b8f7b198e8 (open)

Registration occurs synchronously in the context of the caller; the execution of the handler is not delegated to a specific dispatcher in this overload. If the callback is to run in a defined execution context, the overloaded template variant with an additional ExecutorT&& is available ([SWS_CM_00107]). Binding should typically take place prior to actual trigger processing to capture errors from the outset. Question (open)

Corresponding registration options for TransportFaultConditionHandler exist similarly for proxy events ([SWS_CM_00099]), proxy fields ([SWS_CM_00109]), as well as skeleton methods ([SWS_CM_00093]) and skeleton fields ([SWS_CM_00096]).

The function [SWS_CM_00107] serves to register a callback routine for transport errors of a proxy trigger in namespace <SI-Namespace>::proxy::triggers::<Trigger>. As an overload with execution context, it accepts an executor object executor, in which triggered asynchronous computations are executed, in addition to the handler of type ara::com::e2e::TransportFaultConditionHandler.

The following specifications apply to usage and error handling:

• Parameters and return value: Parameter handler passes the callable to be set, while executor defines the execution context for asynchronous tasks [SWS_CM_00107]. The function returns no return value and is declared as noexcept (exception safety: exception safe).
• Error cases and violations: If a non-existent or invalid handler is passed (null), the runtime reports a InvalidHandlerViolation [SWS_CM_00107].
• Reported error conditions: The registered handler receives detected transport errors according to [SWS_CM_00212]. These include TransportFaultCondition::kSampleRejected (such as in case of data corruption or resource shortage), TransportFaultCondition::kDeadlineMissed (in case of violated deadlines), and TransportFaultCondition::kSampleLost (in case of lost samples).

Compared to the basic function without executor [SWS_CM_00106], this variant enables targeted control of the concurrency context for the trigger's error processing. Analogous overloads with execution context exist in Communication Management for proxy events [SWS_CM_00100], proxy fields [SWS_CM_00110], and on the skeleton level for methods [SWS_CM_00094] and fields [SWS_CM_00097].

The method Subscribe serves to subscribe to a service trigger on the client side via a proxy instance in namespace <SI-Namespace>::proxy::triggers::<Trigger> [SWS_CM_00723]. Prior to use, the service instance must have been offered on the server side via OfferService() and found by the client via Service Discovery mechanisms AUTOSAR_AP_EXP_ARAComAPI §4.2 “Means of Communication”.

Compared to event subscriptions ([SWS_CM_00141]) and field subscriptions ([SWS_CM_11601]), Subscribe exhibits specific characteristics for triggers:

• Parameters and cache: The function takes no parameters (void Subscribe() noexcept) [SWS_CM_00723]. Because triggers transmit pure notifications without data samples, the reservation of a local sample cache via maxSampleCount [SWS_CM_00141], which is customary for events, is omitted.
• Return value: No ara::core::Result is returned, but rather void [SWS_CM_00723].
• Asynchrony: The call initiates the subscription; the actual establishment of the connection to the service instance is expected to take place asynchronously in Communication Management, analogously to event subscriptions AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 “Monitoring Event Subscription”. Question Q-92ae3f442b45f3cc (open)

The following conditions apply to the lifecycle and error handling:

• State check and idempotency: If the trigger is already in state kSubscribed or kSubscriptionPending at the time of the call, the method returns immediately without further action [SWS_CM_00723].
• Exception safety: The function is specified as noexcept and exception safe [SWS_CM_00723].
• Access control: In case of insufficient permissions, grant enforcement denies execution with a InsufficientPermissionsViolation [SWS_CM_00723].

use

The synchronous function UnsetReceiveHandler in namespace <SI-Namespace>::proxy::triggers::<Trigger> serves to disable the previously registered reception handler for a service trigger on the proxy side [SWS_CM_11614]. The function requires the inclusion of header file #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h", takes no input parameters, and has no return value.

Calling this function deregisters the application-specific callback. This allows the application to flexibly switch between event-driven reception and a query-based model (polling) (AUTOSAR_AP_EXP_ARAComAPI p. 46, AUTOSAR_AP_SWS_CommunicationManagement §7.5.18.1).

Error Handling and Exception Safety

In contrast to the analogous functions for service events [SWS_CM_00183] and service fields [SWS_CM_11606], which are explicitly specified as noexcept and exception-safe, UnsetReceiveHandler for triggers is declared as not exception safe (not exception safe) [SWS_CM_11614]. Interpretation: Callers should prepare for exceptions being thrown in case of internal errors of the communication infrastructure, even though specific exception types or error codes are not listed in the standard. Question Q-92e16243a7ddee35 (open)

Interaction and bindings

The method is part of the trigger classes in the proxy namespace (AUTOSAR_AP_EXP_ARAComAPI §5.3.1). When using a DDS binding, the method call according to [SWS_CM_11141] is mapped via the associated DataReader according to the rules defined in [SWS_CM_11026].

The function UnsetSubscriptionStateChangeHandler is used on the client side to remove a previously registered callback for subscription state changes (ara::com::SubscriptionState) of a trigger [SWS_CM_01108]. It is declared in the scope <SI-Namespace>::proxy::triggers::<Trigger> and is to be included via the header #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" [SWS_CM_01108].

Usage and Call Context

The method has the signature void UnsetSubscriptionStateChangeHandler () noexcept;, takes no parameters, and returns no value [SWS_CM_01108]. It is called synchronously on the instance of the respective trigger of a proxy class to unsubscribe from notifications upon changes of the subscription state AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”. Interpretation: After the call is executed, no further state changes should be delivered to the previous handler. Question Q-d08dc975aacba85c (open)

Error Handling and Concurrency

The interface is declared as noexcept and is explicitly specified as exception safe (exception safe) [SWS_CM_01108]. Failure of the call or throwing of exceptions is therefore ruled out, and no error return values exist.

Interaction

The function fits into the unified schema of the proxy interfaces. Analogous deregistration methods are available in the proxy context for events according to [SWS_CM_00334] AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.4.5 “UnsetSubscriptionStateChangeHandler” as well as for fields according to [SWS_CM_11609] AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 “UnsetSubscriptionStateChangeHandler”. Corresponding counterparts exist on the server or skeleton side for triggers [SWS_CM_01112] and events [SWS_CM_12010].

The function UnsetTransportFaultConditionHandler serves to deregister a previously registered ara::com::e2e::TransportFaultConditionHandler for a specific proxy trigger ([SWS_CM_00108], documented in AUTOSAR_AP_SWS_CommunicationManagement §8.3.7.1.1.3 “UnsetTransportFaultConditionHandler”). It is located in namespace <SI-Namespace>::proxy::triggers::<Trigger> and is to be included via the header file #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00108]).

The signature is void UnsetTransportFaultConditionHandler() noexcept;. The call takes no parameters and returns no value ([SWS_CM_00108]). Due to the noexcept declaration and classification as exception safe, the function throws no exceptions during regular operation ([SWS_CM_00108]). Specific error codes, error channels, or fallback values are not provided in the specification.

Regarding the sequence, the function synchronously removes the association with the error handling routine; consequently, after successful execution, no further notifications about E2E transport errors for the affected trigger should be delivered to the previous handler (interpretation). Question Q-ae8477bc6530e352 (open)

Within the overall system, the element forms the counterpart to analogous deregistration functions for other communication patterns in AUTOSAR_AP_SWS_CommunicationManagement §8.3/8.4:

• Proxy events: UnsetTransportFaultConditionHandler at event level ([SWS_CM_00105]).
• Proxy fields: Deregistration for field notifiers ([SWS_CM_00126]).
• Skeleton level: Deregistration for field Get/Set ([SWS_CM_00098]) as well as for all methods of a skeleton ([SWS_CM_00095]).