:orphan: .. index:: pair: group; Configuration tree traversal .. _doxid-group__confapi__base__traverse: Configuration tree traversal ============================ .. toctree:: :hidden: struct_cfg_obj_descr.rst Overview ~~~~~~~~ .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef struct :ref:`cfg_obj_descr` :ref:`cfg_obj_descr`; typedef int (*:ref:`cfg_inst_handler`)( cfg_handle handle, void *user_data ); // structs struct :ref:`cfg_obj_descr`; // global variables :ref:`te_errno` typedef :ref:`te_errno`(* :ref:`cfg_handle_cb_func`)(cfg_handle handle, void *opaque); const :ref:`te_enum_map` :ref:`cfg_cva_mapping`[]; // global functions :ref:`te_errno` :ref:`cfg_register_object_str`(const char* oid, :ref:`cfg_obj_descr`* descr, :ref:`cfg_handle`* handle); :ref:`te_errno` :ref:`cfg_register_object`(const :ref:`cfg_oid`* oid, :ref:`cfg_obj_descr`* descr, :ref:`cfg_handle`* handle); :ref:`te_errno` :ref:`cfg_register_object_fmt`(:ref:`cfg_obj_descr`* descr, :ref:`cfg_handle`* handle, const char* oid_fmt, ...); :ref:`te_errno` :ref:`te_errno` :ref:`cfg_unregister_object_str`(const char* id_fmt, ...); :ref:`te_errno` :ref:`cfg_get_object_descr`(:ref:`cfg_handle` handle, :ref:`cfg_obj_descr`* descr); :ref:`te_errno` :ref:`cfg_get_oid_str`(:ref:`cfg_handle` handle, char** oid); :ref:`te_errno` :ref:`cfg_get_oid`(:ref:`cfg_handle` handle, :ref:`cfg_oid`** oid); :ref:`te_errno` :ref:`cfg_get_subid`(:ref:`cfg_handle` handle, char** subid); :ref:`te_errno` :ref:`cfg_get_inst_name`(:ref:`cfg_handle` handle, char** name); :ref:`te_errno` :ref:`cfg_get_inst_name_type`(:ref:`cfg_handle` handle, :ref:`cfg_val_type` type, :ref:`cfg_inst_val`* val); :ref:`te_errno` :ref:`cfg_get_ith_inst_name`(const char* str_oid, unsigned int i, char** name); :ref:`te_errno` :ref:`cfg_find_str`(const char* oid, :ref:`cfg_handle`* p_handle); static :ref:`te_errno` :ref:`cfg_find_vfmt`(:ref:`cfg_handle`* p_handle, const char* oid_fmt, va_list ap); :ref:`te_errno` :ref:`cfg_find_fmt`(:ref:`cfg_handle`* p_handle, const char* oid_fmt, ...); :ref:`te_errno` :ref:`te_errno` :ref:`cfg_find`(const :ref:`cfg_oid`* oid, :ref:`cfg_handle`* handle); :ref:`te_errno` :ref:`cfg_find_object_by_instance`(:ref:`cfg_handle` instance, :ref:`cfg_handle`* object); :ref:`te_errno` :ref:`cfg_find_pattern`(const char* pattern, unsigned int* p_num, :ref:`cfg_handle`** p_set); :ref:`te_errno` :ref:`cfg_find_pattern_fmt`(unsigned int* p_num, :ref:`cfg_handle`** p_set, const char* ptrn_fmt, ...); :ref:`te_errno` :ref:`cfg_find_pattern_iter_fmt`(:ref:`cfg_handle_cb_func` cb_func, void* opaque, const char* ptrn_fmt, ...); :ref:`te_errno` :ref:`te_errno` :ref:`cfg_get_son`(:ref:`cfg_handle` handle, :ref:`cfg_handle`* son); :ref:`te_errno` :ref:`cfg_get_brother`(:ref:`cfg_handle` handle, :ref:`cfg_handle`* brother); :ref:`te_errno` :ref:`cfg_get_father`(:ref:`cfg_handle` handle, :ref:`cfg_handle`* father); :ref:`te_errno` :ref:`cfg_enumerate`(:ref:`cfg_handle` handle, :ref:`cfg_inst_handler` callback, void* user_data); // macros #define :ref:`CFG_IS_INST`(_handle) .. _details-group__confapi__base__traverse: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Typedefs -------- .. index:: pair: typedef; cfg_obj_descr .. _doxid-group__confapi__base__traverse_1ga755f0ab6858c18a31dbd6b406ef11f8f: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`cfg_obj_descr` cfg_obj_descr Object properties description .. index:: pair: typedef; cfg_inst_handler .. _doxid-group__confapi__base__traverse_1ga90457f24b355d7861d0dafe63643c62f: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef int (*cfg_inst_handler)( cfg_handle handle, void *user_data ) Function handler called during instances enumeration Global Variables ---------------- .. index:: pair: variable; cfg_handle_cb_func .. _doxid-group__confapi__base__traverse_1ga4ab85b9d9704d20b6f5086585cdbc860: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` typedef :ref:`te_errno`(* cfg_handle_cb_func)(cfg_handle handle, void *opaque) Type of callback function which can passed to :ref:`cfg_find_pattern_iter_fmt() `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - Configurator object or instance handle * - opaque - Opaque data .. rubric:: Returns: Status code .. index:: pair: variable; cfg_cva_mapping .. _doxid-group__confapi__base__traverse_1ga011e6714c87ff031315f1fc0cfe96ee6: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`te_enum_map` cfg_cva_mapping[] Array to convert cfg value access rights to string and vice versa Global Functions ---------------- .. index:: pair: function; cfg_register_object_str .. _doxid-group__confapi__base__traverse_1ga262ddd91a05f74c1b5ee707df11fdaa0: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_register_object_str(const char* oid, :ref:`cfg_obj_descr`* descr, :ref:`cfg_handle`* handle) Register new object using string object identifiers. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - oid - object identifier in string representation * - descr - object properties description * - handle - location for handle of the new object .. rubric:: Returns: Status code (see ``te_errno.h``) .. index:: pair: function; cfg_register_object .. _doxid-group__confapi__base__traverse_1gac91034791772383f9c58aad4b663c4dc: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_register_object(const :ref:`cfg_oid`* oid, :ref:`cfg_obj_descr`* descr, :ref:`cfg_handle`* handle) Register new object using array object identifiers. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - oid - object identifier * - descr - object properties description * - handle - location for handle of the new object .. rubric:: Returns: Status code (see ``te_errno.h``) .. index:: pair: function; cfg_register_object_fmt .. _doxid-group__confapi__base__traverse_1ga125851a8ef8e2c3d99e900979b2b9b51: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_register_object_fmt(:ref:`cfg_obj_descr`* descr, :ref:`cfg_handle`* handle, const char* oid_fmt, ...) The same function as cfg_register_object_str, but OID may be format string. .. index:: pair: function; cfg_unregister_object_str .. _doxid-group__confapi__base__traverse_1ga73c7635d945afef2716df91de2b229f0: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` :ref:`te_errno` cfg_unregister_object_str(const char* id_fmt, ...) Request Configurator to remove an object with a given id from the data base of objects. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - id_fmt - a format string for the object id. .. rubric:: Returns: Status code. .. index:: pair: function; cfg_get_object_descr .. _doxid-group__confapi__base__traverse_1ga50cff1e37c55ee3a064c3aaddea7da44: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_object_descr(:ref:`cfg_handle` handle, :ref:`cfg_obj_descr`* descr) Obtain parameters configured for the object. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - object handle * - descr - OUT: location for the object properties description .. rubric:: Returns: Status code (see ``te_errno.h``) .. index:: pair: function; cfg_get_oid_str .. _doxid-group__confapi__base__traverse_1ga8e22afcf0e5cf3b4d11009c05698dfa5: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_oid_str(:ref:`cfg_handle` handle, char** oid) Obtain identifier of object or object instance by its handle. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - handle of object or object instance * - oid - OUT: location for the oid pointer (memory for the string is allocated by the routine using malloc() .. rubric:: Returns: 0 or TE_EINVAL if invalid handle is provided .. index:: pair: function; cfg_get_oid .. _doxid-group__confapi__base__traverse_1ga92003af6bd4750525e68562f81d09246: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_oid(:ref:`cfg_handle` handle, :ref:`cfg_oid`** oid) Obtain identifier of object or object instance by its handle. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - handle of object or object instance * - oid - OUT: location for the oid pointer (memory for the array is allocated by the routine using malloc() .. rubric:: Returns: 0 or TE_EINVAL if invalid handle is provided .. index:: pair: function; cfg_get_subid .. _doxid-group__confapi__base__traverse_1ga28f46d8316da062b2076ada012bbb266: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_subid(:ref:`cfg_handle` handle, char** subid) Obtain sub-identifier of object by its handle. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - handle of object * - subid - OUT: location for the sub-identifier (should be at least CFG_SUBID_MAX length) .. rubric:: Returns: 0 or TE_EINVAL if invalid handle is provided .. index:: pair: function; cfg_get_inst_name .. _doxid-group__confapi__base__traverse_1ga141bc1ef1df540b95df7f8ee41b94a98: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_inst_name(:ref:`cfg_handle` handle, char** name) Obtain name of object instance by its handle. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - handle of object instance * - name - OUT: location for the name .. rubric:: Returns: 0 or TE_EINVAL if invalid handle is provided .. index:: pair: function; cfg_get_inst_name_type .. _doxid-group__confapi__base__traverse_1gaebf6ee350fc4a8c138aea4c1d1a1b04d: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_inst_name_type(:ref:`cfg_handle` handle, :ref:`cfg_val_type` type, :ref:`cfg_inst_val`* val) Obtain integer name of object instance by its handle. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - Handle of object instance * - type - Type instance name * - val - Value of the corresponding type .. ref-code-block:: cpp type == CVT_BOOL -> (bool *) type == CVT_INT8 -> (int8_t *) type == CVT_UINT8 -> (uint8_t *) type == CVT_INT16 -> (int16_t *) type == CVT_UINT16 -> (uint16_t *) type == CVT_INT32 -> (int32_t *) type == CVT_UINT32 -> (uint32_t *) type == CVT_INT64 -> (int64_t *) type == CVT_UINT64 -> (uint64_t *) type == CVT_ADDRESS -> (struct sockaddr **) .. rubric:: Returns: 0 or TE_EINVAL if invalid handle is provided .. index:: pair: function; cfg_get_ith_inst_name .. _doxid-group__confapi__base__traverse_1gab701d37eef9763a5405f06eaed80d044: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_ith_inst_name(const char* str_oid, unsigned int i, char** name) Obtain name of object instance by its handle. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - str_oid - object instance identifier in string * - i - index of the instance subid * - name - OUT: location for the name .. rubric:: Returns: 0 or TE_EINVAL if invalid handle is provided .. index:: pair: function; cfg_find_str .. _doxid-group__confapi__base__traverse_1ga37cf17b8766ecea92254fbb8bca4a2ce: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_find_str(const char* oid, :ref:`cfg_handle`* p_handle) Find the object or object instance by its object identifier. Root object identifier is "/"; root object instance identifier is "/:". .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - oid - object identifier in string representation * - p_handle - location for object or instance handle .. rubric:: Returns: Status code .. index:: pair: function; cfg_find_vfmt .. _doxid-group__confapi__base__traverse_1ga9b45055e6b4d8fed735918a5ffca3586: .. ref-code-block:: cpp :class: doxyrest-title-code-block static :ref:`te_errno` cfg_find_vfmt(:ref:`cfg_handle`* p_handle, const char* oid_fmt, va_list ap) The same function as cfg_find_str, but OID may be format string .. index:: pair: function; cfg_find_fmt .. _doxid-group__confapi__base__traverse_1ga9cdd3da072912eed20a6fff287e5ab41: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_find_fmt(:ref:`cfg_handle`* p_handle, const char* oid_fmt, ...) The same function as cfg_find_str, but OID may be format string .. index:: pair: function; cfg_find .. _doxid-group__confapi__base__traverse_1gadb1130a2677db186f2490f2ab5dcfad3: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` :ref:`te_errno` cfg_find(const :ref:`cfg_oid`* oid, :ref:`cfg_handle`* handle) Find the object or object instance by its object identifier. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - oid - object identifier * - handle - location for object or instance handle .. rubric:: Returns: Status code .. index:: pair: function; cfg_find_object_by_instance .. _doxid-group__confapi__base__traverse_1gadcc1333eafff1e0328261c54c1261d0a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_find_object_by_instance(:ref:`cfg_handle` instance, :ref:`cfg_handle`* object) Find object of the given instance. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - instance - instance handle * - object - location for object handle .. rubric:: Returns: Status code .. index:: pair: function; cfg_find_pattern .. _doxid-group__confapi__base__traverse_1gad50c07980fe8982d4a9e21ca25365f96: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_find_pattern(const char* pattern, unsigned int* p_num, :ref:`cfg_handle`** p_set) Find all objects or object instances matching a pattern. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - pattern - string object identifier possibly containing '\*' (see Configurator documentation for details) * - p_num - number of found objects or object instances * - p_set - array of object/(object instance) handles; memory for the array is allocated using malloc() .. rubric:: Returns: 0 or TE_EINVAL if a pattern format is incorrect or some argument is NULL. .. index:: pair: function; cfg_find_pattern_fmt .. _doxid-group__confapi__base__traverse_1ga9dcbfffcbf3b64d5507427ab08cd7fa2: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_find_pattern_fmt(unsigned int* p_num, :ref:`cfg_handle`** p_set, const char* ptrn_fmt, ...) The same function as cfg_find_pattern, but OID may be format string .. index:: pair: function; cfg_find_pattern_iter_fmt .. _doxid-group__confapi__base__traverse_1ga204b780473c3bc4f5b9556658e0c5c93: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_find_pattern_iter_fmt(:ref:`cfg_handle_cb_func` cb_func, void* opaque, const char* ptrn_fmt, ...) Find all objects or object instances matching a pattern and call ``cb_func`` for each object. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - cb_func - Pointer to a callback function. * - opaque - Opaque argument to pass ``cb_func``. * - ptrn_fmt - Foramt string with the pattern. .. rubric:: Returns: Status code .. index:: pair: function; cfg_get_son .. _doxid-group__confapi__base__traverse_1gac0d4323d3419217f2baec3863a2885f8: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` :ref:`te_errno` cfg_get_son(:ref:`cfg_handle` handle, :ref:`cfg_handle`* son) Get handle of the oldest son of the object or object instance. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - handle of the object or object instance * - son - pointer to oldest son of the object or object instance. .. rubric:: Returns: Status code .. index:: pair: function; cfg_get_brother .. _doxid-group__confapi__base__traverse_1ga9e0e5968d9b93d81585b21f8bdf3952e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_brother(:ref:`cfg_handle` handle, :ref:`cfg_handle`* brother) Get handle of the brother of the object or object instance. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - handle of the object or object instance * - brother - pointer to the brother's handle .. rubric:: Returns: Status code .. index:: pair: function; cfg_get_father .. _doxid-group__confapi__base__traverse_1ga85e0c2c622e9fee6b45c3d754b95d107: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_get_father(:ref:`cfg_handle` handle, :ref:`cfg_handle`* father) Get handle of the father of the object or object instance. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - handle of the object or object instance * - father - pointer to the father's handle .. rubric:: Returns: Status code .. index:: pair: function; cfg_enumerate .. _doxid-group__confapi__base__traverse_1ga9258e3d4f666c7e8ad8a3689bde26fae: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` cfg_enumerate(:ref:`cfg_handle` handle, :ref:`cfg_inst_handler` callback, void* user_data) Enumerate all instances of the object (enumeration is stopped if callback returns non-zero). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - handle - object handle * - callback - the function to be called for each object instance * - user_data - opaque user data .. rubric:: Returns: Status code (see ``te_errno.h``) Macros ------ .. index:: pair: define; CFG_IS_INST .. _doxid-group__confapi__base__traverse_1ga3ad0733e7e0b0c8ce35f5e4ba0fd640e: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define CFG_IS_INST(_handle) Is it Configurator object instance handle? .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - _handle - Configurator handle