include/asterisk/data.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2009, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
   5  *
   6  * See http://www.asterisk.org for more information about
   7  * the Asterisk project. Please do not directly contact
   8  * any of the maintainers of this project for assistance;
   9  * the project provides a web site, mailing lists and IRC
  10  * channels for your use.
  11  *
  12  * This program is free software, distributed under the terms of
  13  * the GNU General Public License Version 2. See the LICENSE file
  14  * at the top of the source tree.
  15  */
  16
  17 /*!
  18  * \file
  19  * \brief Data retrieval API.
  20  * \author Brett Bryant <brettbryant@gmail.com>
  21  * \author Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
  22  * \arg \ref AstDataRetrieval
  23  */
  24
  25 #ifndef ASTERISK_DATA_H
  26 #define ASTERISK_DATA_H
  27
  28 /*!
  29  * \page AstDataRetrieval The Asterisk DATA retrieval API.
  30  *
  31  * This module implements an abstraction for retrieving asterisk data and
  32  * export it.
  33  *
  34  * \section USAGE
  35  *
  36  * \subsection Provider
  37  *
  38  * \b Register
  39  *
  40  * To register a callback use:
  41  *
  42  * \code
  43  *      static const struct ast_data_handler callback_handler = {
  44  *              .get = callback_handler_get_function,
  45  *      };
  46  *
  47  *      ast_data_register("/node/path", &callback_handler);
  48  * \endcode
  49  *
  50  * If you instead want to register multiple nodes at once use:
  51  * \code
  52  *      static const struct ast_data_handler handler_struct1 = {
  53  *              .get = handler_callback_read,
  54  *      };
  55  *      ... other handlers ...
  56  *
  57  *      static const struct ast_data_entry list_providers[] = {
  58  *              AST_DATA_ENTRY("/path1/node1", &handler_struct1),
  59  *              AST_DATA_ENTRY("/path2/node2", &handler_struct2),
  60  *              AST_DATA_ENTRY("/path3/node3", &handler_struct3),
  61  *      };
  62  *
  63  *      ...
  64  *
  65  *      ast_data_register_multiple(list_providers, ARRAY_LEN(list_providers));
  66  * \endcode
  67  *
  68  * \b Unregister
  69  *
  70  * To unregister a callback function already registered you can just call:
  71  *
  72  * \code
  73  *      ast_data_unregister(NULL);
  74  * \endcode
  75  * And every node registered by the current module (file) will be unregistered.
  76  * If you want to unregister a specific node use:
  77  *
  78  * \code
  79  *      ast_data_unregister("/node/path");
  80  * \endcode
  81  *
  82  * \b Implementation
  83  *
  84  * A simple callback function implementation:
  85  *
  86  * \code
  87  *      #include <data.h>
  88  *
  89  *      struct test_structure {
  90  *              int a;
  91  *              double b;
  92  *      };
  93  *
  94  *      DATA_EXPORT_TEST_STRUCTURE(MEMBER)                      \
  95  *              MEMBER(test_structure, a, AST_DATA_INTEGER)     \
  96  *              MEMBER(test_structure, b, AST_DATA_DOUBLE)
  97  *
  98  *      AST_DATA_STRUCTURE(test_structure, DATA_EXPORT_TEST_STRUCTURE)
  99  *
 100  *      static int my_callback_function(struct ast_data_search *search,
 101  *              struct ast_data *root_node)
 102  *      {
 103  *              struct ast_data *internal_node;
 104  *              struct test_structure ts = {
 105  *                      .a = 10,
 106  *                      .b = 20
 107  *              };
 108  *
 109  *              if (ast_data_search_cmp_structure(search, test_structure, "test_node")) {
 110  *                      return 0;
 111  *              }
 112  *
 113  *              internal_node = ast_data_add_node(root_node, "test_node");
 114  *              if (!internal_node) {
 115  *                      return -1;
 116  *              }
 117  *
 118  *              ast_data_add_structure(test_structure, internal_node, ts);
 119  *
 120  *              return 0;
 121  *      }
 122  *
 123  * \endcode
 124  *
 125  * \subsection Get
 126  *
 127  * \b Getting \b the \b tree
 128  *
 129  * To get the tree you need to create a query, a query is based on three parameters
 130  * a \b path to the provider, a \b search condition and a \b filter condition.
 131  * \code
 132  *      struct ast_data *result;
 133  *      struct ast_data_query query = {
 134  *              .path = "/asterisk/application/app_queue/queues",
 135  *              .search = "/queues/queue/name=queue1",
 136  *              .filter = "/queues/queue/name|wrapuptime|members/member/interface"
 137  *      };
 138  *
 139  *      result = ast_data_get(&query);
 140  * \endcode
 141  *
 142  * After using it you need to release the allocated memory of the returned tree:
 143  * \code
 144  *      ast_data_free(result);
 145  * \endcode
 146  *
 147  * \b Iterate
 148  *
 149  * To retrieve nodes from the tree, it is possible to iterate through the returned
 150  * nodes of the tree using:
 151  * \code
 152  *      struct ast_data_iterator *i;
 153  *      struct ast_data *internal_node;
 154  *
 155  *      i = ast_data_iterator_init(result_tree, "path/node_name");
 156  *      while ((internal_node = ast_data_iterator_next(i))) {
 157  *              ... do something with node ...
 158  *      }
 159  *      ast_data_iterator_end(i);
 160  * \endcode
 161  * node_name is the name of the nodes to retrieve and path is the path to the internal
 162  * nodes to retrieve (if needed).
 163  *
 164  * \b Retrieving
 165  *
 166  * After getting the node you where searching for, you will need to retrieve its value,
 167  * to do that you may use one of the ast_data_retrieve_##type functions:
 168  * \code
 169  *      int a = ast_data_retrieve_int(tree, "path/to/the/node");
 170  *      double b = ast_data_retrieve_dbl(tree, "path/to/the/node");
 171  *      unsigned int c = ast_data_retrieve_bool(tree, "path/to/the/node");
 172  *      char *d = ast_data_retrieve_string(tree, "path/to/the/node");
 173  *      struct sockaddr_in e = ast_data_retrieve_ipaddr(tree, "path/to/the/node");
 174  *      unsigned int f = ast_data_retrieve_uint(tree, "path/to/the/node");
 175  *      void *g = ast_data_retrieve_ptr(tree, "path/to/the/node");
 176  * \endcode
 177  *
 178  */
 179
 180 #if defined(__cplusplus) || defined(c_plusplus)
 181 extern "C" {
 182 #endif
 183
 184 /*! \brief The data type of the data node. */
 185 enum ast_data_type {
 186         AST_DATA_CONTAINER,
 187         AST_DATA_INTEGER,
 188         AST_DATA_UNSIGNED_INTEGER,
 189         AST_DATA_DOUBLE,
 190         AST_DATA_BOOLEAN,
 191         AST_DATA_STRING,
 192         AST_DATA_IPADDR,
 193         AST_DATA_POINTER
 194 };
 195
 196 /*! \brief The Data API structures version. */
 197 #define AST_DATA_HANDLER_VERSION 1
 198 #define AST_DATA_QUERY_VERSION   1
 199
 200 /*! \brief opaque definition of an ast_data handler, a tree node. */
 201 struct ast_data;
 202
 203 /*! \brief opaque definition of an ast_data_iterator handler. */
 204 struct ast_data_iterator;
 205
 206 /*! \brief opaque definition of an ast_data_search structure. */
 207 struct ast_data_search;
 208
 209 /*! \brief structure retrieved from a node, with the nodes content. */
 210 struct ast_data_retrieve {
 211         /*! \brief The type of the node retrieved. */
 212         enum ast_data_type type;
 213
 214         union {
 215                 char *AST_DATA_STRING;
 216                 int AST_DATA_INTEGER;
 217                 double AST_DATA_DOUBLE;
 218                 unsigned int AST_DATA_UNSIGNED_INTEGER;
 219                 unsigned int AST_DATA_BOOLEAN;
 220                 void *AST_DATA_POINTER;
 221                 struct in_addr AST_DATA_IPADDR;
 222                 void *AST_DATA_CONTAINER;
 223         } value;
 224 };
 225
 226 /*!
 227  * \brief The get callback definition.
 228  */
 229 typedef int (*ast_data_get_cb)(const struct ast_data_search *search,
 230         struct ast_data *root);
 231
 232 /*! \brief The structure of the node handler. */
 233 struct ast_data_handler {
 234         /*! \brief Structure version. */
 235         uint32_t version;
 236         /*! \brief Data get callback implementation. */
 237         ast_data_get_cb get;
 238 };
 239
 240 /*! \brief This entries are for multiple registers. */
 241 struct ast_data_entry {
 242         /*! \brief Path of the node to register. */
 243         const char *path;
 244         /*! \brief Data handler structure. */
 245         const struct ast_data_handler *handler;
 246 };
 247
 248 #define AST_DATA_ENTRY(__path, __handler) { .path = __path, .handler = __handler }
 249
 250 /*! \brief A query to the data API is specified in this structure. */
 251 struct ast_data_query {
 252         /*! \brief Data query version. */
 253         uint32_t version;
 254         /*! \brief Path to the node to retrieve. */
 255         char *path;
 256         /*! \brief Filter string, return the internal nodes specified here.
 257          *         Setting it to NULL will return every internal node. */
 258         char *filter;
 259         /*! \brief Search condition. */
 260         char *search;
 261 };
 262
 263 /*! \brief Map the members of a structure. */
 264 struct ast_data_mapping_structure {
 265         /*! \brief structure member name. */
 266         const char *name;
 267         /*! \brief structure member type. */
 268         enum ast_data_type type;
 269         /*! \brief member getter. */
 270         union {
 271                 char *(*AST_DATA_STRING)(void *ptr);
 272                 int (*AST_DATA_INTEGER)(void *ptr);
 273                 double (*AST_DATA_DOUBLE)(void *ptr);
 274                 unsigned int (*AST_DATA_UNSIGNED_INTEGER)(void *ptr);
 275                 unsigned int (*AST_DATA_BOOLEAN)(void *ptr);
 276                 void *(*AST_DATA_POINTER)(void *ptr);
 277                 struct in_addr (*AST_DATA_IPADDR)(void *ptr);
 278                 void *(*AST_DATA_CONTAINER)(void *ptr);
 279         } get;
 280 };
 281
 282 /* Generate the structure and the functions to access the members of a structure. */
 283 #define AST_DATA_STRUCTURE(__struct, __name)                                                            \
 284         __name(__AST_DATA_MAPPING_FUNCTION);                                                            \
 285         static const struct ast_data_mapping_structure __data_mapping_structure_##__struct[] = {        \
 286                 __name(__AST_DATA_MAPPING_STRUCTURE)                                                    \
 287         }
 288
 289 /* Generate the structure to access the members and setup the pointer of the getter. */
 290 #define __AST_DATA_MAPPING_STRUCTURE(__structure, __member, __type)                             \
 291         { .name = #__member, .get.__type = data_mapping_structure_get_##__structure##__member,  \
 292         .type = __type },
 293
 294 /* based on the data type, specifify the type of return value for the getter function. */
 295 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_STRING(__structure, __member)                              \
 296         __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_STRING, char *)
 297 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_INTEGER(__structure, __member)                             \
 298         __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_INTEGER, int)
 299 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_UNSIGNED_INTEGER(__structure, __member)                    \
 300         __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_UNSIGNED_INTEGER, unsigned int)
 301 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_BOOLEAN(__structure, __member)                             \
 302         __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_BOOLEAN, unsigned int)
 303 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_POINTER(__structure, __member)                             \
 304         __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_POINTER, void *)
 305 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_IPADDR(__structure, __member)                              \
 306         __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_IPADDR, struct in_addr)
 307 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_DOUBLE(__structure, __member)                              \
 308         __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_DBL, double)
 309 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_CONTAINER(__structure, __member)                           \
 310         __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_CONTAINER, void *)
 311
 312 #define __AST_DATA_MAPPING_FUNCTION(__structure, __member, __type)              \
 313         __AST_DATA_MAPPING_FUNCTION_##__type(__structure, __member)
 314
 315 /* Create the function to retrieve a member of the structure. */
 316 #define __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, __type, __real_type)            \
 317         static __real_type data_mapping_structure_get_##__structure##__member(void *ptr) {      \
 318                 struct __structure *struct_##__member = (struct __structure *) ptr;             \
 319                 return (__real_type) struct_##__member->__member;                               \
 320         }
 321
 322 /*!
 323  * \brief Register a data provider.
 324  * \param[in] path The path of the node to register.
 325  * \param[in] handler The structure defining this node handler.
 326  * \param[in] registrar Who is registering this node.
 327  * \param[in] mod The module registering this handler.
 328  * \see ast_data_unregister
 329  * \retval <0 on error.
 330  * \retval 0 on success.
 331  * \see __ast_data_unregister, __ast_data_register_multiple
 332  */
 333 int __ast_data_register(const char *path, const struct ast_data_handler *handler,
 334         const char *registrar, struct ast_module *mod);
 335 #define ast_data_register(path, handler) __ast_data_register(path, handler, __FILE__, ast_module_info->self)
 336 #define ast_data_register_core(path, handler) __ast_data_register(path, handler, __FILE__, NULL)
 337
 338 /*!
 339  * \brief Register multiple data providers at once.
 340  * \param[in] data_entries An array of data_entries structures.
 341  * \param[in] entries The number of entries in the data_entries array.
 342  * \param[in] registrar Who is registering this nodes.
 343  * \param[in] mod The module registering this handlers.
 344  * \retval <0 on error (none of the nodes are being registered on error).
 345  * \retval 0 on success.
 346  * \see __ast_data_register, __ast_data_unregister
 347  */
 348 int __ast_data_register_multiple(const struct ast_data_entry *data_entries,
 349         size_t entries, const char *registrar, struct ast_module *mod);
 350 #define ast_data_register_multiple(data_entries, entries) \
 351         __ast_data_register_multiple(data_entries, entries, __FILE__, ast_module_info->self)
 352 #define ast_data_register_multiple_core(data_entries, entries) \
 353         __ast_data_register_multiple(data_entries, entries, __FILE__, NULL)
 354
 355 /*!
 356  * \brief Unregister a data provider.
 357  * \param[in] path Which node to unregister, if path is NULL unregister every node
 358  *                 registered by the passed 'registrar'.
 359  * \param[in] registrar Who is trying to unregister this node, only the owner (the
 360  *                      one who registered the node) will be able to unregister it.
 361  * \see ast_data_register
 362  * \retval <0 on error.
 363  * \retval 0 on success.
 364  * \see __ast_data_register, __ast_data_register_multiple
 365  */
 366 int __ast_data_unregister(const char *path, const char *registrar);
 367 #define ast_data_unregister(path) __ast_data_unregister(path, __FILE__)
 368
 369 /*!
 370  * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the
 371  *        current string value.
 372  *        .search = "somename=somestring"
 373  *        name = "somename"
 374  *        value is the current value of something and will be evaluated against "somestring".
 375  * \param[in] root The root node pointer of the search tree.
 376  * \param[in] name The name of the specific.
 377  * \param[in] value The value to compare.
 378  * \returns The strcmp return value.
 379  */
 380 int ast_data_search_cmp_string(const struct ast_data_search *root, const char *name, char *value);
 381
 382 /*!
 383  * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the
 384  *        current pointer address value.
 385  *        .search = "something=0x32323232"
 386  *        name = "something"
 387  *        value is the current value of something and will be evaluated against "0x32323232".
 388  * \param[in] root The root node pointer of the search tree.
 389  * \param[in] name The name of the specific.
 390  * \param[in] ptr The pointer address to compare.
 391  * \returns The (value - current_value) result.
 392  */
 393 int ast_data_search_cmp_ptr(const struct ast_data_search *root, const char *name,
 394         void *ptr);
 395
 396 /*!
 397  * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the
 398  *        current ipv4 address value.
 399  *        .search = "something=192.168.2.2"
 400  *        name = "something"
 401  *        value is the current value of something and will be evaluated against "192.168.2.2".
 402  * \param[in] root The root node pointer of the search tree.
 403  * \param[in] name The name of the specific.
 404  * \param[in] addr The ipv4 address value to compare.
 405  * \returns The (value - current_value) result.
 406  */
 407 int ast_data_search_cmp_ipaddr(const struct ast_data_search *root, const char *name,
 408         struct in_addr addr);
 409
 410 /*!
 411  * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the
 412  *        current double value.
 413  *        .search = "something=222"
 414  *        name = "something"
 415  *        value is the current value of something and will be evaluated against "222".
 416  * \param[in] root The root node pointer of the search tree.
 417  * \param[in] name The name of the specific.
 418  * \param[in] value The double value to compare.
 419  * \returns The (value - current_value) result.
 420  */
 421 int ast_data_search_cmp_dbl(const struct ast_data_search *root, const char *name,
 422         double value);
 423
 424 /*!
 425  * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the
 426  *        current boolean value.
 427  *        .search = "something=true"
 428  *        name = "something"
 429  *        value is the current value of something and will be evaluated against "true".
 430  * \param[in] root The root node pointer of the search tree.
 431  * \param[in] name The name of the specific.
 432  * \param[in] value The boolean value to compare.
 433  * \returns The (value - current_value) result.
 434  */
 435 int ast_data_search_cmp_bool(const struct ast_data_search *root, const char *name,
 436         unsigned int value);
 437
 438 /*!
 439  * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the
 440  *        current unsigned integer value.
 441  *        .search = "something=10"
 442  *        name = "something"
 443  *        value is the current value of something and will be evaluated against "10".
 444  * \param[in] root The root node pointer of the search tree.
 445  * \param[in] name The name of the specific.
 446  * \param[in] value The unsigned value to compare.
 447  * \returns The strcmp return value.
 448  */
 449 int ast_data_search_cmp_uint(const struct ast_data_search *root, const char *name,
 450         unsigned int value);
 451
 452 /*!
 453  * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the
 454  *        current signed integer value.
 455  *        .search = "something=10"
 456  *        name = "something"
 457  *        value is the current value of something and will be evaluated against "10".
 458  * \param[in] root The root node pointer of the search tree.
 459  * \param[in] name The name of the specific.
 460  * \param[in] value The value to compare.
 461  * \returns The strcmp return value.
 462  */
 463 int ast_data_search_cmp_int(const struct ast_data_search *root, const char *name, int value);
 464
 465 /*!
 466  * \brief Based on a search tree, evaluate every member of a structure against it.
 467  * \param[in] search The search tree.
 468  * \param[in] mapping The structure mapping.
 469  * \param[in] mapping_len The lenght of the structure mapping.
 470  * \param[in] structure The structure pointer.
 471  * \param[in] structure_name The name of the structure to compare.
 472  * \retval 0 If the structure matches.
 473  * \retval 1 If the structure doesn't match.
 474  */
 475 int __ast_data_search_cmp_structure(const struct ast_data_search *search,
 476         const struct ast_data_mapping_structure *mapping, size_t mapping_len,
 477         void *structure, const char *structure_name);
 478 #define ast_data_search_cmp_structure(search, structure_name, structure, structure_name_cmp)            \
 479         __ast_data_search_cmp_structure(search, __data_mapping_structure_##structure_name,              \
 480         ARRAY_LEN(__data_mapping_structure_##structure_name), structure, structure_name_cmp)
 481
 482 /*!
 483  * \brief Check if there is a compare condition inside the search tree with the
 484  *        passed 'compare_condition' node names.
 485  * \param[in] search The search tree.
 486  * \param[in] compare_condition The path of the compare condition.
 487  * \retval 0 There is no compare condition.
 488  * \retval 1 There is a compare condition.
 489  */
 490 int ast_data_search_has_condition(const struct ast_data_search *search,
 491         const char *compare_condition);
 492
 493 /*!
 494  * \brief Retrieve a subtree from the asterisk data API.
 495  * \param[in] query The query structure specifying what nodes to retrieve.
 496  * \retval NULL on error.
 497  * \retval non-NULL The dynamically allocated requested sub-tree (it needs to be
 498  *         released using ast_data_free.
 499  * \see ast_data_free, ast_data_get_xml
 500  */
 501 struct ast_data *ast_data_get(const struct ast_data_query *query);
 502
 503 /*!
 504  * \brief Retrieve a subtree from the asterisk data API in XML format..
 505  * \param[in] query The query structure specifying what nodes to retrieve.
 506  * \retval NULL on error.
 507  * \retval non-NULL The dynamically allocated requested sub-tree (it needs to be
 508  *         released using ast_data_free.
 509  * \see ast_data_free, ast_data_get
 510  */
 511 struct ast_xml_doc *ast_data_get_xml(const struct ast_data_query *query);
 512
 513 /*!
 514  * \brief Release the allocated memory of a tree.
 515  * \param[in] root The sub-tree pointer returned by a call to ast_data_get.
 516  * \see ast_data_get
 517  */
 518 void ast_data_free(struct ast_data *root);
 519
 520 /*!
 521  * \brief Get a node type.
 522  * \param[in] res A pointer to the ast_data result set.
 523  * \param[in] path A path to the node to get the type.
 524  * \return The type of the requested node type.
 525  */
 526 enum ast_data_type ast_data_retrieve_type(struct ast_data *res, const char *path);
 527
 528 /*!
 529  * \brief Get the node name.
 530  * \param[in] node The node pointer.
 531  * \returns The node name.
 532  */
 533 char *ast_data_retrieve_name(struct ast_data *node);
 534
 535 /*!
 536  * \brief Add a container child.
 537  * \param[in] root The root of the ast_data to insert into.
 538  * \param[in] childname The name of the child element to be added.
 539  * \retval NULL on error (memory exhaustion only).
 540  * \retval non-NULL a newly allocated node.
 541  */
 542 struct ast_data *ast_data_add_node(struct ast_data *root, const char *childname);
 543
 544 /*!
 545  * \brief Add an integer node type.
 546  * \param[in] root The root of the ast_data to insert into.
 547  * \param[in] childname The name of the child element to be added.
 548  * \param[in] value The value for the new node.
 549  * \retval NULL on error (memory exhaustion only).
 550  * \retval non-NULL a newly allocated node.
 551  */
 552 struct ast_data *ast_data_add_int(struct ast_data *root, const char *childname,
 553         int value);
 554
 555 /*!
 556  * \brief Add an unsigned integer node type.
 557  * \param[in] root The root of the ast_data to insert into.
 558  * \param[in] childname The name of the child element to be added.
 559  * \param[in] value The value for the new node.
 560  * \retval NULL on error (memory exhaustion only).
 561  * \retval non-NULL a newly allocated node.
 562  */
 563 struct ast_data *ast_data_add_uint(struct ast_data *root, const char *childname,
 564         unsigned int value);
 565
 566 /*!
 567  * \brief Add a floating point node type.
 568  * \param[in] root The root of the ast_data to insert into.
 569  * \param[in] childname The name of the child element to be added.
 570  * \param[in] dbl The value for the new node.
 571  * \retval NULL on error (memory exhaustion only).
 572  * \retval non-NULL a newly allocated node.
 573  */
 574 struct ast_data *ast_data_add_dbl(struct ast_data *root, const char *childname,
 575         double dbl);
 576 /*!
 577  * \brief Add a ipv4 address type.
 578  * \param[in] root The root of the ast_data to insert into.
 579  * \param[in] childname The name of the child element to be added.
 580  * \param[in] addr The ipv4 address value.
 581  * \retval NULL on error (memory exhaustion only).
 582  * \retval non-NULL a newly allocated node.
 583  */
 584 struct ast_data *ast_data_add_ipaddr(struct ast_data *root, const char *childname,
 585         struct in_addr addr);
 586
 587 /*!
 588  * \brief Add a ptr node type.
 589  * \param[in] root The root of the ast_data to insert into.
 590  * \param[in] childname The name of the child element to be added.
 591  * \param[in] ptr The pointer value to add.
 592  * \retval NULL on error (memory exhaustion only).
 593  * \retval non-NULL a newly allocated node.
 594  */
 595 struct ast_data *ast_data_add_ptr(struct ast_data *root, const char *childname,
 596         void *ptr);
 597
 598 /*!
 599  * \brief Add a string node type.
 600  * \param[in] root The root of the ast_data to insert into.
 601  * \param[in] childname The name of the child element to be added.
 602  * \param[in] value The value for the new node.
 603  * \retval NULL on error (memory exhaustion only).
 604  * \retval non-NULL a newly allocated node.
 605  */
 606 struct ast_data *ast_data_add_str(struct ast_data *root, const char *childname,
 607         const char *string);
 608
 609 /*!
 610  * \brief Add a boolean node type.
 611  * \param[in] root The root of the ast_data to insert into.
 612  * \param[in] childname The name of the child element to be added.
 613  * \param[in] value The value for the new node.
 614  * \retval NULL on error (memory exhaustion only).
 615  * \retval non-NULL a newly allocated node.
 616  */
 617 struct ast_data *ast_data_add_bool(struct ast_data *root, const char *childname,
 618         unsigned int boolean);
 619
 620 /*!
 621  * \brief Add a complete structure to a node.
 622  * \param[in] root Where to add the structure.
 623  * \param[in] mapping The structure mapping array.
 624  * \param[in] mapping_len The lenght of the mapping array.
 625  * \param[in] structure The structure pointer.
 626  * \retval 0 on success.
 627  * \retval 1 on error.
 628  */
 629 int __ast_data_add_structure(struct ast_data *root,
 630         const struct ast_data_mapping_structure *mapping,
 631         size_t mapping_len, void *structure);
 632 #define ast_data_add_structure(structure_name, root, structure)                         \
 633         __ast_data_add_structure(root, __data_mapping_structure_##structure_name,       \
 634                 ARRAY_LEN(__data_mapping_structure_##structure_name), structure)
 635
 636 /*!
 637  * \brief Remove a node that was added using ast_data_add_
 638  * \param[in] root The root node of the node to be removed.
 639  * \param[in] child The node pointer to remove.
 640  */
 641 void ast_data_remove_node(struct ast_data *root, struct ast_data *child);
 642
 643 /*!
 644  * \brief Initialize an iterator.
 645  * \param[in] tree The returned tree by a call to ast_data_get.
 646  * \param[in] elements Which elements to iterate through.
 647  * \retval NULL on error.
 648  * \retval non-NULL A dinamically allocated iterator structure.
 649  */
 650 struct ast_data_iterator *ast_data_iterator_init(struct ast_data *tree,
 651         const char *elements);
 652
 653 /*!
 654  * \brief Release (stop using) an iterator.
 655  * \param[in] iterator The iterator created by ast_data_iterator_start.
 656  * \see ast_data_iterator_start
 657  */
 658 void ast_data_iterator_end(struct ast_data_iterator *iterator);
 659
 660 /*!
 661  * \brief Get the next node of the tree.
 662  * \param[in] iterator The iterator structure returned by ast_data_iterator_start.
 663  * \retval NULL when no more nodes to return.
 664  * \retval non-NULL A node of the ast_data tree.
 665  * \see ast_data_iterator_start, ast_data_iterator_stop
 666  */
 667 struct ast_data *ast_data_iterator_next(struct ast_data_iterator *iterator);
 668
 669 /*!
 670  * \brief Retrieve a value from a node in the tree.
 671  * \param[in] tree The structure returned by a call to ast_data_get.
 672  * \param[in] path The path to the node.
 673  * \param[out] content The node content.
 674  * \retval 0 on success.
 675  * \retval <0 on error.
 676  */
 677 int ast_data_retrieve(struct ast_data *tree, const char *path, struct ast_data_retrieve *content);
 678
 679 /*!
 680  * \brief Retrieve the integer value of a node.
 681  * \param[in] tree The tree from where to get the value.
 682  * \param[in] path The node name or path.
 683  * \returns The value of the node.
 684  */
 685 static inline int ast_data_retrieve_int(struct ast_data *tree, const char *path)
 686 {
 687         struct ast_data_retrieve ret;
 688
 689         ast_data_retrieve(tree, path, &ret);
 690
 691         return ret.value.AST_DATA_INTEGER;
 692 }
 693
 694 /*!
 695  * \brief Retrieve the boolean value of a node.
 696  * \param[in] tree The tree from where to get the value.
 697  * \param[in] path The node name or path.
 698  * \returns The value of the node.
 699  */
 700 static inline unsigned int ast_data_retrieve_bool(struct ast_data *tree, const char *path)
 701 {
 702         struct ast_data_retrieve ret;
 703
 704         ast_data_retrieve(tree, path, &ret);
 705
 706         return ret.value.AST_DATA_BOOLEAN;
 707 }
 708
 709 /*!
 710  * \brief Retrieve the unsigned integer value of a node.
 711  * \param[in] tree The tree from where to get the value.
 712  * \param[in] path The node name or path.
 713  * \returns The value of the node.
 714  */
 715 static inline unsigned int ast_data_retrieve_uint(struct ast_data *tree, const char *path)
 716 {
 717         struct ast_data_retrieve ret;
 718
 719         ast_data_retrieve(tree, path, &ret);
 720
 721         return ret.value.AST_DATA_UNSIGNED_INTEGER;
 722 }
 723
 724 /*!
 725  * \brief Retrieve the string value of a node.
 726  * \param[in] tree The tree from where to get the value.
 727  * \param[in] path The node name or path.
 728  * \returns The value of the node.
 729  */
 730 static inline const char *ast_data_retrieve_string(struct ast_data *tree, const char *path)
 731 {
 732         struct ast_data_retrieve ret;
 733
 734         ast_data_retrieve(tree, path, &ret);
 735
 736         return ret.value.AST_DATA_STRING;
 737 }
 738
 739 /*!
 740  * \brief Retrieve the ptr value of a node.
 741  * \param[in] tree The tree from where to get the value.
 742  * \param[in] path The node name or path.
 743  * \returns The value of the node.
 744  */
 745 static inline void *ast_data_retrieve_ptr(struct ast_data *tree, const char *path)
 746 {
 747         struct ast_data_retrieve ret;
 748
 749         ast_data_retrieve(tree, path, &ret);
 750
 751         return ret.value.AST_DATA_POINTER;
 752 }
 753
 754 /*!
 755  * \brief Retrieve the double value of a node.
 756  * \param[in] tree The tree from where to get the value.
 757  * \param[in] path The node name or path.
 758  * \returns The value of the node.
 759  */
 760 static inline double ast_data_retrieve_dbl(struct ast_data *tree, const char *path)
 761 {
 762         struct ast_data_retrieve ret;
 763
 764         ast_data_retrieve(tree, path, &ret);
 765
 766         return ret.value.AST_DATA_DOUBLE;
 767 }
 768
 769 /*!
 770  * \brief Retrieve the ipv4 address value of a node.
 771  * \param[in] tree The tree from where to get the value.
 772  * \param[in] path The node name or path.
 773  * \returns The value of the node.
 774  */
 775 static inline struct in_addr ast_data_retrieve_ipaddr(struct ast_data *tree, const char *path)
 776 {
 777         struct ast_data_retrieve ret;
 778
 779         ast_data_retrieve(tree, path, &ret);
 780
 781         return ret.value.AST_DATA_IPADDR;
 782 }
 783
 784 #if defined(__cplusplus) || defined(c_plusplus)
 785 }
 786 #endif
 787
 788 #endif /* ASTERISK_DATA_H */