Overview
The Network Management Functional Cluster coordinates the communication state of
partial networks, VLANs and physical channels. This page specifies the public API
of the ara::nm namespace — network state query, requested-state control,
state-change notifiers, and the associated error domain — organized by header file.
- Library:
lib/libpara_nm.so
- CMake:
find_package(para-nm) → para::nm
- Standard headers:
include/ara/nm/
- Runtime daemon:
bin/NM
1 Header: ara/nm/network_handle.h
1.1 Class: NetworkHandle
| Kind: | class |
| Port Interfaces: | NetworkManagementPortInterface |
| Header file: | #include "ara/nm/network_handle.h" |
| Forwarding header file: | #include "ara/nm/nm_fwd.h" |
| Scope: | namespace ara::nm |
| Symbol: | NetworkHandle |
| Syntax: | class NetworkHandle final {...}; |
| Description: | Class NetworkHandle is the access to the network handle referenced by the ara::core::InstanceSpecifier. Provides information about network state per NetworkHandle. Intended to be only used by StateManagement |
1.1.1 Public Member Types
1.1.1.1 Type Alias: NetworkStateChangeNotifier
| Kind: | type alias |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Symbol: | NetworkStateChangeNotifier |
| Syntax: | using NetworkStateChangeNotifier = std::function<void(const NetworkStateType&)>; |
| Thread Safety: | not thread-safe |
| Description: | A function wrapper for the handler function that gets called by the Communication Management software in case the network state has changed. |
1.1.1.2 Enumeration: NetworkStateType
| Kind: | enumeration |
| Header file: | #include "ara/nm/network_handle.h" |
| Forwarding header file: | #include "ara/nm/nm_fwd.h" |
| Scope: | ara::nm::NetworkHandle |
| Symbol: | NetworkStateType |
| Underlying type: | std::uint32_t |
| Syntax: | enum class NetworkStateType : std::uint32_t {...}; |
| Values: | kNoCom | = 0 |
| Not all PNCs, VLANs and/or physical channels associated to this instance of the NetworkState are in kFullCom. |
| kFullCom | = 1 |
| All PNCs, VLANs and/or physical channels associated to this instance of the NetworkState are in kFullCom. |
| Description: | Enumeration of elementary supervision status. |
1.1.2 Public Member Functions
1.1.2.1 Special Member Functions
1.1.2.1.1 Copy Constructor
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | NetworkHandle (const NetworkHandle &)=delete; |
| Description: | The copy constructor for NetworkHandle shall not be used. |
1.1.2.1.2 Move Constructor
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | NetworkHandle (NetworkHandle &&stbc) noexcept; |
| Parameters (in): | stbc | The NetworkHandle object to be moved. |
| Exception Safety: | exception safe |
| Thread Safety: | implementation_defined |
| Description: | Move constructor for NetworkHandle. |
1.1.2.1.3 Copy Assignment Operator
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | ara::nm::NetworkHandle & operator= (const ara::nm::NetworkHandle &)=delete; |
| Description: | The copy assignment operator for NetworkHandle shall not be used. |
1.1.2.1.4 Move Assignment Operator
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | ara::nm::NetworkHandle & operator= (ara::nm::NetworkHandle &&stbc) & noexcept; |
| Parameters (in): | stbc | The NetworkHandle object to be moved. |
| Return value: | NetworkHandle & | The moved NetworkHandle object. |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Description: | Move assignment operator for NetworkHandle. |
1.1.2.1.5 Destructor
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | ~NetworkHandle () noexcept; |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Description: | NetworkHandle destructor |
1.1.2.2 Constructors
1.1.2.2.1 NetworkHandle
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | explicit NetworkHandle (const ara::core::InstanceSpecifier &specifier) noexcept; |
| Parameters (in): | specifier | ara::core::InstanceSpecifier to a PortPrototype of a NetworkManagementPortInterface |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Description: | NetworkHandle constructor |
1.1.2.3 Member Functions
1.1.2.3.1 GetNetworkRequestedState
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | ara::core::Result< ara::nm::NetworkHandle::NetworkStateType > GetNetworkRequestedState () const noexcept; |
| Return value: | ara::core::Result< NetworkStateType > | As per SWS_ANM_01007 |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Errors: | NmErrc::kServiceNotAvailable | rollback_semantics |
| The connection to the daemon is currently lost, so the application must implement an appropriate error strategy, such as taking over the previous NetworkState. |
| Description: | Method to obtain the current network requested state i.e. if the PNC / VLAN / Physical Network is currently requested or released |
1.1.2.3.2 GetNetworkState
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | ara::core::Result< ara::nm::NetworkHandle::NetworkStateType > GetNetworkState () const noexcept; |
| Return value: | ara::core::Result< NetworkStateType > | - If successful: an ara::core::Result containing a ara::core::Result::value_type containing a ara::nm::NetworkHandle::NetworkStateType indicating the network requested state of the corresponding PNC / VLAN / Physical Network - If unsuccessful: an ara::core::Result containing an ara::core::Result::error_type i.e. a corresponding ara::nm::NmErrc |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Errors: | NmErrc::kServiceNotAvailable | rollback_semantics |
| The connection to the daemon is currently lost, so the application must implement an appropriate error strategy, such as taking over the previous NetworkState. |
| Description: | Method to obtain the current network state i.e. PNC / VLAN / Physical Network is currently active or not |
1.1.2.3.3 RegisterNetworkRequestedStateChangeNotifier(NetworkStateChangeNotifier)
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | ara::core::Result< void > RegisterNetworkRequestedStateChangeNotifier (ara::nm::NetworkHandle::NetworkStateChangeNotifier notifier) noexcept; |
| Parameters (in): | notifier | The function to register |
| Return value: | ara::core::Result< void > | As per SWS_ANM_01010 |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Errors: | NmErrc::kInvalidHandler | rollback_semantics |
| Provided Callable handler does not exist or is null |
| Description: | Register a notifier function which is called if the current network requested state is changed (i.e. changed into FullCom or into NoCom). A maximum of one notifier can be registered. Every further registration overwrites the current registration. |
1.1.2.3.4 RegisterNetworkRequestedStateChangeNotifier(NetworkStateChangeNotifier, ExecutorT&&)
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | template <typename ExecutorT>
ara::core::Result< void > RegisterNetworkRequestedStateChangeNotifier (ara::nm::NetworkHandle::NetworkStateChangeNotifier notifier, ExecutorT &&executor) noexcept; |
| Template param: | ExecutorT | Context object type in which the asynchronous computation spawn shall be invoked. |
| Parameters (in): | notifier | As per notifier in SWS_ANM_01012 |
| executor | As per executor in SWS_ANM_01015 |
| Return value: | ara::core::Result< void > | As per SWS_ANM_01010 |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Errors: | NmErrc::kInvalidHandler | rollback_semantics |
| Provided Callable handler does not exist or is null |
| Description: | As per SWS_ANM_01012 but the method shall execute in a provided context |
1.1.2.3.5 RegisterNetworkStateChangeNotifier(NetworkStateChangeNotifier)
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | ara::core::Result< void > RegisterNetworkStateChangeNotifier (ara::nm::NetworkHandle::NetworkStateChangeNotifier notifier) noexcept; |
| Parameters (in): | notifier | The function to register. A maximum of one notifier can be registered. Every further registration overwrites the current registration. |
| Return value: | ara::core::Result< void > | - If successful: an ara::core::Result containing a ara::core::Result::value_type containing a void - If unsuccessful: an ara::core::Result containing an ara::core::Result::error_type i.e. a corresponding ara::nm::NmErrc |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Errors: | NmErrc::kInvalidHandler | rollback_semantics |
| Provided Callable handler does not exist or is null |
| Description: | Register a notifier function which is called if the current network state is changed (i.e. changed into FullCom or into NoCom). |
1.1.2.3.6 RegisterNetworkStateChangeNotifier(NetworkStateChangeNotifier, ExecutorT&&)
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | template <typename ExecutorT>
ara::core::Result< void > RegisterNetworkStateChangeNotifier (ara::nm::NetworkHandle::NetworkStateChangeNotifier notifier, ExecutorT &&executor) noexcept; |
| Template param: | ExecutorT | Context object type in which the asynchronous computation spawn shall be invoked. |
| Parameters (in): | notifier | As per SWS_ANM_01010 |
| executor | Executioner object in which any asynchronous computation spawn by RegisterNetworkStateChangeNotifier shall be invoked. |
| Return value: | ara::core::Result< void > | As per SWS_ANM_01010 |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Errors: | NmErrc::kInvalidHandler | rollback_semantics |
| Provided Callable handler does not exist or is null |
| Description: | As per SWS_ANM_01010 but the method shall execute in a provided context |
1.1.2.3.7 SetNetworkRequestedState
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | ara::core::Result< void > SetNetworkRequestedState (ara::nm::NetworkHandle::NetworkStateType networkState) noexcept; |
| Parameters (in): | networkState | The request state to be set |
| Return value: | ara::core::Result< void > | - If successful: an ara::core::Result containing a ara::core::Result::value_type containing a void - If unsuccessful: an ara::core::Result containing an ara::core::Result::error_type i.e. a corresponding ara::nm::NmErrc |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Errors: | NmErrc::kServiceNotAvailable | rollback_semantics |
| The connection to the daemon is currently lost, so the application must implement an appropriate error strategy, such as taking over the previous NetworkState. |
| Description: | A method that can be used to set a new network requested state. Setting a new network requested state will request or release the PNC / VLAN / Physical Network. |
1.1.2.3.8 UnregisterNetworkRequestedStateChangeNotifier
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | void UnregisterNetworkRequestedStateChangeNotifier () noexcept; |
| Return value: | None |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Description: | Unregister a notifier function which is called if a current network requested state is changed. |
1.1.2.3.9 UnregisterNetworkStateChangeNotifier
| Kind: | function |
| Header file: | #include "ara/nm/network_handle.h" |
| Scope: | ara::nm::NetworkHandle |
| Syntax: | void UnregisterNetworkStateChangeNotifier () noexcept; |
| Return value: | None |
| Exception Safety: | exception safe |
| Thread Safety: | not thread-safe |
| Description: | Unregister a notifier function which is called if a current network state is changed. |
2 Header: ara/nm/nm_error_domain.h
2.1 Non-Member Types
2.1.1 Enumeration: NmErrc
| Kind: | enumeration |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Forwarding header file: | #include "ara/nm/nm_fwd.h" |
| Scope: | namespace ara::nm |
| Symbol: | NmErrc |
| Underlying type: | ara::core::ErrorDomain::CodeType |
| Syntax: | enum class NmErrc : ara::core::ErrorDomain::CodeType {...}; |
| Values: | kServiceNotAvailable | = 1 |
| The connection to the daemon is currently lost, so the application must implement an appropriate error strategy, such as taking over the previous NetworkState. |
| kInvalidHandler | = 2 |
| Provided Callable handler does not exist or is null |
| Description: | Defines the error codes for the ara::nm::NmErrorDomain |
2.2 Non-Member Functions
2.2.1 Other
2.2.1.1 GetNmDomain
| Kind: | function |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | namespace ara::nm |
| Syntax: | constexpr const ara::core::ErrorDomain & GetNmDomain () noexcept; |
| Return value: | const ara::core::ErrorDomain & | Reference to the ara::nm::NmErrorDomain object |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Description: | Returns a reference to the ara::nm::NmErrorDomain object |
2.2.1.2 MakeErrorCode
| Kind: | function |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | namespace ara::nm |
| Syntax: | constexpr ara::core::ErrorCode MakeErrorCode (ara::nm::NmErrc code, ara::core::ErrorDomain::SupportDataType data) noexcept; |
| Parameters (in): | code | Error code number |
| data | Vendor defined data associated with the error |
| Return value: | ara::core::ErrorCode | An ara::core::ErrorCode object. |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Description: | Creates an instance of ara::core::ErrorCode |
2.3 Class: NmErrorDomain
| Kind: | class |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Forwarding header file: | #include "ara/nm/nm_fwd.h" |
| Scope: | namespace ara::nm |
| Symbol: | NmErrorDomain |
| Base class: | ara::core::ErrorDomain |
| Syntax: | class NmErrorDomain final : public ara::core::ErrorDomain {...}; |
| Description: | A class representing a network management error domain. |
2.3.1 Public Member Types
2.3.1.1 Type Alias: Errc
| Kind: | type alias |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | ara::nm::NmErrorDomain |
| Symbol: | Errc |
| Syntax: | using Errc = NmErrc; |
| Description: | Alias for the error code value enumeration |
2.3.1.2 Type Alias: Exception
| Kind: | type alias |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | ara::nm::NmErrorDomain |
| Symbol: | Exception |
| Syntax: | using Exception = NmException; |
| Description: | Alias for the exception base class |
2.3.2 Public Member Functions
2.3.2.1 Special Member Functions
2.3.2.1.1 Default Constructor
| Kind: | function |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | ara::nm::NmErrorDomain |
| Syntax: | NmErrorDomain () noexcept; |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Description: | Constructs a new ara::nm::NmErrorDomain object |
2.3.2.2 Member Functions
2.3.2.2.1 Message
| Kind: | function |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | ara::nm::NmErrorDomain |
| Syntax: | const char * Message (CodeType errorCode) const noexcept override; |
| Parameters (in): | errorCode | The error code number. |
| Return value: | const char * | The message associated with the error code |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Description: | Returns the message associated with the error code |
2.3.2.2.2 Name
| Kind: | function |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | ara::nm::NmErrorDomain |
| Syntax: | const char * Name () const noexcept override; |
| Return value: | const char * | As per ara::nm::NmErrorDomain in SWS_CORE_90023 |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Description: | Retrieve the name of the error domain |
2.3.2.2.3 ThrowAsException
| Kind: | function |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | ara::nm::NmErrorDomain |
| Syntax: | void ThrowAsException (const ara::core::ErrorCode &errorCode) const noexcept(false) override; |
| Parameters (in): | errorCode | The error to throw. |
| Return value: | None |
| Exception Safety: | not exception safe |
| Thread Safety: | thread-safe |
| Description: | Throws the exception associated with the error code. As per SWS_CORE_10304, this function does not participate in overload resolution when C++ exceptions are disabled in the compiler toolchain. |
2.4 Class: NmException
| Kind: | class |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Forwarding header file: | #include "ara/nm/nm_fwd.h" |
| Scope: | namespace ara::nm |
| Symbol: | NmException |
| Base class: | ara::core::Exception |
| Syntax: | class NmException : public ara::core::Exception {...}; |
| Description: | Defines a class for exceptions to be thrown by the API. |
2.4.1 Public Member Functions
2.4.1.1 Constructors
2.4.1.1.1 NmException
| Kind: | function |
| Header file: | #include "ara/nm/nm_error_domain.h" |
| Scope: | ara::nm::NmException |
| Syntax: | explicit NmException (ara::core::ErrorCode errorCode) noexcept; |
| Parameters (in): | errorCode | The error code |
| Exception Safety: | exception safe |
| Thread Safety: | thread-safe |
| Description: | Constructs a new ara::nm::NmException containing an ara::core::ErrorCode |
See also
- Network Management daemon (NM) and the runtime model: PARA Overview
- Network handle configuration: Network Management configuration