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

用法与语义

静态工厂方法Create用于根据[SWS_CM_10438]按照具名构造函数惯用法（Named-Constructor-Idiom）无异常地创建代理实例（<SI>Proxy）。它需要一个事先根据[SWS_CM_00131]确定的服务句柄作为参数handle。该调用同步进行，并被声明为noexcept。结果在ara::core::Result中返回，在成功情况下，该对象包含就绪可用的代理实例。

错误处理

如果在实例化期间发生错误，Create将通过ara::core::Result返回类型为ara::com::ComErrc的错误代码[SWS_CM_10438]：

• ComErrc::kServiceNotAvailable：服务在先前通过OfferService()提供后不再可用。
• ComErrc::kCommunicationFailure：网络绑定报告可恢复的通信错误或安全连接建立失败。

这两种错误都具有回滚语义[SWS_CM_10438]。对于结构性或安全性相关错误，适用的违规（Violations）规则为：如果传入的句柄为 null 或损坏，则存在ErroneousServiceHandleViolation。如果调用进程在授权强制执行（Grant Enforcement）框架内缺少该实例所需的权限，则请求将被拒绝并被视为InsufficientPermissionsViolation（SWS CommunicationManagement §8 “Security”、[SWS_CM_10438]）。

并发性与边界条件

解释：由于Create同步工作并绑定通信资源，因此针对不同句柄的调用可能是可重入的，但由于可能涉及网络初始化，不应在时间关键的硬实时循环中执行。 问题 Q-f7ba23670f562788 (未决)

Proxy 类的静态方法 FindService 用于根据 ara::com::InstanceIdentifier 同步查找可用的服务实例（[SWS_CM_00122]）。调用立即将结果作为 ara::core::Result 返回，成功执行时该结果包含一个 ara::com::ServiceHandleContainer（[SWS_CM_00122]）。此容器（通常实现为 ara::core::Vector（[SWS_CM_00304]））根据当前的提供状态可以为空、包含单个实例句柄或包含多个句柄（ARAComAPI §6.5 “Service Discovery”）。

在发生错误时，当网络绑定报告可恢复的传输错误或安全通信问题时，ara::core::Result 会返回来自 ara::com::ComErrc 的错误代码，即 ComErrc::kCommunicationFailure（[SWS_CM_00122]）。此外，该访问受权限检查约束；权限不足会导致 InsufficientPermissionsViolation（[SWS_CM_00122]）。

关于流程和并发性，适用以下条件：

• 调用上下文与同步性：由于搜索是立即执行的，因此只能找到先前在服务器端为其调用过 OfferService() 的实例（ARAComAPI §6.5 “Service Discovery”）。
• 异常安全性与可重入性：该函数被指定为 noexcept 且为异常安全（[SWS_CM_00122]）。由于该方法是静态的且不需要可变对象状态，因此推测它可以可重入且线程安全地被调用。 问题 Q-3228cc998c4a737e (未决)
• 后续处理：找到的句柄用于通过构造函数 Proxy(const HandleType &handle) 实例化 Proxy 对象（[SWS_CM_00131]）。对于基于模型的搜索，备选提供了带有 ara::core::InstanceSpecifier 的重载（[SWS_CM_00622]）。

根据 [SWS_CM_00622]，Proxy 类的静态函数 FindService 用于基于 ara::core::InstanceSpecifier 同步查找可用服务实例并立即返回（“immediately returned request”）。能够查找到的前提是，相应的服务 Skeleton 实例此前已通过 OfferService() 提供（ARAComAPI 第103页 “Figure 6.5: Service Discovery”）。

返回值与相互协作

作为结果，该调用根据 [SWS_CM_00622] 返回一个带有 ara::com::ServiceHandleContainer 的 ara::core::Result，其默认基于 ara::core::Vector [SWS_CM_00304]。该容器可以为空，包含单个句柄，或包含多个找到的实例（ARAComAPI 第103页 “Figure 6.5: Service Discovery”）。随后，获取的服务句柄被传递给构造函数以实例化 Proxy 对象 [SWS_CM_00131]。对于带通知的事件驱动异步搜索，可备选使用 StartFindService [SWS_CM_00623]，而对于实例标识符，则使用来自 [SWS_CM_00122] 的重载。

错误处理与边界条件

该函数被声明为 noexcept，且根据 [SWS_CM_00622] 视为异常安全（“exception safe”）。在发生错误时，Result 对象包含错误代码 ComErrc::kCommunicationFailure，例如在网络绑定出现通信故障时 [SWS_CM_00622]。此外，[SWS_CM_00622] 还定义了模型和权限违规，如 InstanceSpecifierMappingIntegrityViolation、PortInterfaceMappingViolation、ProcessMappingViolation、InstanceSpecifierAlreadyInUseViolation 以及 InsufficientPermissionsViolation。

Interpretation: 鉴于同步和立即可返回的特性，该方法可能主要适用于初始初始化阶段或有针对性的轮询，前提是不需要通过回调进行持续观察。 问题 Q-ea5b242a6fe41d20 (未决)

使用

显式构造函数 <SI>Proxy 在命名空间 <SI-Namespace>::proxy 中实例化类型特定的服务 Proxy 类 [SWS_CM_00131]。在 Proxy-Skeleton 模式的框架下，此生成的对象在服务使用者端用作本地门面，将方法调用转发给实际的服务实现 ARAComAPI Figure 5.1 “Proxy Skeleton Pattern”。

为了构造，将对有效 HandleType 的引用作为参数传递 [SWS_CM_00131]。此标识符必须事先通过 Service Discovery 机制获取——无论是通过 FindService() 同步获取 [SWS_CM_00122]，还是通过 StartFindService() 注册的回调异步获取 [SWS_CM_00123]。

错误处理

构造并非异常安全（not exception safe）[SWS_CM_00131]。如果无法访问引用的服务，将根据 ara::com::ComErrc::kServiceNotAvailable 触发 ara::com::ComException [SWS_CM_00131]。此外，还定义了以下违规情况：

• ErroneousServiceHandleViolation：当传入的 HandleType 对象为 null 或损坏时发生 [SWS_CM_00131]。
• InsufficientPermissionsViolation：当权限检查（Grant Enforcement）拒绝创建时发生 [SWS_CM_00131]。

限制与生命周期

对于 Proxy 类，拷贝构造函数被明确删除（=delete）[SWS_CM_00136]。实例的传递仅允许通过移动构造函数（Move Constructor）进行，该构造函数同样被指定为非异常安全 [SWS_CM_00137]。在成功创建后，如果目标服务暂时中断并恢复可用，通信管理会在运行时自动在后台更新现有 Proxy 实例的传输层寻址 ARAComAPI Figure 6.1 “Auto Updating of Proxy Instance”。

析构函数 ~<SI>Proxy () 结束服务代理实例的生命周期并释放关联的本地资源 [SWS_CM_99444]。服务代理在消费者端充当本地外观，用于与可能位于远程的服务实现进行交互并转发调用 ARAComAPI §5.1 “Proxy Skeleton Pattern”。代理对象此前通过解析出的服务句柄进行实例化 [SWS_CM_00131]，该句柄由诸如 FindService 之类的服务发现函数提供 [SWS_CM_00122]。

对于销毁和运行时行为，适用以下规范和边界条件：

• 生命周期与语义：销毁在离开作用域或显式删除实例时同步发生。虽然代理类的拷贝构造函数已被删除 [SWS_CM_00136]，但对象在其析构之前可以通过移动语义进行移动 [SWS_CM_00137]。
• 异常安全性：析构函数被指定为非异常安全（not exception safe）[SWS_CM_99444]。
• 前置条件与错误行为：如果违反前置条件 [SWS_CM_00087]，将导致 DanglingSamplesViolation [SWS_CM_99444]。（解释：在调用析构函数之前，推测可能必须释放消费者持有的所有样本引用或数据指针，以避免悬空引用。） 问题 Q-5488797b732d9be6 (未决)
• 交互：如果使用了异步服务搜索，必要时应在释放使用上下文之前通过 StopFindService 终止搜索 [SWS_CM_00125]。此外，为事件、触发器和字段注册的错误处理程序可以预先重置 [SWS_CM_00105] [SWS_CM_00108] [SWS_CM_00126]。

Proxy 类的静态方法 StartFindService [SWS_CM_00123] 通过注册回调处理程序（ARAComAPI §6.5 “Service Discovery”），基于 ara::com::InstanceIdentifier 启动对服务实例的异步搜索。向调用传递 ara::com::FindServiceHandler 以及所搜索的 ara::com::InstanceIdentifier [SWS_CM_00123]。

在成功情况下，该函数返回包含 ara::com::FindServiceHandle 的 ara::core::Result [SWS_CM_00123]。该标识符代表活动的搜索请求，并且是在稍后通过 StopFindService [SWS_CM_00125] 再次终止对服务可用性的监控以及后续处理程序调用所强制必需的。

如果在建立连接时发生通信问题，该方法在 ara::core::Result 中返回错误码 ComErrc::kCommunicationFailure [SWS_CM_00123]。如果传入的可调用对象实例无效或为空，这将被视为 InvalidHandlerViolation；缺少访问权限会导致 InsufficientPermissionsViolation [SWS_CM_00123]。

一旦匹配的服务实例在系统中变为可用，通信管理就会使用相应的服务句柄调用已注册的处理程序 [SWS_CM_00123]。基于所报告的 HandleType，应用程序可以通过具名构造函数方法 Create [SWS_CM_10438] 创建具体的 Proxy 实例。解释：处理程序大概率在通信管理的线程中异步执行，因此在处理程序中访问共享资源应以线程安全方式进行。 问题 Q-9dc570d7e65fc808 (未决)为了通过基于模型的标识符进行搜索，也可以使用带有 InstanceSpecifier 的 StartFindService 作为替代 [SWS_CM_00623]。

Proxy 类的静态方法 StartFindService 基于建模的 ara::core::InstanceSpecifier [SWS_CM_00623] 启动对服务实例的持续搜索。调用时会传入 InstanceSpecifier 以及类型为 ara::com::FindServiceHandler 的回调函数 [SWS_CM_00623]。作为返回值，该函数提供一个 ara::core::Result<ara::com::FindServiceHandle> [SWS_CM_00623]，其在成功注册时提供用于管理搜索的搜索句柄。

错误处理通过返回的 ara::core::Result 进行。如果在网络 Binding 时发生可恢复的通信错误或安全通信错误，结果将包含错误代码 ComErrc::kCommunicationFailure [SWS_CM_00623]。此外还指定了特定的违规行为：若传入的处理程序无效或为空则为 InvalidHandlerViolation，在授权强制执行（Grant Enforcement）导致权限缺失时为 InsufficientPermissionsViolation，以及建模违规如 InstanceSpecifierMappingIntegrityViolation 或 PortInterfaceMappingViolation [SWS_CM_00623]。

关于并发性和边界条件，该函数声明为 noexcept 并指定为异常安全 [SWS_CM_00623]。一旦在系统中检测到匹配的服务实例，注册的处理程序的执行大概率由通信管理异步进行。 问题 Q-79fb3ff78d517714 (未决)

在与相关接口的协作中，以下几点适用：

• 返回的 ara::com::FindServiceHandle 必须予以保留，以便通过 StopFindService [SWS_CM_00125] 终止正在进行的搜索并停止接收进一步的通知。
• 通过回调提供的句柄（HandleType）通常用于通过工厂方法 Create [SWS_CM_10438] 实例化 Proxy 对象。
• 除了通过 InstanceSpecifier 搜索之外，也可以使用 ara::com::InstanceIdentifier 发起搜索 [SWS_CM_00123]。

方法 SetServiceStateChangeHandler 用于在 Proxy 实例上注册回调函数，以监视相应服务的可用性变化（[SWS_CM_01074]、SWS CommunicationManagement §8.3.8.2.4.6 “SetServiceStateChangeHandler(ara::com::ServiceStateHandler)”）。一旦服务可用性状态（ServiceState）发生改变，通信管理就会调用此处理程序（[SWS_CM_01074]）。

作为参数传递的是一个类型为 ara::com::ServiceStateHandler 的函数对象，该对象被指定为 std::function<void(ServiceState)>（[SWS_CM_01072]）。该函数没有返回值。在运行时允许通过重新调用来覆盖已注册的处理程序（[SWS_CM_01074]）。

在错误处理方面，该函数被声明为异常安全的（noexcept）（[SWS_CM_01074]）。如果传入的 Callable 不存在或为 null，则构成违规 InvalidHandlerViolation（[SWS_CM_01074]）。

关于执行环境，[SWS_CM_01074] 代表基础接口。由于此处无法传递 Executor，该回调大概会在通信管理的内部线程上下文中执行。 问题 Q-7833435e7aa1da9f (未决)如果需要在特定应用程序上下文中执行，可备选使用带有符合 [SWS_CM_01076] 的 executor 的重载模板变体（SWS CommunicationManagement §8.3.8.2.4.5 “SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)”）。

用法与调用上下文

模板方法 SetServiceStateChangeHandler 用于在生成的Proxy类 <SI-Namespace>::proxy::<SI>Proxy 上注册用于监控服务可用性的回调 [SWS_CM_01076]。该函数接受两个参数 AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.5 “SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)”：

• handler：类型为 ara::com::ServiceStateHandler（定义为 std::function<void(ServiceState)>）的仿函数，在每次可用性状态发生变化时被调用 [SWS_CM_01072]，[SWS_CM_01074]。
• executor：符合 [SWS_CM_11360] 的模板类型 ExecutorT 的执行上下文，已注册的处理程序将在其中执行 [SWS_CM_01076]。

该函数没有返回值（void）[SWS_CM_01076]。

错误处理与异常安全性

该函数被声明为 noexcept，并被指定为异常安全（exception safe）[SWS_CM_01076]。如果传入的可调用处理程序不存在或是 null，则会引发 InvalidHandlerViolation [SWS_CM_01076]。

并发性与限制

已注册的处理程序可以在运行时被覆盖 [SWS_CM_01074]。由于执行是通过传入的 executor 对象进行的 [SWS_CM_01076]，因此通知推测将在用户提供的线程或调度上下文中异步处理。 问题 Q-349c5224c3b9cc20 (未决)

相互作用

该方法在基本变体 [SWS_CM_01074] 的基础上扩展了显式指定执行上下文的功能 [SWS_CM_01076]。要进行集成，需要头文件 <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h，而处理程序类型来自 ara/com/types.h [SWS_CM_01072]。

静态模板方法 StartFindService 启动异步后台监控，以根据 ara::com::InstanceIdentifier 查找服务的实例（[SWS_CM_11352]，EXP_ARAComAPI §5.3.3 “Proxy Class API’s”）。除目标实例（符合 [SWS_CM_00122] 的 instance）外，还会注册一个回调函数（符合 [SWS_CM_00123] 的 handler）以及一个执行上下文（符合 [SWS_CM_11360] 的模板类型 ExecutorT 的 executor）（[SWS_CM_11352]）。回调通知大概率会在传入的 executor 的线程或任务上下文中处理（[SWS_CM_11352]）。 问题 Q-1db520123c1e49a4 (未决)

作为返回值，该调用返回一个 ara::com::FindServiceHandle（[SWS_CM_11352]）。该句柄用于标识正在进行的搜索活动，并且后续通过 [SWS_CM_00125]（StopFindService）显式终止后台活动时需要用到它（EXP_ARAComAPI §5.3.3 “Proxy Class API’s”）。通过已注册回调接收到的服务句柄（HandleType）随后用于构造关联的 Proxy 实例（[SWS_CM_00131]）。

该函数声明为 noexcept 并被指定为异常安全（exception safe）（[SWS_CM_11352]）。定义了以下运行时违规（Violations）：

• InvalidHandlerViolation：当传入的处理程序函数无效或等于 null 时发生（[SWS_CM_11352]）。
• InsufficientPermissionsViolation：当访问被授权系统（Grant Enforcement）拒绝时发生（[SWS_CM_11352]）。

如果需要改为通过基于模型的 ara::core::InstanceSpecifier 搜索服务，则可以使用替代函数变体 [SWS_CM_11365]。

静态模板函数 StartFindService 根据 ara::core::InstanceSpecifier 启动对服务实例的持续、异步搜索，并在传入的执行上下文中注册通知处理程序 [SWS_CM_11365]。与同步单次搜索不同，它会触发用于监控服务可用性的后台活动，并返回一个 ara::com::FindServiceHandle EXP_ARAComAPI §5.3 “Proxy Class APIs”。

参数与执行

该函数接收三个参数 [SWS_CM_11365]：

• handler：类型为 ara::com::FindServiceHandler（符合 [SWS_CM_00123]）的回调函数，在实例可用性发生变更时被调用。
• instance：要搜索的 ara::core::InstanceSpecifier（符合 [SWS_CM_00123]）。
• executor：模板类型为 ExecutorT（符合 [SWS_CM_11360]）的执行上下文。解释：模板实参 ExecutorT 大概率决定了已注册的回调在哪个线程或任务上下文中执行。 问题 Q-6d46f67d536a391e (未决)

错误处理与边界条件

该签名声明为 noexcept 并被指定为 exception safe [SWS_CM_11365]。规范定义了以下功能性违规（Violations）：InstanceSpecifierMappingIntegrityViolation（在可执行程序上下文中解析失败或不是 PortPrototype）、PortInterfaceMappingViolation 和 ProcessMappingViolation（不匹配的 PortInterface 映射）、InstanceSpecifierAlreadyInUseViolation、InvalidHandlerViolation（无效或不存在的处理程序）以及缺少访问权限时的 InsufficientPermissionsViolation [SWS_CM_11365]。

相互作用

获取到的 FindServiceHandle 用于通过传递给 StopFindService 来受控地终止正在进行的后台监控 [SWS_CM_00125]。上报给处理程序的句柄用于通过 Proxy(handle) 实例化具体服务 Proxy [SWS_CM_00131]。对于使用 ara::com::InstanceIdentifier 进行的搜索，存在一个替代重载 [SWS_CM_11352]。

Proxy 类的静态函数 StopFindService 终止此前通过 StartFindService 启动的异步服务搜索，并停止接收针对所传递句柄的进一步通知 [SWS_CM_00125]。从而停止通过技术绑定监控服务可用性的正在运行的后台活动 AP EXP ARAComAPI §5.3 “Proxy Class API’s”。

用法与语义

• 参数：作为输入参数，该函数需要一个此前通过 StartFindService 方法之一获取的 ara::com::FindServiceHandle（[SWS_CM_00123]、[SWS_CM_00623]、[SWS_CM_11352]、[SWS_CM_11365]、[SWS_CM_00125]）。
• 返回值与异常安全性：该函数不提供返回值（void），使用 noexcept 声明并指定为异常安全 [SWS_CM_00125]。
• 并发性与调用上下文：明确允许直接在用户定义的回调函数 FindServiceHandler [SWS_CM_00383] 内调用 StopFindService AP EXP ARAComAPI §5.3 “Proxy Class API’s”。为此，相应的 FindServiceHandle 作为参数传递给处理程序 [SWS_CM_00383]。由于回调本身不必是可重入的，因此连续调用的串行化必须由绑定实现者来确保 AP EXP ARAComAPI §5.3 “Proxy Class API’s”。

根据 [SWS_CM_01075]（AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.12 “UnsetServiceStateChangeHandler”），成员函数 UnsetServiceStateChangeHandler 是命名空间 <SI-Namespace>::proxy::<SI>Proxy 中生成的代理类的组成部分。它通过头文件 #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" 引入。

关于使用、行为和并发性，适用以下规定：

• 使用：该方法具有签名 void UnsetServiceStateChangeHandler() noexcept;。它不接收参数且不返回任何值。解释：根据标识符以及对 [SWS_CM_01074] 的引用，该调用用于重置或注销此前在代理实例上注册的用于服务状态更改的回调处理程序。 问题 Q-6eb71298a6f37ad9 (未决)
• 错误处理与异常安全性：该操作被声明为 noexcept 并被指定为异常安全（exception safe）（[SWS_CM_01075]）。它不引发异常，也不向调用方返回错误代码。
• 交互与边界条件：功能语义参见 [SWS_CM_01074] 中的定义。解释：注销推测可能同步生效，因此在函数调用返回后，将不再通过先前的回调传递进一步的状态转换。 问题 Q-31348a50d9be537d (未决)