类 <SI-Namespace>::proxy::fields::<Field>

使用

方法 Get 在代理作用域 <SI-Namespace>::proxy::fields::<Field> 中用于异步检索当前字段值（[SWS_CM_00112]；另见 AUTOSAR_AP_EXP_ARAComAPI §6 “FieldGet”）。该函数通过代理头文件 <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h 提供，并且仅在为该字段建模了 Field.hasGetter == TRUE 时存在（[SWS_CM_00112]）。它不接受任何参数，并返回一个 ara::core::Future<FieldType>，该对象在成功传输后包含当前值（[SWS_CM_00112]）。

错误处理与边界条件

该接口被定义为 noexcept 且异常安全（[SWS_CM_00112]）。如果操作失败，返回的 ara::core::Future 包含具有回滚语义的错误代码（[SWS_CM_00112]）：

• ComErrc::kCommunicationFailure：网络绑定报告可恢复的通信错误或安全通信失败（[SWS_CM_00112]）。
• ComErrc::kMinimumSendIntervalViolationError：发送请求的发生速度快于该元素配置的最小发送间隔（minimumSendInterval）所允许的速度（[SWS_CM_00112]）。
• InsufficientPermissionsViolation：执行被授权执行（Grant Enforcement）拒绝（[SWS_CM_00112]）。

Getter 不存在应用程序错误（Application Errors）（[SWS_CM_00113]）。

相互作用

在骨架端，Getter 请求的处理以前提为通过 RegisterGetHandler 配置的回调（[SWS_CM_00114]）。每次调用 Get() 都会执行端到端检查（E2E）；由此产生的状态信息可以在代理端通过 GetE2EStateMachineStateGetter 同步查询（[SWS_CM_00145]）。

用法与调用上下文

函数 Set 在命名空间 <SI-Namespace>::proxy::fields::<Field> 中提供，并且仅在为字段 Field.hasSetter == TRUE 进行了配置时才可用 [SWS_CM_00113]。在使用之前，必须已在服务端提供该服务实例（OfferService()），并在客户端找到并连接 ARAComAPI §4.2 “Means of Communication”。该调用以异步方式进行：它通过参数 value 传递新的字段值，并返回一个 ara::core::Future<FieldType> [SWS_CM_00113]。该方法被指定为 noexcept 且视为异常安全的 [SWS_CM_00113]。

错误处理

如果传输失败，相应的错误将通过返回的 ara::core::Future 提供 [SWS_CM_00113]：

• ComErrc::kCommunicationFailure：报告可恢复的通信错误或安全传输故障；在发生超时的情况下，服务端可能处于未定义状态且不具备回滚语义 [SWS_CM_00113]。
• ComErrc::kMinimumSendIntervalViolationError：当发送请求的发出速度快于配置的最小发送间隔（minimumSendInterval）时发生（同样不具备回滚语义）[SWS_CM_00113]。
• 缺少访问权限会导致被 Grant Enforcement 拒绝（InsufficientPermissionsViolation）[SWS_CM_00113]。
• 应用程序错误不是通过异常传递的，而是在 Future 成功时返回一个与请求参数不同的值 [SWS_CM_00113]。

协同交互与并发性

在服务端，该调用对应于 Skeleton 实例上的一个回调，该回调此前必须已通过 RegisterSetHandler 注册 [SWS_CM_00116] ARAComAPI §4.2 “Means of Communication”。为了监控客户端的 E2E 传输安全性，可以通过 GetE2EStateMachineStateSetter() 查询上一次 Set() 调用的 E2E 状态机状态 [SWS_CM_00146]。

用法与调用上下文

函数SetReceiveHandler在代理端命名空间<SI-Namespace>::proxy::fields::<Field>中通过头文件<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h提供（[SWS_CM_11605]）。它在客户端注册一个用于字段值更改通知的回调（[SWS_CM_11605]）。该机制遵循事件的通知流程，从而 Communication Management 会在发生更新时通知客户端（EXP_ARAComAPI §4.2 “Means of Communication”）。

传递一个ara::com::FieldReceiveHandler作为参数，它表示一个无参函数（[SWS_CM_11605]）。该函数不返回任何返回值（void），并被指定为异常安全（noexcept）（[SWS_CM_11605]）。

错误处理与并发

如果传入的 Callable 对象不存在或为 null，该函数将报告违规InvalidHandlerViolation（[SWS_CM_11605]）。如果处理程序的执行应在定义的执行上下文中进行，则可以使用带有ExecutorT的模板变体（[SWS_CM_11611]）。

相互作用

该行为对应于事件（[SWS_CM_00181]）和触发器（[SWS_CM_00250]）的处理程序注册。遵循代理类的接口模式，注销注册推测应通过UnsetReceiveHandler()进行（EXP_ARAComAPI §5.3.1 “Proxy Class API’s”）。 问题 Q-74cd83b99aadec16 (未决)

用法与调用上下文

模板函数SetReceiveHandler是代理类class <SI-Namespace>::proxy::fields::<Field>的一部分（[SWS_CM_11611]；头文件#include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h"）。它用于在客户端注册一个用于字段值更改通知的接收处理程序（AUTOSAR_AP_EXP_ARAComAPI §4.2 “Means of Communication”、[SWS_CM_11605]）。通过参数传递类型为ara::com::FieldReceiveHandler的可调用对象handler以及作为通用引用ExecutorT&&的执行上下文executor（[SWS_CM_11611]）。该函数没有返回值（void）。

错误处理与异常安全性

该方法被声明为noexcept，并被指定为异常安全（exception safe）（[SWS_CM_11611]）。如果传入的 Callable handler不存在或为 null，则存在InvalidHandlerViolation（[SWS_CM_11611]）。因此，调用方必须确保在调用之前提供有效的函数或函数对象。

并发性与交互

与不带执行器的标准注册（[SWS_CM_11605]）不同，当字段通知到达时，回调将在由executor提供的执行上下文中处理（[SWS_CM_11611]）。解释：这推测会产生解耦效果，使得特定于应用的数据处理不会在内部中间件线程的执行上下文中进行。 问题 Q-cbe1af19bea15a88 (未决)该方法属于代理类 API（AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”），并遵循与事件的执行器变体（[SWS_CM_11356]基于[SWS_CM_00181]）以及触发器的执行器变体（[SWS_CM_00352]基于[SWS_CM_00250]）相同的模式。

函数 SetSubscriptionStateChangeHandler 在 Proxy 字段（作用域 <SI-Namespace>::proxy::fields::<Field>）上注册一个用户定义的回调，一旦字段的订阅状态（ara::com::SubscriptionState）发生变化，Communication Management 就会调用该回调（[SWS_CM_11607]，[SWS_CM_00333]）。调用以同步方式进行且不返回值（[SWS_CM_11607]）。它是用于管理事件与字段订阅的核心 Proxy 接口之一（AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”）。

在错误处理方面，注册函数被指定为 exception safe 并声明为 noexcept（[SWS_CM_11607]）。如果传入的可调用对象 handler 不存在或为 null，则构成形式为 InvalidHandlerViolation 的规范违规（[SWS_CM_11607]）。

在与连接建立的相互协作中需要注意，Subscribe() 原则上必须被视为异步操作（[SWS_CM_12006]）。因此，即使 Subscribe() 无错误返回，应用程序也只有在已注册的处理程序指示了状态 kSubscribed 后，方可认为订阅成功（[SWS_CM_12006]）。此外，如果实际绑定无法立即完成，或者服务器实例例如由于重启或网络错误而发生故障，Communication Management 也会使用 kSubscriptionPending 调用该处理程序（[SWS_CM_00313]）。如果处理程序应在特定的执行上下文中运行，则可以使用带有 ExecutorT 的重载模板变体（[SWS_CM_11608]）。

命名空间<SI-Namespace>::proxy::fields::<Field>中的模板函数SetSubscriptionStateChangeHandler用于注册一个回调函数，以监视字段订阅的状态更改（[SWS_CM_11608]）。它扩展了[SWS_CM_11607]中的基本行为，使注册的处理程序在显式传入的执行上下文（executor）中执行（[SWS_CM_11608]）。

该方法接收两个参数（[SWS_CM_11608]）：

• handler：要调用的类型为ara::com::SubscriptionStateChangeHandler的回调（[SWS_CM_11354]），一旦ara::com::SubscriptionState发生更改即会触发（[SWS_CM_00333]）。
• executor：类型为ExecutorT&&的转发引用（[SWS_CM_11360]），它为处理程序的执行提供上下文（[SWS_CM_11608]）。

该函数不返回任何返回值（void），并被声明为noexcept（[SWS_CM_11608]）。它被指定为 exception safe（[SWS_CM_11608]）。如果传入的 Callable 不存在或为null，则定义了违规InvalidHandlerViolation（[SWS_CM_11608]）。

解释：通过传递executor，处理程序的执行推测将从通信管理的内部上下文转移到应用程序的线程或任务上下文中。 问题 Q-647f618545799c4e (未决)在代理 API 的交互中，该调用与Subscribe()、Unsubscribe()和UnsetSubscriptionStateChangeHandler()等方法并列（AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”）。针对代理事件（[SWS_CM_11354]）以及代理触发器（[SWS_CM_01106]），存在类似的带有执行上下文的重载变体。

用法与调用上下文

成员函数 SetTransportFaultConditionHandler 用于在命名空间 <SI-Namespace>::proxy::fields::<Field> [SWS_CM_00109] 中为 Proxy 字段的通知器注册错误处理程序。类型为 ara::com::e2e::TransportFaultConditionHandler 的可调用对象（Callable）作为参数传递。该函数不提供返回值，并将回调绑定到各个服务实例的通知器，以接收通信后端的传输错误 AUTOSAR_AP_SWS_CommunicationManagement §7.4 “End-to-end communication protection” 第235页。

错误处理与异常安全性

该方法被声明为 noexcept 并指定为异常安全（exception safe）[SWS_CM_00109]。如果传入的可调用对象无效或为 null，则存在形式为 InvalidHandlerViolation 的前置条件违规 [SWS_CM_00109]。解释：由于该函数不允许抛出异常，因此在 AUTOSAR Adaptive 中此类违规行为通常会导致程序立即中止。 问题 Q-74df6934d4ae3c93 (未决)

并发性与交互

虽然此基本形式直接注册处理程序，但 [SWS_CM_00110] 提供了重载的模板变体，该变体额外接收一个执行器（ExecutorT&& executor）以指定异步执行上下文。该函数融入了端到端错误处理中：通知器（[SWS_CM_00109]，[SWS_CM_00110]）、事件（[SWS_CM_00099]）和触发器（[SWS_CM_00106]）通过此类处理程序异步报告传输错误，而在方法以及 Getter 和 Setter 请求时的传输错误则通过生成的 ara::core::Future 中的 ComErrc::kCommunicationFailure 返回 [SWS_CM_00090]。

使用

模板成员函数 SetTransportFaultConditionHandler 在代理字段类的作用域（<SI-Namespace>::proxy::fields::<Field>）内用于为相应字段的通知器注册 Handler [SWS_CM_00110]。它接受两个输入参数：

• handler：要注册的类型为 ara::com::e2e::TransportFaultConditionHandler 的 Callable [SWS_CM_00110]。
• executor：对 Executor 对象（ExecutorT&&）的右值引用，任何异步触发的计算都将在该对象的执行上下文中启动 [SWS_CM_00110]。

该函数不返回值（void），并声明为 noexcept [SWS_CM_00110]。

错误处理与执行安全性

该接口被规范为异常安全（exception safe）[SWS_CM_00110]。如果将不存在或为 null 的 Callable 作为 handler 传递，将导致 InvalidHandlerViolation [SWS_CM_00110]。通过此 Handler 报告特定的传输错误条件，而方法以及字段的 Getter 和 Setter 则通过其各自返回的 Future 上的 ComErrc::kCommunicationFailure 指示可能发生的传输错误 [SWS_CM_00090]。

并发性与交互

该方法构成了参数较少的基础函数 [SWS_CM_00109] 的 Execution Context 重载。通过传入的 Executor 对象，该实现将 Handler 的执行与 Communication Management 的内部接收上下文解耦 [SWS_CM_00110]。针对代理事件 [SWS_CM_00100]、代理触发器 [SWS_CM_00107] 以及 Skeleton 方法 [SWS_CM_00094] 和 Skeleton 字段 [SWS_CM_00097] 也提供了同类的重载。Interpretation：该调用适宜在通知器消息到达或订阅通知器之前进行，以确保无缝的错误监控。 问题 Q-bc5c62dd39c09029 (未决)

方法 Subscribe 用于订阅作用域 proxy::fields::<Field> 中服务 Proxy 实例的 Field 的通知（[SWS_CM_11601]）。通过参数 maxSampleCount，应用程序可以确定其希望同时持有的数据样本的最大数量，从而建立本地接收缓存（[SWS_CM_11601]，EXP ARAComAPI §5.3 “Proxy Class API’s”）。该调用是异步的：返回的 ara::core::Result<void> 仅表示 Communication Management 已接受该订阅（EXP ARAComAPI §5.3.5.2 “Monitoring Event Subscription”）。

关于状态行为和错误处理，适用以下规则：

• 幂等性：如果 Field 已处于状态 kSubscribed 或 kSubscriptionPending，且传入的 maxSampleCount 与当前订阅的值一致，则该方法返回且不产生任何效果（[SWS_CM_11601]）。
• 错误码：如果无法提供所要求的缓存，则操作失败并返回错误 ComErrc::kMaxSampleCountNotRealizable（[SWS_CM_11601]，[SWS_CM_10432]）。
• 权限检查：如果缺少所需权限，该调用将被授权系统（Grant Enforcement）拒绝，并伴随 InsufficientPermissionsViolation（[SWS_CM_11601]）。

该方法声明为 noexcept 并被指定为 Exception-safe（[SWS_CM_11601]）。在语义上，它遵循事件订阅的行为（[SWS_CM_00141]）；配置的缓存构成了随后通过 GetNewSamples 等方法接收样本的基础（[SWS_CM_00701]）。

在 Proxy 层面上，函数 UnsetReceiveHandler() 用于注销先前注册的字段通知接收处理程序（[SWS_CM_11606]）。它属于 ara::com 的 Proxy 类 API（AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s”），并位于命名空间 <SI-Namespace>::proxy::fields::<Field> 中（[SWS_CM_11606]）。

关于调用上下文和语义，该方法不接收任何参数且不返回值（[SWS_CM_11606]）。通过此调用，应用程序可以随时通过撤销用户特定的回调，从事件驱动的通知模型切换到基于查询的轮询操作（AUTOSAR_AP_EXP_ARAComAPI §5.3.2 “RadarService Proxy Class Example”）。

对于错误处理，该函数被指定为 noexcept 以及 exception safe（[SWS_CM_11606]）；根据规范，不存在特定的错误码。调用以同步方式进行；成功撤回处理程序后，Communication Management 在有新数据到达时不再触发进一步的回调调用（解释：正在运行或已调度的执行大概率会在撤回前完成或串行化处理完毕，因为 Communication Management 触发的回调调用必须串行化进行；参见 AUTOSAR_AP_EXP_ARAComAPI §5.3.2 “RadarService Proxy Class Example”）。 问题 Q-fbc65e80b8d8be38 (未决)

在协同交互方面，该方法与服务事件（[SWS_CM_00183]；AUTOSAR_AP_EXP_ARAComAPI §10）和触发器（[SWS_CM_11614]）中停用触发器相对应。在 DDS 绑定中，该行为通过将 UnsetReceiveHandler() 映射到相应的 DataReader 来实现（[SWS_CM_11141]）。

使用

在 AUTOSAR Adaptive Platform 框架内，方法 UnsetSubscriptionStateChangeHandler 用于移除先前为字段订阅状态变更（ara::com::SubscriptionState）注册的回调 [SWS_CM_11609]。它在命名空间 <SI-Namespace>::proxy::fields::<Field> 中的服务 Proxy 字段实例上同步调用，并要求包含生成的头文件 #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 “UnsetSubscriptionStateChangeHandler”。该调用不接收任何传入参数且不返回任何值。

错误处理与并发

该接口声明为 noexcept，根据规范满足 exception safe 特性 [SWS_CM_11609]。因此排除了发生错误或异常的情况。由于注销立即生效，可以推断（解读）在方法结束之后不再向原处理程序传递新的通知。 问题 Q-30238329b76b64f4 (未决)

相互作用

该函数属于 ara::com AUTOSAR_AP_EXP_ARAComAPI §5.3.1 “Proxy Class API’s” 中用于管理订阅的基础 Proxy 类 API。用于停用状态变更处理程序的同类方法存在于 Proxy 事件 [SWS_CM_00334] 和触发器 [SWS_CM_01108] 中，并且对等地存在于 Skeleton 端的事件 [SWS_CM_12010] 和触发器 [SWS_CM_01112] 中。

使用

函数 UnsetTransportFaultConditionHandler 用于重新注销先前为特定代理字段的通知器注册的 ara::com::e2e::TransportFaultConditionHandler [SWS_CM_00126]。它在作用域 <SI-Namespace>::proxy::fields::<Field> 内定义，并通过头文件 <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h 引入 AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.1.4 “UnsetTransportFaultConditionHandler”。该调用无参数进行，且不返回值（void）。

错误处理

该方法被声明为 noexcept，并具有 exception safe 异常保证 [SWS_CM_00126]。不返回错误代码，也不抛出异常。如果先前未注册任何 Handler，重复调用大概不会产生任何影响。 问题 Q-85da9a7b00678748 (未决)

并发性与限制

该规范未定义单独的并发或线程安全要求。由于该接口同步工作且不使用异步类型，因此撤销错误处理程序的操作应能同步且立即生效。 问题 Q-ed4cc712bb55aee5 (未决)调用方应在应用程序生命周期中协调该调用，以使单个服务实例的通知程序（Notifier）消息不会在没有处理程序的情况下不受控地被处理AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 “End-to-end communication protection for SOMEIP”。

相互作用

注销在 AUTOSAR Adaptive 中遵循一致的命名与功能模式：

• 在 Proxy 级别，为事件（[SWS_CM_00105]）以及触发器（[SWS_CM_00108]）提供了等效函数。
• 在 Skeleton 级别，存在用于字段 Getter 和 Setter（[SWS_CM_00098]）以及统一用于 Skeleton 接口所有方法（[SWS_CM_00095]）的对应对等项。