Avoid making AstData depend on libxml2 to compile.
[asterisk/asterisk.git] / 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 #ifdef HAVE_LIBXML2
504 /*!
505  * \brief Retrieve a subtree from the asterisk data API in XML format..
506  * \param[in] query The query structure specifying what nodes to retrieve.
507  * \retval NULL on error.
508  * \retval non-NULL The dynamically allocated requested sub-tree (it needs to be
509  *         released using ast_data_free.
510  * \see ast_data_free, ast_data_get
511  */
512 struct ast_xml_doc *ast_data_get_xml(const struct ast_data_query *query);
513 #endif
514
515 /*!
516  * \brief Release the allocated memory of a tree.
517  * \param[in] root The sub-tree pointer returned by a call to ast_data_get.
518  * \see ast_data_get
519  */
520 void ast_data_free(struct ast_data *root);
521
522 /*!
523  * \brief Get a node type.
524  * \param[in] res A pointer to the ast_data result set.
525  * \param[in] path A path to the node to get the type.
526  * \return The type of the requested node type.
527  */
528 enum ast_data_type ast_data_retrieve_type(struct ast_data *res, const char *path);
529
530 /*!
531  * \brief Get the node name.
532  * \param[in] node The node pointer.
533  * \returns The node name.
534  */
535 char *ast_data_retrieve_name(struct ast_data *node);
536
537 /*!
538  * \brief Add a container child.
539  * \param[in] root The root of the ast_data to insert into.
540  * \param[in] childname The name of the child element to be added.
541  * \retval NULL on error (memory exhaustion only).
542  * \retval non-NULL a newly allocated node.
543  */
544 struct ast_data *ast_data_add_node(struct ast_data *root, const char *childname);
545
546 /*!
547  * \brief Add an integer node type.
548  * \param[in] root The root of the ast_data to insert into.
549  * \param[in] childname The name of the child element to be added.
550  * \param[in] value The value for the new node.
551  * \retval NULL on error (memory exhaustion only).
552  * \retval non-NULL a newly allocated node.
553  */
554 struct ast_data *ast_data_add_int(struct ast_data *root, const char *childname,
555         int value);
556
557 /*!
558  * \brief Add an unsigned integer node type.
559  * \param[in] root The root of the ast_data to insert into.
560  * \param[in] childname The name of the child element to be added.
561  * \param[in] value The value for the new node.
562  * \retval NULL on error (memory exhaustion only).
563  * \retval non-NULL a newly allocated node.
564  */
565 struct ast_data *ast_data_add_uint(struct ast_data *root, const char *childname,
566         unsigned int value);
567
568 /*!
569  * \brief Add a floating point node type.
570  * \param[in] root The root of the ast_data to insert into.
571  * \param[in] childname The name of the child element to be added.
572  * \param[in] dbl The value for the new node.
573  * \retval NULL on error (memory exhaustion only).
574  * \retval non-NULL a newly allocated node.
575  */
576 struct ast_data *ast_data_add_dbl(struct ast_data *root, const char *childname,
577         double dbl);
578 /*!
579  * \brief Add a ipv4 address type.
580  * \param[in] root The root of the ast_data to insert into.
581  * \param[in] childname The name of the child element to be added.
582  * \param[in] addr The ipv4 address value.
583  * \retval NULL on error (memory exhaustion only).
584  * \retval non-NULL a newly allocated node.
585  */
586 struct ast_data *ast_data_add_ipaddr(struct ast_data *root, const char *childname,
587         struct in_addr addr);
588
589 /*!
590  * \brief Add a ptr node type.
591  * \param[in] root The root of the ast_data to insert into.
592  * \param[in] childname The name of the child element to be added.
593  * \param[in] ptr The pointer value to add.
594  * \retval NULL on error (memory exhaustion only).
595  * \retval non-NULL a newly allocated node.
596  */
597 struct ast_data *ast_data_add_ptr(struct ast_data *root, const char *childname,
598         void *ptr);
599
600 /*!
601  * \brief Add a string node type.
602  * \param[in] root The root of the ast_data to insert into.
603  * \param[in] childname The name of the child element to be added.
604  * \param[in] value The value for the new node.
605  * \retval NULL on error (memory exhaustion only).
606  * \retval non-NULL a newly allocated node.
607  */
608 struct ast_data *ast_data_add_str(struct ast_data *root, const char *childname,
609         const char *string);
610
611 /*!
612  * \brief Add a boolean node type.
613  * \param[in] root The root of the ast_data to insert into.
614  * \param[in] childname The name of the child element to be added.
615  * \param[in] value The value for the new node.
616  * \retval NULL on error (memory exhaustion only).
617  * \retval non-NULL a newly allocated node.
618  */
619 struct ast_data *ast_data_add_bool(struct ast_data *root, const char *childname,
620         unsigned int boolean);
621
622 /*!
623  * \brief Add a complete structure to a node.
624  * \param[in] root Where to add the structure.
625  * \param[in] mapping The structure mapping array.
626  * \param[in] mapping_len The lenght of the mapping array.
627  * \param[in] structure The structure pointer.
628  * \retval 0 on success.
629  * \retval 1 on error.
630  */
631 int __ast_data_add_structure(struct ast_data *root,
632         const struct ast_data_mapping_structure *mapping,
633         size_t mapping_len, void *structure);
634 #define ast_data_add_structure(structure_name, root, structure)                         \
635         __ast_data_add_structure(root, __data_mapping_structure_##structure_name,       \
636                 ARRAY_LEN(__data_mapping_structure_##structure_name), structure)
637
638 /*!
639  * \brief Remove a node that was added using ast_data_add_
640  * \param[in] root The root node of the node to be removed.
641  * \param[in] child The node pointer to remove.
642  */
643 void ast_data_remove_node(struct ast_data *root, struct ast_data *child);
644
645 /*!
646  * \brief Initialize an iterator.
647  * \param[in] tree The returned tree by a call to ast_data_get.
648  * \param[in] elements Which elements to iterate through.
649  * \retval NULL on error.
650  * \retval non-NULL A dinamically allocated iterator structure.
651  */
652 struct ast_data_iterator *ast_data_iterator_init(struct ast_data *tree,
653         const char *elements);
654
655 /*!
656  * \brief Release (stop using) an iterator.
657  * \param[in] iterator The iterator created by ast_data_iterator_start.
658  * \see ast_data_iterator_start
659  */
660 void ast_data_iterator_end(struct ast_data_iterator *iterator);
661
662 /*!
663  * \brief Get the next node of the tree.
664  * \param[in] iterator The iterator structure returned by ast_data_iterator_start.
665  * \retval NULL when no more nodes to return.
666  * \retval non-NULL A node of the ast_data tree.
667  * \see ast_data_iterator_start, ast_data_iterator_stop
668  */
669 struct ast_data *ast_data_iterator_next(struct ast_data_iterator *iterator);
670
671 /*!
672  * \brief Retrieve a value from a node in the tree.
673  * \param[in] tree The structure returned by a call to ast_data_get.
674  * \param[in] path The path to the node.
675  * \param[out] content The node content.
676  * \retval 0 on success.
677  * \retval <0 on error.
678  */
679 int ast_data_retrieve(struct ast_data *tree, const char *path, struct ast_data_retrieve *content);
680
681 /*!
682  * \brief Retrieve the integer value of a node.
683  * \param[in] tree The tree from where to get the value.
684  * \param[in] path The node name or path.
685  * \returns The value of the node.
686  */
687 static inline int ast_data_retrieve_int(struct ast_data *tree, const char *path)
688 {
689         struct ast_data_retrieve ret;
690
691         ast_data_retrieve(tree, path, &ret);
692
693         return ret.value.AST_DATA_INTEGER;
694 }
695
696 /*!
697  * \brief Retrieve the boolean value of a node.
698  * \param[in] tree The tree from where to get the value.
699  * \param[in] path The node name or path.
700  * \returns The value of the node.
701  */
702 static inline unsigned int ast_data_retrieve_bool(struct ast_data *tree, const char *path)
703 {
704         struct ast_data_retrieve ret;
705
706         ast_data_retrieve(tree, path, &ret);
707
708         return ret.value.AST_DATA_BOOLEAN;
709 }
710
711 /*!
712  * \brief Retrieve the unsigned integer value of a node.
713  * \param[in] tree The tree from where to get the value.
714  * \param[in] path The node name or path.
715  * \returns The value of the node.
716  */
717 static inline unsigned int ast_data_retrieve_uint(struct ast_data *tree, const char *path)
718 {
719         struct ast_data_retrieve ret;
720
721         ast_data_retrieve(tree, path, &ret);
722
723         return ret.value.AST_DATA_UNSIGNED_INTEGER;
724 }
725
726 /*!
727  * \brief Retrieve the string value of a node.
728  * \param[in] tree The tree from where to get the value.
729  * \param[in] path The node name or path.
730  * \returns The value of the node.
731  */
732 static inline const char *ast_data_retrieve_string(struct ast_data *tree, const char *path)
733 {
734         struct ast_data_retrieve ret;
735
736         ast_data_retrieve(tree, path, &ret);
737
738         return ret.value.AST_DATA_STRING;
739 }
740
741 /*!
742  * \brief Retrieve the ptr value of a node.
743  * \param[in] tree The tree from where to get the value.
744  * \param[in] path The node name or path.
745  * \returns The value of the node.
746  */
747 static inline void *ast_data_retrieve_ptr(struct ast_data *tree, const char *path)
748 {
749         struct ast_data_retrieve ret;
750
751         ast_data_retrieve(tree, path, &ret);
752
753         return ret.value.AST_DATA_POINTER;
754 }
755
756 /*!
757  * \brief Retrieve the double value of a node.
758  * \param[in] tree The tree from where to get the value.
759  * \param[in] path The node name or path.
760  * \returns The value of the node.
761  */
762 static inline double ast_data_retrieve_dbl(struct ast_data *tree, const char *path)
763 {
764         struct ast_data_retrieve ret;
765
766         ast_data_retrieve(tree, path, &ret);
767
768         return ret.value.AST_DATA_DOUBLE;
769 }
770
771 /*!
772  * \brief Retrieve the ipv4 address value of a node.
773  * \param[in] tree The tree from where to get the value.
774  * \param[in] path The node name or path.
775  * \returns The value of the node.
776  */
777 static inline struct in_addr ast_data_retrieve_ipaddr(struct ast_data *tree, const char *path)
778 {
779         struct ast_data_retrieve ret;
780
781         ast_data_retrieve(tree, path, &ret);
782
783         return ret.value.AST_DATA_IPADDR;
784 }
785
786 #if defined(__cplusplus) || defined(c_plusplus)
787 }
788 #endif
789
790 #endif /* ASTERISK_DATA_H */