Wed Jan 8 2020 09:49:46

Asterisk developer's documentation


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