类 ara::nm::NetworkHandle

用法与生命周期

类 NetworkHandle 用作访问通过 ara::core::InstanceSpecifier 寻址的网络句柄的访问对象，并专用于 State Management [SWS_ANM_01000]。通过传递 NetworkManagementPortInterface 端口原型的 Instance Specifier 来进行实例化 [SWS_ANM_01001]。由于该类被声明为 final，因此它不能用作派生的基类 [SWS_ANM_01000]。

移动语义与并发性

该类的对象具有纯移动语义：复制构造函数 [SWS_ANM_01005] 以及复制赋值运算符 [SWS_ANM_01006] 已被删除（= delete）。实例可以改为通过移动构造函数 [SWS_ANM_01003] 和移动赋值运算符 [SWS_ANM_01004] 进行转移。

关于线程安全，适用以下规定：

• 带有 InstanceSpecifier 的构造函数是线程安全的（thread-safe）[SWS_ANM_01001]。
• 对于移动构造函数，线程安全是由实现定义的（implementation-defined）[SWS_ANM_01003]。
• 析构函数 [SWS_ANM_01002] 和移动赋值 [SWS_ANM_01004] 被显式标为非线程安全（not thread-safe）。Interpretation：由于不保证线程安全，因此如果多个线程使用同一句柄，调用上下文推测应负责外部同步。 问题 Q-7172baaffab79218 (未决)

错误处理

所有构造函数、赋值运算符以及析构函数均被声明为 noexcept [SWS_ANM_01001]、[SWS_ANM_01002]、[SWS_ANM_01003]、[SWS_ANM_01004]。在此类接口中未规定异常或错误返回值。

来自头文件 ara/nm/network_handle.h 的类型别名 NetworkStateChangeNotifier 定义了网络状态变更时回调函数的函数包装器 [SWS_ANM_01020]。签名 std::function<void(const NetworkStateType&)> 接受对 NetworkStateType 的常量引用作为表示新状态的参数，并且没有返回值 [SWS_ANM_01020]。

该 Notifier 在通过两个注册点监控 Network Management 时使用：

• 为了指示有效网络状态，通过 RegisterNetworkStateChangeNotifier 注册 Notifier [SWS_ANM_01010]。或者，模板重载允许传递自定义的 executor，Notifier 将在其上下文中执行 [SWS_ANM_01015]。每个实例最多可以激活一个 Notifier [SWS_ANM_01010]。
• 对于所请求网络状态的通知，通过 RegisterNetworkRequestedStateChangeNotifier 进行注册，可以选择直接注册 [SWS_ANM_01012]，也可以指定目标执行器 [SWS_ANM_01014]。此处最多也只允许一个处理程序 [SWS_ANM_01012]。

关于错误处理，所有注册函数均返回 ara::core::Result<void>；如果注册失败，则报告错误 NmErrc::kInvalidHandler [SWS_ANM_01010]、[SWS_ANM_01012]。当传递未完全初始化或为空的函数对象时，可能特别会发生这种情况。 问题 Q-04452871df619a94 (未决)

作为一项限制，NetworkStateChangeNotifier 被规范为非线程安全（not thread-safe）[SWS_ANM_01020]。相关的注册函数同样设计为非线程安全 [SWS_ANM_01010]、[SWS_ANM_01012]。因此，调用方必须确保赋值和注册以同步或顺序方式进行。

枚举 NetworkStateType 表示 anm（Adaptive Network Management）模块中网络的状态 [SWS_ANM_01358]。它区分了非活动状态 kNoCom = 0（只要并非所有关联网络都处于 FULL_COM 状态）和活动状态 kFullCom = 1（当所有关联网络都处于 FULL_COM 状态时）[SWS_ANM_01358]。

该类型在 ara/nm/network_handle.h 的接口中得到广泛应用：

• 状态查询：方法 GetNetworkState() 以同步且线程安全的方式将当前有效网络状态作为 ara::core::Result<NetworkStateType> 返回 [SWS_ANM_01007]。同样，GetNetworkRequestedState() 以线程安全的方式读取针对 PNC、VLAN 或物理网络当前请求的状态 [SWS_ANM_01008]。
• 状态请求：通过 SetNetworkRequestedState(NetworkStateType networkState) 主动请求（kFullCom）或释放（kNoCom）PNC、VLAN 或物理网络的状态 [SWS_ANM_01009]。该操作被规范为非线程安全 [SWS_ANM_01009]。
• 事件通知：该类型通过函数包装器 NetworkStateChangeNotifier（std::function<void(const NetworkStateType&)>）作为参数传递，以便向应用逻辑通知状态变更 [SWS_ANM_01020]。

错误处理：通过上述方法查询或设置 NetworkStateType 时，若发生错误，可以在 ara::core::Result 中返回代码 NmErrc::kServiceNotAvailable [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009]。

使用

来自头文件 ara/nm/network_handle.h 的函数 RegisterNetworkRequestedStateChangeNotifier 注册一个回调函数，用于接收请求的网络状态变更的通知 [SWS_ANM_01012]。它接受一个 NetworkStateChangeNotifier 作为参数。针对请求的状态变更，最多只能注册一个通知器 [SWS_ANM_01012]。该函数声明为 noexcept 并返回一个 ara::core::Result<void>。

错误处理

如果在注册时发生错误，将通过 ara::core::Result 报告特定的错误代码 NmErrc::kInvalidHandler [SWS_ANM_01012]。Interpretation：当传入的通知器无效或不可调用时，可能会触发此错误。 问题 Q-57a28e90a933e6de (未决)

并发性与限制

该函数被规范为非线程安全（not thread-safe）[SWS_ANM_01012]。因此，调用方必须对来自多个线程的并发访问和注册尝试进行强制外部同步。

相互作用

作为直接执行的替代方案，函数 [SWS_ANM_01014] 存在一个模板重载，该重载额外接受一个 executor 参数。由此可以在显式提供的执行上下文中运行通知器；该重载同样不是线程安全的，并在出错时报告 NmErrc::kInvalidHandler [SWS_ANM_01014]。

在头文件 ara/nm/network_handle.h 中声明的模板函数 RegisterNetworkRequestedStateChangeNotifier 注册一个类型为 NetworkStateChangeNotifier 的回调，以便接收请求的网络状态变更通知 [SWS_ANM_01014]。通过类型为 ExecutorT&& 的附加参数 executor 指定所需的执行上下文，当状态发生变更时，该通知器应在其中执行。用于 Handler 注册的同步调用被声明为 noexcept，并向调用方返回一个 ara::core::Result<void>。

对于错误处理，该接口通过返回类型 ara::core::Result 指示问题。如果传入无效的 Handler，则操作失败，函数返回特定错误代码 NmErrc::kInvalidHandler [SWS_ANM_01014]。

关于并发性和调用限制，该函数被明确规范为 not thread-safe [SWS_ANM_01014]。这意味着调用方在并发访问同一句柄实例时必须确保外部同步，以避免数据冲突。

在系统交互中，该函数代表参数较少的变体 [SWS_ANM_01012] 的扩展，后者最多为请求的状态变更注册一个通知器。Interpretation：由于 [SWS_ANM_01012] 中的基本规范最多允许一个通知器，该调用大概也会占用同一个通知器槽位，并在重新注册时覆盖先前设置的 Handler。 问题 Q-5d8c1832558ac15b (未决)

使用

函数 RegisterNetworkStateChangeNotifier 用于为有效网络状态注册一个通知器（Notifier）[SWS_ANM_01010]。它在头文件 ara/nm/network_handle.h 中声明，并定义为 noexcept [SWS_ANM_01010]。参数传递一个 NetworkStateChangeNotifier notifier；返回通过 ara::core::Result<void> 同步进行 [SWS_ANM_01010]。针对该状态最多只能注册一个通知器 [SWS_ANM_01010]。

错误处理

在出错时，ara::core::Result 返回错误代码 NmErrc::kInvalidHandler [SWS_ANM_01010]。这向调用方表明传入的 Handler 无效 [SWS_ANM_01010]。

并发性与限制

该接口被明确规范为 not thread-safe [SWS_ANM_01010]。因此，调用组件必须确保对 RegisterNetworkStateChangeNotifier 的调用不会在没有外部同步的情况下并发进行。由于规范最多允许一个通知器，重复调用大概会覆盖或拒绝已有的注册 [SWS_ANM_01010]。 问题 Q-5e3ac4e4d2b33e9f (未决)

相互作用

该函数与模板重载 [SWS_ANM_01015] 直接相关。基础函数在没有显式执行上下文的情况下绑定通知器，而 [SWS_ANM_01015] 允许传递一个额外的参数 ExecutorT&& executor，以便在指定的上下文中控制 Handler 的执行 [SWS_ANM_01015]。这两种变体均实现了 RS_Nm_00051 中的要求，在同一头文件中定义，并共用 not thread-safe 归类以及错误 NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015]。

来自头文件 ara/nm/network_handle.h 的模板函数 RegisterNetworkStateChangeNotifier（[SWS_ANM_01015]）注册一个回调函数，用于监视有效网络状态的变更。与参数较少的变体相比，该接口除了接受类型为 NetworkStateChangeNotifier 的 notifier 之外，还额外接受一个用户定义的执行上下文 executor（ExecutorT&&），通知将通过该上下文异步分派并处理。

错误处理与返回值

该函数被声明为 noexcept，并通过 ara::core::Result<void> 指示结果 [SWS_ANM_01015]。如果在注册时发生错误——特别是当传入无效或不可调用的 Handler 时——操作失败并返回错误代码 NmErrc::kInvalidHandler。

并发性与交互

关于线程安全性，该接口被规范为 not thread-safe [SWS_ANM_01015]。因此，注册调用不得在未受保护的情况下从多个线程并发作用于同一状态上下文。在系统组合中，该函数对基础接口 [SWS_ANM_01010] 进行了补充，后者在没有显式 Executor 的情况下最多注册一个通知器。作为 Interpretation，对 [SWS_ANM_01015] 而言大概也适用始终只有一个通知器处于活动状态，且重新调用会替换先前保存的 Handler。 问题 Q-e9a890e004a4f0ea (未决)

根据 [SWS_ANM_01009]，函数 SetNetworkRequestedState 用于通过头文件 ara/nm/network_handle.h 请求或释放子网簇 (PNC)、VLAN 或物理网络。作为输入参数传递类型为 NetworkStateType 的期望目标状态 networkState。该调用可能同步执行，因为该接口直接返回一个 ara::core::Result<void> 而不是异步 Future 对象。 问题 Q-38a98cab4ea55704 (未决)

成功时，该方法返回一个空的 ara::core::Result<void> [SWS_ANM_01009]。如果无法设置请求的状态或网络管理服务未就绪，函数将在结果对象 [SWS_ANM_01009] 中报告特定的错误代码 NmErrc::kServiceNotAvailable。调用软件组件必须显式评估此错误对象，以便对不可用的服务做出充分响应。

关于并发性，根据规范，该操作被明确归类为 not thread-safe [SWS_ANM_01009]。因此，为了避免竞态条件，不得在没有应用程序端同步的情况下对同一句柄进行并发调用。通过带有 noexcept 的声明，还保证了没有 C++ 异常传播到外部 [SWS_ANM_01009]。

使用

函数 UnregisterNetworkRequestedStateChangeNotifier 属于自适应网络管理（anm）模块，并通过头文件 ara/nm/network_handle.h 声明 [SWS_ANM_01013]。其任务是取消用于请求的网络状态变更的通知器 [SWS_ANM_01013]，从而有助于实现上游需求 RS_Nm_00051。

该接口不接收传入参数，且不提供返回值（void）[SWS_ANM_01013]。Interpretation：由于签名未提供异步结果类型，因此推测该调用同步完成，并且注销在函数返回后立即生效。 问题 Q-df3005625905440a (未决)

错误处理

该函数被指定为 noexcept [SWS_ANM_01013]，因此不抛出异常。规范中既未为调用方规定错误代码，也未规定单独的错误反应。

并发性与限制

关于线程安全，该函数被显式归类为 not thread-safe [SWS_ANM_01013]。因此，调用软件单元必须通过适当的同步措施确保去注册不会与对同一实例的其他访问并发执行。