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

使用

函数 SetReceiveHandler 用于在客户端作用域 <SI-Namespace>::proxy::events::<Event> 中注册针对到达事件 [SWS_CM_00181] 的回调处理程序。传入的参数为一个 ara::com::EventReceiveHandler，其被定义为无参函数，并在事件到达时由 Communication Management 调用 [SWS_CM_00181]。该函数没有返回值（void）[SWS_CM_00181]。

错误处理与异常行为

该操作被指定为 noexcept 且异常安全（exception safe）[SWS_CM_00181]。如果传入的 Callable 不存在或是 null，则被视为 InvalidHandlerViolation [SWS_CM_00181]。

执行上下文与协作

在 Proxy 接口中，SetReceiveHandler 属于与 UnsetReceiveHandler() 和 GetNewSamples() ARAComAPI §5.3.1 “Proxy Class API’s” 等调用并列的基础机制。如果处理程序应在给定的上下文中执行，则提供了带有 ExecutorT 的模板重载 [SWS_CM_11356]（ARAComAPI 第10页）。

相同的通知方法也通过 [SWS_CM_00250]（带上下文：[SWS_CM_00352]）用于触发器，以及通过 [SWS_CM_11605]（带上下文：[SWS_CM_11611]）用于字段 ARAComAPI §4.2 “Means of Communication”。

命名空间 proxy::events::<Event> 中的方法 SetSubscriptionStateChangeHandler 注册一个回调函数，一旦事件的状态 ara::com::SubscriptionState 发生更改，Communication Management 就会调用该回调函数（[SWS_CM_00333]）。该函数被声明为 noexcept 并被视为异常安全（[SWS_CM_00333]）。

使用与异步语义

对 Subscribe() 的调用原则上是异步工作的；只有当注册的处理程序或 GetSubscriptionState() 返回状态 kSubscribed 时，成功的订阅才可被视为已完成（[SWS_CM_12006]）。如果订阅未立即生效（例如由于总线协议延迟），或者如果由于重启或网络错误导致服务器实例不可达，则使用 kSubscriptionPending 调用处理程序（[SWS_CM_00313]）。取消处理程序注册通过 UnsetSubscriptionStateChangeHandler() 进行（EXP ARAComAPI §5.3.1 “Proxy Class API’s”）。

错误处理与边界条件

如果未传递有效的回调对象或该对象为 null，则属于错误情况 InvalidHandlerViolation（[SWS_CM_00333]）。关于调用顺序，处理程序适宜在 Subscribe() 之前注册，以便可靠地捕获早期的状态转换。 问题 Q-3b9c25c6aa2d0a0f (未决)

交互与变体

为了在给定的线程或工作上下文中执行处理程序，提供了带有参数 ExecutorT 的重载模板变体（[SWS_CM_11354]）。并行接口存在于 Proxy 触发器（[SWS_CM_01107]）、Proxy 字段（[SWS_CM_11607]）以及 Skeleton 级别（[SWS_CM_12008]）。

模板成员函数 SetSubscriptionStateChangeHandler 在作用域 proxy::events::<Event> 中用于注册订阅状态更改（ara::com::SubscriptionState）的回调函数（[SWS_CM_11354]，AP EXP ARAComAPI §5.3.1 “Proxy Class API’s”）。与基础函数 [SWS_CM_00333] 相比，该处理程序不在 Communication Management 的内部上下文中执行，而是通过模板参数 ExecutorT 传递给提供的执行上下文 executor（[SWS_CM_11360]，AP EXP ARAComAPI §1.0 “SetSubscriptionState with ExecutorT”）。

参数与返回值

• handler：要调用的 Callable，在事件的 ara::com::SubscriptionState 发生更改时得到通知（[SWS_CM_00333]）。
• executor：根据 [SWS_CM_11360] 的执行上下文，处理程序应在其中被处理。
• 返回值：该函数没有返回值（void）。

错误处理与执行

该函数被声明为 noexcept 并指定为异常安全（exception safe）。如果传入的 Callable handler 不存在或为 null，则会引发 InvalidHandlerViolation（[SWS_CM_11354]）。

相互作用

带有 ExecutorT 的上下文绑定状态监视模式同样存在于 Proxy 触发器（[SWS_CM_01106]）以及 Proxy 字段（[SWS_CM_11608]）。如果不需要移交给特定上下文，则可以使用变体 [SWS_CM_00333]。

成员函数 SetTransportFaultConditionHandler 用于在 Proxy 事件（[SWS_CM_00099]）上注册类型为 ara::com::e2e::TransportFaultConditionHandler 的回调函数。通过此处理程序报告在通信绑定的传输层检测到的传输错误（[SWS_CM_00211]）。

使用与语义：

• 调用与参数：该函数接收可调用处理程序对象 handler 且不提供返回值（[SWS_CM_00099]）。方法签名被声明为 noexcept（[SWS_CM_00099]）。
• 传输的错误状态：注册的处理程序在发生错误时报告枚举 ara::com::e2e::TransportFaultCondition 的值，例如在底层传输通道丢弃样本时的 kSampleRejected（[SWS_CM_00211]）。
• 执行上下文：对于异步执行，提供了带有附加执行器对象 ExecutorT&& executor 的模板重载（[SWS_CM_00100]）。

错误处理与边界条件：

• 异常安全性：该函数被视为异常安全（exception safe）（[SWS_CM_00099]）。
• 违规行为：如果传入的可调用对象不存在或为 null，则存在 InvalidHandlerViolation（[SWS_CM_00099]）。
• 交互：用于注册 TransportFaultConditionHandler 的等效接口也存在于触发器（[SWS_CM_00106]）、字段通知器（[SWS_CM_00109]）和 Skeleton 方法（[SWS_CM_00093]）。

模板函数 SetTransportFaultConditionHandler 在 Proxy 事件上注册类型为 ara::com::e2e::TransportFaultConditionHandler 的特定于应用程序的处理程序以及用户定义的执行器（[SWS_CM_00100]）。它代表了带有更少参数的基础函数的执行上下文重载（[SWS_CM_00099]）。

使用与参数：该方法在 <SI-Namespace>::proxy::events::<Event> 的实例上调用且不返回任何值（void）（[SWS_CM_00100]）。它接收要调用的处理程序（handler）并获取一个执行器对象（executor 作为万能引用 ExecutorT&&），任何对处理程序的异步执行都会在该对象的上下文中启动（[SWS_CM_00100]）。函数签名使用 noexcept 声明（[SWS_CM_00100]）。

错误处理：该操作被指定为 exception safe（[SWS_CM_00100]）。如果传入了无效或不存在的可调用对象（null），则存在形式为 InvalidHandlerViolation 的违规行为（[SWS_CM_00100]）。通过注册的处理程序报告检测到的传输错误，例如在底层传输实体丢弃传入数据样本时的 TransportFaultCondition::kSampleRejected（[SWS_CM_00211]）。

交互：虽然 [SWS_CM_00099] 在没有显式执行器的情况下进行注册，但此重载允许在所需的线程或任务上下文中执行（[SWS_CM_00100]）。带有执行器的类似重载可用于 Skeleton 方法（[SWS_CM_00094]）和 Skeleton 字段（[SWS_CM_00097]），以及在 Proxy 端用于触发器（[SWS_CM_00107]）和字段通知器（[SWS_CM_00110]）。

使用

方法 Subscribe 根据 [SWS_CM_00141] 注册用于接收服务事件的 Proxy 元素。该调用具有异步性质：函数的返回仅确认 Communication Management 已接受注册请求（AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 “Monitoring Event Subscription”）。通过必选参数 maxSampleCount，应用程序明确告知其最多同时保留多少个事件样本，并藉此初始化本地接收缓冲区（AUTOSAR_AP_EXP_ARAComAPI 第40页）。

错误处理与边界条件

若调用时事件已处于状态 kSubscribed 或 kSubscriptionPending，且传入的值 maxSampleCount 与活动订阅一致，则该方法不执行任何操作直接成功返回（[SWS_CM_00141]）。反之，若在重新订阅时缓存大小不一致，则调用失败并在 ara::core::Result 中返回错误代码 ComErrc::kMaxSampleCountNotRealizable（[SWS_CM_00141]）。在缺少访问权限时，调用将被拒绝（InsufficientPermissionsViolation，依据 [SWS_CM_00141]）。该签名声明为 noexcept 且被视为异常安全。

相互作用

预留的缓存容量限制了后续通过 GetNewSamples 进行的数据接收（[SWS_CM_00701]）；若应用程序持有的智能指针数量多于指定值，则会触发错误 ComErrc::kMaxSamplesExceeded（[SWS_CM_10432]）。虽然字段事件以相同方式通过 maxSampleCount 订阅（[SWS_CM_11601]），但纯触发器事件不需要指定缓冲区大小（[SWS_CM_00723]）。

使用

函数 UnsetReceiveHandler 是作用域 <SI-Namespace>::proxy::events::<Event> 中事件包装器的一部分，并通过头文件 #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" 包含（[SWS_CM_00183]）。它不接受输入参数，也没有返回值（void）。通过调用该函数，此前使用 SetReceiveHandler 为服务事件注册的特定于应用层接收处理程序将被重新移除（EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”）。由此，接收方应用程序可以随时在事件驱动接收（“event-driven”）与使用 GetNewSamples() 的主动查询模式（“polling style”）之间切换（EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”）。

错误处理

该方法使用 noexcept 声明，并具有属性 exception safe（[SWS_CM_00183]）。它在运行时不抛出任何异常，也不返回特定的错误代码。

并发性与绑定

对于已注册的回调处理程序，由于 Communication Management 会序列化调用，因此它不需要是可重入的（EXP ARAComAPI §5.3.2 “RadarService Proxy Class Example”），而 UnsetReceiveHandler 会禁用用于接收后续通知的事件触发器（[SWS_CM_00183]）。在 DDS 绑定的上下文中，方法 UnsetReceiveHandler() 根据 [SWS_CM_11141] 按照规范 [SWS_CM_11026] 映射到相应的 DataReader。

相互作用

该函数与通过 SetReceiveHandler 进行的注册直接对应（[SWS_CM_11140]、EXP ARAComAPI §5.3.1 “Proxy Class API’s”）。相关函数可在其他 Proxy 接口中找到：

• 对于字段，作用域 <SI-Namespace>::proxy::fields::<Field> 中存在同名函数 UnsetReceiveHandler，它同样被定义为 noexcept 和 exception safe（[SWS_CM_11606]）。
• 对于触发器，UnsetReceiveHandler 在作用域 <SI-Namespace>::proxy::triggers::<Trigger> 中可用，但不同的是它被声明为 not exception safe（[SWS_CM_11614]）。

使用

成员函数 UnsetSubscriptionStateChangeHandler 用于重置并注销此前在 Proxy 端为订阅状态更改（ara::com::SubscriptionState）设置的回调处理程序（[SWS_CM_00334]、EXP ARAComAPI §1.0）。该函数是事件接口的组成部分，位于 proxy::events 下的应用特定命名空间中（[SWS_CM_00334]、SWS CommunicationManagement §8.3.2.2.4.5 “UnsetSubscriptionStateChangeHandler”）。为了使用该函数，需要包含生成的 Proxy 头文件 <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h（[SWS_CM_00334]）。调用同步进行，不接受任何参数，且不提供返回值（[SWS_CM_00334]）。

错误处理

根据规范，该函数使用标识符 noexcept 声明，并归类为异常安全（“exception safe”）（[SWS_CM_00334]）。在出错时它不会触发 C++ 异常，也不会返回错误码（[SWS_CM_00334]）。

并发性与交互

该函数与用于服务搜索和事件管理的其他 Proxy API（如 Subscribe()、Unsubscribe()、GetSubscriptionState() 和 SetSubscriptionStateChangeHandler()）配合使用（EXP ARAComAPI §5.3.1 “Proxy Class API’s”）。解释：在调用之后，大概率不会再通过已注销的处理程序触发任何进一步的通知。 问题 Q-6173c01e6ca93876 (未决)在规范中，针对 Proxy Field（[SWS_CM_11609]、SWS CommunicationManagement §8.3.3.2.4.5 “UnsetSubscriptionStateChangeHandler”）和 Trigger（[SWS_CM_01108]）以及在服务提供端（Skeleton）针对 Event（[SWS_CM_12010]）和 Trigger（[SWS_CM_01112]），也定义了用于重置状态更改处理程序的对称对应物。

使用

命名空间 <SI-Namespace>::proxy::events::<Event> 中的函数 UnsetTransportFaultConditionHandler 用于注销先前为具体代理事件注册的 ara::com::e2e::TransportFaultConditionHandler [SWS_CM_00105]。函数声明通过头文件 <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h 提供 AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.1.3 “UnsetTransportFaultConditionHandler”。该调用不接受任何参数，且不返回值（void）。

错误处理与异常安全性

该函数使用标识符 noexcept 声明，并被规范为异常安全（exception safe）[SWS_CM_00105]。标准中既未定义特定的错误代码，也未定义向错误或诊断子系统的通知。

流程与边界条件

该调用应当是同步执行的，以便在事件层级上立即关闭 E2E 错误处理，例如当不再需要监视该事件时，或者在释放关联的代理对象之前（Interpretation）。 问题 Q-ff00695fff5407fe (未决)执行后，通信层不再通过该事件先前保存的回调来处理 E2E 传输错误。

相互作用

注销传输错误 Handler 遵循跨不同通信元素的统一模式：

• 对于代理层级的字段通知器，使用函数 [SWS_CM_00126]。
• 对于代理触发器，Handler 通过 [SWS_CM_00108] 注销。
• 在 Skeleton 端，为服务接口的所有方法（[SWS_CM_00095]）以及字段的 Getter/Setter（[SWS_CM_00098]）提供了类似的接口。

使用

方法 Unsubscribe() 在代理端终止服务事件的活动订阅（[SWS_CM_00151]、EXP_ARAComAPI §5.5）。它在作用域 <SI-Namespace>::proxy::events::<Event> 中定义，并通过头文件 #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" 包含（[SWS_CM_00151]）。该函数不接受任何传入参数，且没有返回值（void）。如果在调用时该事件未被订阅，则方法直接返回而不执行任何操作（[SWS_CM_00151]）。

错误处理与异常安全性

该操作使用标识符 noexcept 声明，并被规范为异常安全（[SWS_CM_00151]）。如果在调用方法之前违反了 [SWS_CM_00085] 规定的前置条件，则规定违反应为 DanglingSamplesViolation（[SWS_CM_00151]）。

相互作用与相关接口

在网络层面上，终止订阅会触发 StopSubscribeEventgroup 类型的 SOME/IP 消息发送（[SWS_CM_10378]、SWS_CommunicationManagement §7.2.1.2.6）。在代理接口内，Unsubscribe() 属于订阅管理方法组（EXP_ARAComAPI §5.3.1）。相同的取消订阅语义也适用于服务触发器（[SWS_CM_00810]、EXP_ARAComAPI §4）以及 Field 通知（[SWS_CM_11602]）。