:orphan: .. index:: pair: group; Network setup library .. _doxid-group__tapi__net: Network setup library ===================== .. toctree:: :hidden: group_tapi_net_env.rst group_tapi_net_yaml.rst enum_tapi_net_iface_type.rst enum_tapi_net_nat_rule_mode.rst enum_tapi_net_nat_rule_type.rst struct_tapi_net_ctx.rst struct_tapi_net_endpoint.rst struct_tapi_net_iface.rst struct_tapi_net_link.rst struct_tapi_net_nat_rule.rst struct_tapi_net_qinq.rst struct_tapi_net_ta.rst struct_tapi_net_vlan.rst Overview ~~~~~~~~ Definition of test API to define and set up test network. :ref:`More...` | :ref:`Auxiliary library for interacting with test environment.` | :ref:`Auxiliary library to define network in YAML format` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef enum :ref:`tapi_net_iface_type` :ref:`tapi_net_iface_type`; typedef struct :ref:`tapi_net_vlan` :ref:`tapi_net_vlan`; typedef struct :ref:`tapi_net_qinq` :ref:`tapi_net_qinq`; typedef struct :ref:`tapi_net_iface` :ref:`tapi_net_iface`; typedef struct :ref:`tapi_net_endpoint` :ref:`tapi_net_endpoint`; typedef enum :ref:`tapi_net_nat_rule_type` :ref:`tapi_net_nat_rule_type`; typedef enum :ref:`tapi_net_nat_rule_mode` :ref:`tapi_net_nat_rule_mode`; typedef struct :ref:`tapi_net_nat_rule` :ref:`tapi_net_nat_rule`; typedef struct :ref:`tapi_net_ta` :ref:`tapi_net_ta`; typedef struct :ref:`tapi_net_link` :ref:`tapi_net_link`; typedef struct :ref:`tapi_net_ctx` :ref:`tapi_net_ctx`; // enums enum :ref:`tapi_net_iface_type`; enum :ref:`tapi_net_nat_rule_mode`; enum :ref:`tapi_net_nat_rule_type`; // structs struct :ref:`tapi_net_ctx`; struct :ref:`tapi_net_endpoint`; struct :ref:`tapi_net_iface`; struct :ref:`tapi_net_link`; struct :ref:`tapi_net_nat_rule`; struct :ref:`tapi_net_qinq`; struct :ref:`tapi_net_ta`; struct :ref:`tapi_net_vlan`; // global functions typedef :ref:`SLIST_HEAD`(tapi_net_iface_head, :ref:`tapi_net_iface`); void :ref:`tapi_net_ctx_init`(:ref:`tapi_net_ctx`* net_ctx); void :ref:`tapi_net_ctx_release`(:ref:`tapi_net_ctx`* net_ctx); void :ref:`tapi_net_ta_init`(const char* ta_name, :ref:`tapi_net_ta`* cfg_net_ta); void :ref:`tapi_net_ta_set_ifaces`(:ref:`tapi_net_ta`* net_cfg_ta, const char** if_name_list); void :ref:`tapi_net_ta_destroy`(:ref:`tapi_net_ta`* cfg_net_ta); :ref:`te_errno` :ref:`tapi_net_iface_set_vlan_conf`(:ref:`tapi_net_iface`* iface, const :ref:`tapi_net_vlan`* vlan); :ref:`te_errno` :ref:`tapi_net_iface_set_qinq_conf`(:ref:`tapi_net_iface`* iface, const :ref:`tapi_net_qinq`* qinq); :ref:`te_errno` :ref:`tapi_net_logical_iface_add`(:ref:`tapi_net_iface_type` iface_type, const char* if_name, :ref:`tapi_net_iface`* base_iface, :ref:`tapi_net_iface`** iface); :ref:`tapi_net_ta`* :ref:`tapi_net_find_agent_by_name`(:ref:`tapi_net_ctx`* net_ctx, const char* ta_name); :ref:`tapi_net_iface`* :ref:`tapi_net_find_iface_by_name`(:ref:`tapi_net_ta`* net_cfg_ta, const char* if_name); :ref:`tapi_net_iface_type` :ref:`tapi_net_iface_type_by_name`(const char* iface_type_str); :ref:`te_errno` :ref:`tapi_net_setup_ifaces`(const :ref:`tapi_net_ctx`* net_ctx); const char* :ref:`tapi_net_get_top_iface_name`(const tapi_net_iface_head* iface_head); :ref:`te_errno` :ref:`tapi_net_get_top_iface_addr`(const tapi_net_iface_head* iface_head, const struct sockaddr** addr); :ref:`te_errno` :ref:`tapi_net_setup`(:ref:`tapi_net_ctx`* net_ctx); void :ref:`tapi_net_nat_rule_init`(:ref:`tapi_net_nat_rule`* rule); :ref:`te_errno` :ref:`tapi_net_nat_rule_validate`(const :ref:`tapi_net_nat_rule`* rule); :ref:`te_errno` :ref:`tapi_net_nat_rule_check_dup`(const :ref:`tapi_net_ta`* agent, const :ref:`tapi_net_nat_rule`* rule); :ref:`te_errno` :ref:`tapi_net_addr_fill`(:ref:`tapi_net_ctx`* net_ctx); const struct sockaddr* :ref:`tapi_net_ep_resolve_ip_addr`(:ref:`tapi_net_ctx`* ctx, const :ref:`tapi_net_endpoint`* ep); // macros #define :ref:`TAPI_NET_EP_NUM` #define :ref:`TAPI_NET_NAME_LEN` .. _details-group__tapi__net: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Definition of test API to define and set up test network. Typedefs -------- .. index:: pair: typedef; tapi_net_iface_type .. _doxid-group__tapi__net_1gab2b48bded82be7c0d1b0b0ea21d97ef2: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`tapi_net_iface_type` tapi_net_iface_type Supported interface types. .. index:: pair: typedef; tapi_net_vlan .. _doxid-group__tapi__net_1ga46d6d6709fb4eda1198e31e2e8224ccc: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_net_vlan` tapi_net_vlan VLAN-specific configuration. .. index:: pair: typedef; tapi_net_qinq .. _doxid-group__tapi__net_1gab750557e565aa0f191ec3eeab967a74d: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_net_qinq` tapi_net_qinq QinQ-specific configuration. .. index:: pair: typedef; tapi_net_iface .. _doxid-group__tapi__net_1ga2fce35fe311c90ff753b8fb5b9c8e6eb: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_net_iface` tapi_net_iface Logical interface definition. Interfaces are organized as a stack, starting from a base and building up through VLAN, QinQ, GRE, or other layers. The stack is represented as a singly linked list, where each interface points to the next one above it. The structure defines the interface type and any type-specific parameters, such as a VLAN ID. .. index:: pair: typedef; tapi_net_endpoint .. _doxid-group__tapi__net_1gab1661b9f98e0f548369212d11a9c7f44: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_net_endpoint` tapi_net_endpoint Network endpoint of single connection. .. index:: pair: typedef; tapi_net_nat_rule_type .. _doxid-group__tapi__net_1gabd6ac94b4dd2560c724f582d865c85e6: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`tapi_net_nat_rule_type` tapi_net_nat_rule_type Type of NAT rule. .. index:: pair: typedef; tapi_net_nat_rule_mode .. _doxid-group__tapi__net_1ga2d4b2cecb2cf6eef25b4d5de244b36b2: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`tapi_net_nat_rule_mode` tapi_net_nat_rule_mode Mode of NAT rule. .. index:: pair: typedef; tapi_net_nat_rule .. _doxid-group__tapi__net_1gadc6efbaa5f3b988332ea36b9ef11aa6a: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_net_nat_rule` tapi_net_nat_rule Single NAT rule. .. index:: pair: typedef; tapi_net_ta .. _doxid-group__tapi__net_1ga6d74aaca63f7c42d8330c975774b49b3: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_net_ta` tapi_net_ta Test agent with a list of logical interfaces. .. index:: pair: typedef; tapi_net_link .. _doxid-group__tapi__net_1ga9fbf024253277cae928e2e1d4017f420: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_net_link` tapi_net_link Logical network between two endpoints. For the test purposes, networks are modeled as point-to-point connections. .. index:: pair: typedef; tapi_net_ctx .. _doxid-group__tapi__net_1gacd5352a9cd77a039132eaa52f2f165a9: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_net_ctx` tapi_net_ctx Network configuration context that includes all interface definitions and network topologies. Global Functions ---------------- .. index:: pair: function; SLIST_HEAD .. _doxid-group__tapi__net_1ga2d4840917c56d3a2e001e3eff560ce6b: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef SLIST_HEAD(tapi_net_iface_head, :ref:`tapi_net_iface`) Singly-linked list of logical interfaces. .. index:: pair: function; tapi_net_ctx_init .. _doxid-group__tapi__net_1ga776f41e67d1e18d4138750ffcabaf0d9: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_net_ctx_init(:ref:`tapi_net_ctx`* net_ctx) Initialize network configuration context. This sets up vectors and their destructors. .. index:: pair: function; tapi_net_ctx_release .. _doxid-group__tapi__net_1gac3109cbcf2f03d2ed23218d3f30bbe87: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_net_ctx_release(:ref:`tapi_net_ctx`* net_ctx) Release Network Configuration Context. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - net_ctx - Network Configuration Context. .. index:: pair: function; tapi_net_ta_init .. _doxid-group__tapi__net_1gaa19dfc7ac0ea1c60cf509f5257982576: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_net_ta_init(const char* ta_name, :ref:`tapi_net_ta`* cfg_net_ta) Initialize Test Agent network configuration. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta_name - TA name. * - cfg_net_ta - Resulting TA network configuration. .. index:: pair: function; tapi_net_ta_set_ifaces .. _doxid-group__tapi__net_1gac6dc203af0581213c43936cdc8f0e2d9: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_net_ta_set_ifaces(:ref:`tapi_net_ta`* net_cfg_ta, const char** if_name_list) Set interfaces in network configuration for specific Test Agent. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - cfg_net_ta - TA network configuration. * - if_name_list - NULL-terminated list of physical interface names. .. rubric:: Returns: Status of the initializion. .. index:: pair: function; tapi_net_ta_destroy .. _doxid-group__tapi__net_1gabd6384bb53f1f441b31484f0633f4874: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_net_ta_destroy(:ref:`tapi_net_ta`* cfg_net_ta) Destroy Test Agent network configuration. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - net_cfg_ta - Pointer to TA network configuration. .. index:: pair: function; tapi_net_iface_set_vlan_conf .. _doxid-group__tapi__net_1gae5a6cd2ce997a5387f9eb30218551702: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_iface_set_vlan_conf(:ref:`tapi_net_iface`* iface, const :ref:`tapi_net_vlan`* vlan) Set interface VLAN-specific information. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - iface - Pointer to VLAN interface. * - vlan - VLAN information. * - TE_EINVAL - Invalid ``vlan_id`` was passed. * - 0 - Success. .. rubric:: Returns: Status of the setting. .. index:: pair: function; tapi_net_iface_set_qinq_conf .. _doxid-group__tapi__net_1gab045383152d222dbb719c19dfb90043e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_iface_set_qinq_conf(:ref:`tapi_net_iface`* iface, const :ref:`tapi_net_qinq`* qinq) Set interface QinQ-specific information. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - iface - Pointer to QinQ interface. * - qinq - QinQ information. * - TE_EINVAL - Invalid ``inner_id`` or ``outer_id`` was passed. * - 0 - Success. .. rubric:: Returns: Status of the setting. .. index:: pair: function; tapi_net_logical_iface_add .. _doxid-group__tapi__net_1ga1c4113f3186afdb2254f9678a49f8501: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_logical_iface_add(:ref:`tapi_net_iface_type` iface_type, const char* if_name, :ref:`tapi_net_iface`* base_iface, :ref:`tapi_net_iface`** iface) Add new logical interface. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - iface_type - Iterface type. * - if_name - Interface name. * - base_iface - Pointer to the interface to base on. * - iface - Pointer to the added interfaces. * - TE_EINVAL - Unsupported type of logical interface. * - 0 - Success. .. rubric:: Returns: Status of the adding. .. index:: pair: function; tapi_net_find_agent_by_name .. _doxid-group__tapi__net_1gabe08c934edda9cf7d485d11f69c1fabd: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`tapi_net_ta`* tapi_net_find_agent_by_name(:ref:`tapi_net_ctx`* net_ctx, const char* ta_name) Find TA network configuration in network context. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - net_ctx - Network configuration context. * - ta_name - TA name to find. .. rubric:: Returns: Pointer to TA network configuration, or ``NULL`` in case of error. .. index:: pair: function; tapi_net_find_iface_by_name .. _doxid-group__tapi__net_1ga7207a6dba60b447791472f5ca8b09279: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`tapi_net_iface`* tapi_net_find_iface_by_name(:ref:`tapi_net_ta`* net_cfg_ta, const char* if_name) Find interface by its name in TA network configuration. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - net_cfg_ta - Pointer TA network configuration. * - if_name - Interface name to find. .. rubric:: Returns: Pointer to interface, or ``NULL`` in case of error. .. index:: pair: function; tapi_net_iface_type_by_name .. _doxid-group__tapi__net_1gac987fd24efa376ea8073f0aba8996904: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`tapi_net_iface_type` tapi_net_iface_type_by_name(const char* iface_type_str) Get interface type by its string representation. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - if_name - String with Network type .. rubric:: Returns: Interface type. .. index:: pair: function; tapi_net_setup_ifaces .. _doxid-group__tapi__net_1ga2e37156c1a09112218e7786fc5d6add0: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_setup_ifaces(const :ref:`tapi_net_ctx`* net_ctx) Setup interfaces specified in the network context. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - net_ctx - Network context. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_net_get_top_iface_name .. _doxid-group__tapi__net_1ga817540fe588f0987b3d5ad817c5dc7da: .. ref-code-block:: cpp :class: doxyrest-title-code-block const char* tapi_net_get_top_iface_name(const tapi_net_iface_head* iface_head) Get interface name of the top-most interface in the stack. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - iface_head - Head of the interface stack. .. rubric:: Returns: Interface name or ``NULL`` on error. .. index:: pair: function; tapi_net_get_top_iface_addr .. _doxid-group__tapi__net_1gad8de38825a2a101781b69deb408d07c9: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_get_top_iface_addr(const tapi_net_iface_head* iface_head, const struct sockaddr** addr) Get address of the top-most interface in the stack. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - iface_head - Head of the interface stack. * - addr - Address of the interface. * - TE_ENOENT - No address assigned to requested interface. * - 0 - Success. .. rubric:: Returns: Status of the adding. .. index:: pair: function; tapi_net_setup .. _doxid-group__tapi__net_1ga324b96c5ce19fca79d6828416b35482d: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_setup(:ref:`tapi_net_ctx`* net_ctx) Setup network based on network context. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - net_ctx - Network contex to use for setup. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_net_nat_rule_init .. _doxid-group__tapi__net_1ga3b2f38ab0782e82ec8de1fb967240e20: .. ref-code-block:: cpp :class: doxyrest-title-code-block void tapi_net_nat_rule_init(:ref:`tapi_net_nat_rule`* rule) Initialize NAT rule. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - rule - NAT rule to init. .. index:: pair: function; tapi_net_nat_rule_validate .. _doxid-group__tapi__net_1gafb7532e4bb96afc2b52bd01d1785d69c: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_nat_rule_validate(const :ref:`tapi_net_nat_rule`* rule) Validate NAT rule. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - rule - NAT rule to validate. * - TE_EINVAL - Validation failed. * - 0 - Success. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_net_nat_rule_check_dup .. _doxid-group__tapi__net_1ga98e3e3a1758e2c57a43f7644ac63133a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_nat_rule_check_dup(const :ref:`tapi_net_ta`* agent, const :ref:`tapi_net_nat_rule`* rule) Check NAT rule duplicates. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - agent - Test agent which owns the NAT rule list. * - rule - Rule to validate. * - TE_EEXIST - Conflicting rule already exists. * - 0 - Success. .. rubric:: Returns: Status code. .. index:: pair: function; tapi_net_addr_fill .. _doxid-group__tapi__net_1ga5b8063c9e7d57141cd8458bec0db740e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_net_addr_fill(:ref:`tapi_net_ctx`* net_ctx) Fill in IP addresses for logical interfaces based on netowrks in Configurator. This function set appropriate IP addresses for the logical interface structures mentioned in Configurator to use them after in tests. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - net_ctx - Network contex .. rubric:: Returns: Status code. .. index:: pair: function; tapi_net_ep_resolve_ip_addr .. _doxid-group__tapi__net_1ga325fb36e0c6c5b0e8256b31444ecbc7c: .. ref-code-block:: cpp :class: doxyrest-title-code-block const struct sockaddr* tapi_net_ep_resolve_ip_addr(:ref:`tapi_net_ctx`* ctx, const :ref:`tapi_net_endpoint`* ep) Resolve IP address of specific network endpoint. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - net_ctx - Network contex to use for resolving. * - ep - Network endpoint. .. rubric:: Returns: Resolved IP address. Macros ------ .. index:: pair: define; TAPI_NET_EP_NUM .. _doxid-group__tapi__net_1gad6e06ea046da9d45f56587930194e1e5: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TAPI_NET_EP_NUM The limit of endpoint number which can be used in test networks. .. index:: pair: define; TAPI_NET_NAME_LEN .. _doxid-group__tapi__net_1ga9020f3197838cf65a51b6472bdd48124: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TAPI_NET_NAME_LEN Length of network name.