:orphan:

.. index:: pair: group; API: Configurator
.. _doxid-group__confapi__base:

API: Configurator
=================

.. toctree::
	:hidden:

	group_confapi_base_backup.rst
	group_confapi_base_access.rst
	group_confapi_base_traverse.rst
	group_confapi_base_sync.rst
	group_confapi_base_reboot.rst

Overview
~~~~~~~~

Copyright (C) 2004-2022 OKTET Labs Ltd. :ref:`More...<details-group__confapi__base>`

|	:ref:`Configuration backup manipulation<doxid-group__confapi__base__backup>`
|	:ref:`Configuration tree access operations<doxid-group__confapi__base__access>`
|	:ref:`Configuration tree traversal<doxid-group__confapi__base__traverse>`
|	:ref:`Synchronization configuration tree with Test Agent<doxid-group__confapi__base__sync>`
|	:ref:`Test Agent reboot<doxid-group__confapi__base__reboot>`



.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// typedefs

	typedef uint64_t :ref:`cfg_handle<doxid-group__confapi__base_1gabc299401ba5bcc0edb6eab462c0a6ba4>`;

	// global functions

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`cfg_wait_changes<doxid-group__confapi__base_1ga7eeb5c4908147dbdbca16a93ac83027b>`(void);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`cfg_touch_instance<doxid-group__confapi__base_1ga2c8463bb2cfb1ddc48f51921be01540f>`(const char* oid_tmpl, ...);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`cfg_tree_print<doxid-group__confapi__base_1gab00f3b373b113c5d4492d41bc23cbd56>`(const char* filename, const unsigned int log_lvl, const char* id_fmt, ...);
	void :ref:`cfg_api_cleanup<doxid-group__confapi__base_1gab017f695188898b50178e922a205b038>`(void);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`cfg_copy_subtree_fmt<doxid-group__confapi__base_1gaafdf13b3be97f735996b6d0d5c68f987>`(const char* dst_oid, const char* src_oid_fmt, ...);

	// macros

	#define :ref:`CFG_HANDLE_INVALID<doxid-group__confapi__base_1ga5f512b1844ca747d5077ef5ec417253b>`
	#define :ref:`CFG_IVP<doxid-group__confapi__base_1gafcab980920fc1312b5ba25fb29d43a4b>`(x)
	#define :ref:`CFG_VAL<doxid-group__confapi__base_1ga571ed2d1ebadd0b83abc2f8290030c90>`(_t, _v)
	#define :ref:`CFG_WAIT_CHANGES<doxid-group__confapi__base_1ga9e869702cf6508349045e0e6a1c8f180>`
	#define :target:`cfg_get_instance_addr_fmt<doxid-group__confapi__base_1ga62b05539c7d98126712aa27968aa68d5>`
	#define :target:`cfg_get_instance_addr_sync_fmt<doxid-group__confapi__base_1ga9cc360c4959d1cbe857eafec7ffc9fa0>`
	#define :target:`cfg_get_instance_double_fmt<doxid-group__confapi__base_1ga29a73c1c5869412263272190ff2279f1>`
	#define :target:`cfg_get_instance_double_sync_fmt<doxid-group__confapi__base_1ga4d92ec265cf079f0423ec30f255662f7>`
	#define :ref:`cfg_get_instance_int_fmt<doxid-group__confapi__base_1ga0551523957f0cb2508d0c74c9d2ce52b>`
	#define :target:`cfg_get_instance_int_sync_fmt<doxid-group__confapi__base_1ga95ec223e815009f256431f9119053cdb>`
	#define :target:`cfg_get_instance_string_fmt<doxid-group__confapi__base_1gad97bf6b6aee89ef3af9f32b540399344>`
	#define :target:`cfg_get_instance_string_sync_fmt<doxid-group__confapi__base_1ga78541a6a051758c3dca5a1fa76896887>`
	#define :target:`cfg_get_instance_uint64_fmt<doxid-group__confapi__base_1ga214910bd1045e7917b7384744438cb81>`
	#define :target:`cfg_get_instance_uint64_sync_fmt<doxid-group__confapi__base_1ga27b8f5cb761ae6de003bf18625e57692>`

.. _details-group__confapi__base:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Typedefs
--------

.. index:: pair: typedef; cfg_handle
.. _doxid-group__confapi__base_1gabc299401ba5bcc0edb6eab462c0a6ba4:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef uint64_t cfg_handle

Object and object instances handle.

Object handle is an index in array of all objects.

Object instance handle consists of two parts: two most significant bytes contain unique number of the instance and two other bytes contain index in the array of all existing object instances.

Global Functions
----------------

.. index:: pair: function; cfg_wait_changes
.. _doxid-group__confapi__base_1ga7eeb5c4908147dbdbca16a93ac83027b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` cfg_wait_changes(void)

Wait for Configuration changes propagation.

Required delays are configured using /conf_delay subtree. Time to sleep is calculated as the maximum of required delays for configuration changes done after the previous wait (regardless how long time ago the changes are done).



.. rubric:: Returns:

Status code (see ``te_errno.h``)

.. index:: pair: function; cfg_touch_instance
.. _doxid-group__confapi__base_1ga2c8463bb2cfb1ddc48f51921be01540f:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` cfg_touch_instance(const char* oid_tmpl, ...)

Notify the Configurator that instances matching OID template are touched by non-CS means (necessary for subsequent correct :ref:`cfg_wait_changes() <doxid-group__confapi__base_1ga7eeb5c4908147dbdbca16a93ac83027b>` processing).



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- oid_tmpl

		- instance identifier format string (may contain '\*' symbols)



.. rubric:: Returns:

Status code (see ``te_errno.h``)

.. index:: pair: function; cfg_tree_print
.. _doxid-group__confapi__base_1gab00f3b373b113c5d4492d41bc23cbd56:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` cfg_tree_print(const char* filename, const unsigned int log_lvl, const char* id_fmt, ...)

Starting from a given prefix, print a tree of objects or instances into a file and(or) log.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- filename

		- output filename (NULL to skip)

	*
		- log_lvl

		- TE log level (0 to skip)

	*
		- id_fmt

		- a format string for the id of the root from which we print.



.. rubric:: Returns:

Status code.

.. index:: pair: function; cfg_api_cleanup
.. _doxid-group__confapi__base_1gab017f695188898b50178e922a205b038:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void cfg_api_cleanup(void)

Clean up resources allocated by Configurator API.

Usually user should not worry about calling of the function, since it is called automatically using atexit() mechanism.

.. index:: pair: function; cfg_copy_subtree_fmt
.. _doxid-group__confapi__base_1gaafdf13b3be97f735996b6d0d5c68f987:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` cfg_copy_subtree_fmt(const char* dst_oid, const char* src_oid_fmt, ...)

Copy a subtree pointed to by its OID format string to a destination pointed to by OID of the tree to be created.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- dst_oid

		- Destination tree OID

	*
		- src_oid_fmt

		- Format string of the source tree OID



.. rubric:: Returns:

Status code.

Macros
------

.. index:: pair: define; CFG_HANDLE_INVALID
.. _doxid-group__confapi__base_1ga5f512b1844ca747d5077ef5ec417253b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define CFG_HANDLE_INVALID

Invalid Configurator object handle

.. index:: pair: define; CFG_IVP
.. _doxid-group__confapi__base_1gafcab980920fc1312b5ba25fb29d43a4b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define CFG_IVP(x)

Cast to Configurator Instance Value Pointer

.. index:: pair: define; CFG_VAL
.. _doxid-group__confapi__base_1ga571ed2d1ebadd0b83abc2f8290030c90:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define CFG_VAL(_t, _v)

Macro definition to be used in cfg\_{add,set}_instance_fmp() calls. Here it is assumed that 'intptr_t' type has the same size as 'void \*'.

.. index:: pair: define; CFG_WAIT_CHANGES
.. _doxid-group__confapi__base_1ga9e869702cf6508349045e0e6a1c8f180:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define CFG_WAIT_CHANGES

Macro to call :ref:`cfg_wait_changes() <doxid-group__confapi__base_1ga7eeb5c4908147dbdbca16a93ac83027b>` from the test without check of return value.

.. index:: pair: define; cfg_get_instance_int_fmt
.. _doxid-group__confapi__base_1ga0551523957f0cb2508d0c74c9d2ce52b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define cfg_get_instance_int_fmt

The macro definitions are wrappers for backward compatibility.