00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2009, Eliel C. Sardanons (LU1ALY) <eliels@gmail.com> 00005 * 00006 * See http://www.asterisk.org for more information about 00007 * the Asterisk project. Please do not directly contact 00008 * any of the maintainers of this project for assistance; 00009 * the project provides a web site, mailing lists and IRC 00010 * channels for your use. 00011 * 00012 * This program is free software, distributed under the terms of 00013 * the GNU General Public License Version 2. See the LICENSE file 00014 * at the top of the source tree. 00015 */ 00016 00017 /*! 00018 * \file 00019 * \brief Data retrieval API. 00020 * \author Brett Bryant <brettbryant@gmail.com> 00021 * \author Eliel C. Sardanons (LU1ALY) <eliels@gmail.com> 00022 * \arg \ref AstDataRetrieval 00023 */ 00024 00025 #ifndef ASTERISK_DATA_H 00026 #define ASTERISK_DATA_H 00027 00028 #include "asterisk/frame.h" 00029 00030 /*! 00031 * \page AstDataRetrieval The Asterisk DATA retrieval API. 00032 * 00033 * This module implements an abstraction for retrieving asterisk data and 00034 * export it. 00035 * 00036 * \section USAGE 00037 * 00038 * \subsection Provider 00039 * 00040 * \b Register 00041 * 00042 * To register a callback use: 00043 * 00044 * \code 00045 * static const struct ast_data_handler callback_handler = { 00046 * .get = callback_handler_get_function, 00047 * }; 00048 * 00049 * ast_data_register("/node/path", &callback_handler); 00050 * \endcode 00051 * 00052 * If you instead want to register multiple nodes at once use: 00053 * \code 00054 * static const struct ast_data_handler handler_struct1 = { 00055 * .get = handler_callback_read, 00056 * }; 00057 * ... other handlers ... 00058 * 00059 * static const struct ast_data_entry list_providers[] = { 00060 * AST_DATA_ENTRY("/path1/node1", &handler_struct1), 00061 * AST_DATA_ENTRY("/path2/node2", &handler_struct2), 00062 * AST_DATA_ENTRY("/path3/node3", &handler_struct3), 00063 * }; 00064 * 00065 * ... 00066 * 00067 * ast_data_register_multiple(list_providers, ARRAY_LEN(list_providers)); 00068 * \endcode 00069 * 00070 * \b Unregister 00071 * 00072 * To unregister a callback function already registered you can just call: 00073 * 00074 * \code 00075 * ast_data_unregister(NULL); 00076 * \endcode 00077 * And every node registered by the current module (file) will be unregistered. 00078 * If you want to unregister a specific node use: 00079 * 00080 * \code 00081 * ast_data_unregister("/node/path"); 00082 * \endcode 00083 * 00084 * \b Implementation 00085 * 00086 * A simple callback function implementation: 00087 * 00088 * \code 00089 * #include <data.h> 00090 * 00091 * struct test_structure { 00092 * int a; 00093 * double b; 00094 * }; 00095 * 00096 * DATA_EXPORT_TEST_STRUCTURE(MEMBER) \ 00097 * MEMBER(test_structure, a, AST_DATA_INTEGER) \ 00098 * MEMBER(test_structure, b, AST_DATA_DOUBLE) 00099 * 00100 * AST_DATA_STRUCTURE(test_structure, DATA_EXPORT_TEST_STRUCTURE) 00101 * 00102 * static int my_callback_function(struct ast_data_search *search, 00103 * struct ast_data *root_node) 00104 * { 00105 * struct ast_data *internal_node; 00106 * struct test_structure ts = { 00107 * .a = 10, 00108 * .b = 20 00109 * }; 00110 * 00111 * internal_node = ast_data_add_node(root_node, "test_node"); 00112 * if (!internal_node) { 00113 * return -1; 00114 * } 00115 * 00116 * ast_data_add_structure(test_structure, internal_node, ts); 00117 * 00118 * if (!ast_data_search_match(search, internal_node)) { 00119 * ast_data_remove_node(root_node, internal_node); 00120 * } 00121 * 00122 * return 0; 00123 * } 00124 * 00125 * \endcode 00126 * 00127 * \subsection Get 00128 * 00129 * \b Getting \b the \b tree 00130 * 00131 * To get the tree you need to create a query, a query is based on three parameters 00132 * a \b path to the provider, a \b search condition and a \b filter condition. 00133 * \code 00134 * struct ast_data *result; 00135 * struct ast_data_query query = { 00136 * .path = "/asterisk/application/app_queue/queues", 00137 * .search = "/queues/queue/name=queue1", 00138 * .filter = "/queues/queue/name|wrapuptime|members/member/interface" 00139 * }; 00140 * 00141 * result = ast_data_get(&query); 00142 * \endcode 00143 * 00144 * After using it you need to release the allocated memory of the returned tree: 00145 * \code 00146 * ast_data_free(result); 00147 * \endcode 00148 * 00149 * \b Iterate 00150 * 00151 * To retrieve nodes from the tree, it is possible to iterate through the returned 00152 * nodes of the tree using: 00153 * \code 00154 * struct ast_data_iterator *i; 00155 * struct ast_data *internal_node; 00156 * 00157 * i = ast_data_iterator_init(result_tree, "path/node_name"); 00158 * while ((internal_node = ast_data_iterator_next(i))) { 00159 * ... do something with node ... 00160 * } 00161 * ast_data_iterator_end(i); 00162 * \endcode 00163 * node_name is the name of the nodes to retrieve and path is the path to the internal 00164 * nodes to retrieve (if needed). 00165 * 00166 * \b Retrieving 00167 * 00168 * After getting the node you where searching for, you will need to retrieve its value, 00169 * to do that you may use one of the ast_data_retrieve_##type functions: 00170 * \code 00171 * int a = ast_data_retrieve_int(tree, "path/to/the/node"); 00172 * double b = ast_data_retrieve_dbl(tree, "path/to/the/node"); 00173 * unsigned int c = ast_data_retrieve_bool(tree, "path/to/the/node"); 00174 * char *d = ast_data_retrieve_string(tree, "path/to/the/node"); 00175 * struct sockaddr_in e = ast_data_retrieve_ipaddr(tree, "path/to/the/node"); 00176 * unsigned int f = ast_data_retrieve_uint(tree, "path/to/the/node"); 00177 * void *g = ast_data_retrieve_ptr(tree, "path/to/the/node"); 00178 * \endcode 00179 * 00180 */ 00181 00182 #if defined(__cplusplus) || defined(c_plusplus) 00183 extern "C" { 00184 #endif 00185 00186 /*! \brief The data type of the data node. */ 00187 enum ast_data_type { 00188 AST_DATA_CONTAINER, 00189 AST_DATA_INTEGER, 00190 AST_DATA_UNSIGNED_INTEGER, 00191 AST_DATA_DOUBLE, 00192 AST_DATA_BOOLEAN, 00193 AST_DATA_STRING, 00194 AST_DATA_CHARACTER, 00195 AST_DATA_PASSWORD, 00196 AST_DATA_IPADDR, 00197 AST_DATA_TIMESTAMP, 00198 AST_DATA_SECONDS, 00199 AST_DATA_MILLISECONDS, 00200 AST_DATA_POINTER 00201 }; 00202 00203 /*! \brief The Data API structures version. */ 00204 #define AST_DATA_HANDLER_VERSION 1 00205 #define AST_DATA_QUERY_VERSION 1 00206 00207 /*! \brief opaque definition of an ast_data handler, a tree node. */ 00208 struct ast_data; 00209 00210 /*! \brief opaque definition of an ast_data_iterator handler. */ 00211 struct ast_data_iterator; 00212 00213 /*! \brief opaque definition of an ast_data_search structure. */ 00214 struct ast_data_search; 00215 00216 /*! \brief structure retrieved from a node, with the nodes content. */ 00217 struct ast_data_retrieve { 00218 /*! \brief The type of the node retrieved. */ 00219 enum ast_data_type type; 00220 00221 union { 00222 char AST_DATA_CHARACTER; 00223 char *AST_DATA_STRING; 00224 char *AST_DATA_PASSWORD; 00225 int AST_DATA_INTEGER; 00226 unsigned int AST_DATA_TIMESTAMP; 00227 unsigned int AST_DATA_SECONDS; 00228 unsigned int AST_DATA_MILLISECONDS; 00229 double AST_DATA_DOUBLE; 00230 unsigned int AST_DATA_UNSIGNED_INTEGER; 00231 unsigned int AST_DATA_BOOLEAN; 00232 void *AST_DATA_POINTER; 00233 struct in_addr AST_DATA_IPADDR; 00234 void *AST_DATA_CONTAINER; 00235 } value; 00236 }; 00237 00238 /*! 00239 * \brief The get callback definition. 00240 */ 00241 typedef int (*ast_data_get_cb)(const struct ast_data_search *search, 00242 struct ast_data *root); 00243 00244 /*! \brief The structure of the node handler. */ 00245 struct ast_data_handler { 00246 /*! \brief Structure version. */ 00247 uint32_t version; 00248 /*! \brief Data get callback implementation. */ 00249 ast_data_get_cb get; 00250 }; 00251 00252 /*! \brief This entries are for multiple registers. */ 00253 struct ast_data_entry { 00254 /*! \brief Path of the node to register. */ 00255 const char *path; 00256 /*! \brief Data handler structure. */ 00257 const struct ast_data_handler *handler; 00258 }; 00259 00260 #define AST_DATA_ENTRY(__path, __handler) { .path = __path, .handler = __handler } 00261 00262 /*! \brief A query to the data API is specified in this structure. */ 00263 struct ast_data_query { 00264 /*! \brief Data query version. */ 00265 uint32_t version; 00266 /*! \brief Path to the node to retrieve. */ 00267 char *path; 00268 /*! \brief Filter string, return the internal nodes specified here. 00269 * Setting it to NULL will return every internal node. */ 00270 char *filter; 00271 /*! \brief Search condition. */ 00272 char *search; 00273 }; 00274 00275 /*! \brief Map the members of a structure. */ 00276 struct ast_data_mapping_structure { 00277 /*! \brief structure member name. */ 00278 const char *name; 00279 /*! \brief structure member type. */ 00280 enum ast_data_type type; 00281 /*! \brief member getter. */ 00282 union { 00283 char (*AST_DATA_CHARACTER)(void *ptr); 00284 char *(*AST_DATA_STRING)(void *ptr); 00285 char *(*AST_DATA_PASSWORD)(void *ptr); 00286 int (*AST_DATA_INTEGER)(void *ptr); 00287 int (*AST_DATA_TIMESTAMP)(void *ptr); 00288 int (*AST_DATA_SECONDS)(void *ptr); 00289 int (*AST_DATA_MILLISECONDS)(void *ptr); 00290 double (*AST_DATA_DOUBLE)(void *ptr); 00291 unsigned int (*AST_DATA_UNSIGNED_INTEGER)(void *ptr); 00292 unsigned int (*AST_DATA_BOOLEAN)(void *ptr); 00293 void *(*AST_DATA_POINTER)(void *ptr); 00294 struct in_addr (*AST_DATA_IPADDR)(void *ptr); 00295 void *(*AST_DATA_CONTAINER)(void *ptr); 00296 } get; 00297 }; 00298 00299 /* Generate the structure and the functions to access the members of a structure. */ 00300 #define AST_DATA_STRUCTURE(__struct, __name) \ 00301 __name(__AST_DATA_MAPPING_FUNCTION); \ 00302 static const struct ast_data_mapping_structure __data_mapping_structure_##__struct[] = { \ 00303 __name(__AST_DATA_MAPPING_STRUCTURE) \ 00304 } 00305 00306 /* Generate the structure to access the members and setup the pointer of the getter. */ 00307 #define __AST_DATA_MAPPING_STRUCTURE(__structure, __member, __type) \ 00308 { .name = #__member, .get.__type = data_mapping_structure_get_##__structure##__member, \ 00309 .type = __type }, 00310 00311 /* based on the data type, specifify the type of return value for the getter function. */ 00312 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_PASSWORD(__structure, __member) \ 00313 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_PASSWORD, char *) 00314 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_STRING(__structure, __member) \ 00315 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_STRING, char *) 00316 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_CHARACTER(__structure, __member) \ 00317 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_CHARACTER, char) 00318 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_INTEGER(__structure, __member) \ 00319 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_INTEGER, int) 00320 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_TIMESTAMP(__structure, __member) \ 00321 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_INTEGER, int) 00322 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_SECONDS(__structure, __member) \ 00323 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_INTEGER, int) 00324 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_MILLISECONDS(__structure, __member) \ 00325 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_INTEGER, int) 00326 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_UNSIGNED_INTEGER(__structure, __member) \ 00327 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_UNSIGNED_INTEGER, unsigned int) 00328 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_BOOLEAN(__structure, __member) \ 00329 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_BOOLEAN, unsigned int) 00330 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_POINTER(__structure, __member) \ 00331 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_POINTER, void *) 00332 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_IPADDR(__structure, __member) \ 00333 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_IPADDR, struct in_addr) 00334 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_DOUBLE(__structure, __member) \ 00335 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_DBL, double) 00336 #define __AST_DATA_MAPPING_FUNCTION_AST_DATA_CONTAINER(__structure, __member) \ 00337 __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_CONTAINER, void *) 00338 00339 #define __AST_DATA_MAPPING_FUNCTION(__structure, __member, __type) \ 00340 __AST_DATA_MAPPING_FUNCTION_##__type(__structure, __member) 00341 00342 /* Create the function to retrieve a member of the structure. */ 00343 #define __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, __type, __real_type) \ 00344 static __real_type data_mapping_structure_get_##__structure##__member(void *ptr) { \ 00345 struct __structure *struct_##__member = (struct __structure *) ptr; \ 00346 return (__real_type) struct_##__member->__member; \ 00347 } 00348 00349 /*! 00350 * \brief Register a data provider. 00351 * \param[in] path The path of the node to register. 00352 * \param[in] handler The structure defining this node handler. 00353 * \param[in] registrar Who is registering this node. 00354 * \param[in] mod The module registering this handler. 00355 * \see ast_data_unregister 00356 * \retval <0 on error. 00357 * \retval 0 on success. 00358 * \see __ast_data_unregister, __ast_data_register_multiple 00359 */ 00360 int __ast_data_register(const char *path, const struct ast_data_handler *handler, 00361 const char *registrar, struct ast_module *mod); 00362 #define ast_data_register(path, handler) __ast_data_register(path, handler, __FILE__, ast_module_info->self) 00363 #define ast_data_register_core(path, handler) __ast_data_register(path, handler, __FILE__, NULL) 00364 00365 /*! 00366 * \brief Register multiple data providers at once. 00367 * \param[in] data_entries An array of data_entries structures. 00368 * \param[in] entries The number of entries in the data_entries array. 00369 * \param[in] registrar Who is registering this nodes. 00370 * \param[in] mod The module registering this handlers. 00371 * \retval <0 on error (none of the nodes are being registered on error). 00372 * \retval 0 on success. 00373 * \see __ast_data_register, __ast_data_unregister 00374 */ 00375 int __ast_data_register_multiple(const struct ast_data_entry *data_entries, 00376 size_t entries, const char *registrar, struct ast_module *mod); 00377 #define ast_data_register_multiple(data_entries, entries) \ 00378 __ast_data_register_multiple(data_entries, entries, __FILE__, ast_module_info->self) 00379 #define ast_data_register_multiple_core(data_entries, entries) \ 00380 __ast_data_register_multiple(data_entries, entries, __FILE__, NULL) 00381 00382 /*! 00383 * \brief Unregister a data provider. 00384 * \param[in] path Which node to unregister, if path is NULL unregister every node 00385 * registered by the passed 'registrar'. 00386 * \param[in] registrar Who is trying to unregister this node, only the owner (the 00387 * one who registered the node) will be able to unregister it. 00388 * \see ast_data_register 00389 * \retval <0 on error. 00390 * \retval 0 on success. 00391 * \see __ast_data_register, __ast_data_register_multiple 00392 */ 00393 int __ast_data_unregister(const char *path, const char *registrar); 00394 #define ast_data_unregister(path) __ast_data_unregister(path, __FILE__) 00395 00396 /*! 00397 * \brief Check the current generated node to know if it matches the search 00398 * condition. 00399 * \param[in] search The search condition. 00400 * \param[in] data The AstData node generated. 00401 * \return 1 If the "data" node matches the search condition. 00402 * \return 0 If the "data" node does not matches the search condition. 00403 * \see ast_data_remove_node 00404 */ 00405 int ast_data_search_match(const struct ast_data_search *search, struct ast_data *data); 00406 00407 /*! 00408 * \brief Based on a search tree, evaluate every member of a structure against it. 00409 * \param[in] search The search tree. 00410 * \param[in] mapping The structure mapping. 00411 * \param[in] mapping_len The lenght of the structure mapping. 00412 * \param[in] structure The structure pointer. 00413 * \param[in] structure_name The name of the structure to compare. 00414 * \retval 0 If the structure matches. 00415 * \retval 1 If the structure doesn't match. 00416 */ 00417 int __ast_data_search_cmp_structure(const struct ast_data_search *search, 00418 const struct ast_data_mapping_structure *mapping, size_t mapping_len, 00419 void *structure, const char *structure_name); 00420 #define ast_data_search_cmp_structure(search, structure_name, structure, structure_name_cmp) \ 00421 __ast_data_search_cmp_structure(search, __data_mapping_structure_##structure_name, \ 00422 ARRAY_LEN(__data_mapping_structure_##structure_name), structure, structure_name_cmp) 00423 00424 /*! 00425 * \brief Retrieve a subtree from the asterisk data API. 00426 * \param[in] query The query structure specifying what nodes to retrieve. 00427 * \retval NULL on error. 00428 * \retval non-NULL The dynamically allocated requested sub-tree (it needs to be 00429 * released using ast_data_free. 00430 * \see ast_data_free, ast_data_get_xml 00431 */ 00432 struct ast_data *ast_data_get(const struct ast_data_query *query); 00433 00434 #ifdef HAVE_LIBXML2 00435 /*! 00436 * \brief Retrieve a subtree from the asterisk data API in XML format.. 00437 * \param[in] query The query structure specifying what nodes to retrieve. 00438 * \retval NULL on error. 00439 * \retval non-NULL The dynamically allocated requested sub-tree (it needs to be 00440 * released using ast_data_free. 00441 * \see ast_data_free, ast_data_get 00442 */ 00443 struct ast_xml_doc *ast_data_get_xml(const struct ast_data_query *query); 00444 #endif 00445 00446 /*! 00447 * \brief Release the allocated memory of a tree. 00448 * \param[in] root The sub-tree pointer returned by a call to ast_data_get. 00449 * \see ast_data_get 00450 */ 00451 void ast_data_free(struct ast_data *root); 00452 00453 /*! 00454 * \brief Get a node type. 00455 * \param[in] res A pointer to the ast_data result set. 00456 * \param[in] path A path to the node to get the type. 00457 * \return The type of the requested node type. 00458 */ 00459 enum ast_data_type ast_data_retrieve_type(struct ast_data *res, const char *path); 00460 00461 /*! 00462 * \brief Get the node name. 00463 * \param[in] node The node pointer. 00464 * \returns The node name. 00465 */ 00466 char *ast_data_retrieve_name(struct ast_data *node); 00467 00468 /*! 00469 * \brief Add a container child. 00470 * \param[in] root The root of the ast_data to insert into. 00471 * \param[in] childname The name of the child element to be added. 00472 * \retval NULL on error (memory exhaustion only). 00473 * \retval non-NULL a newly allocated node. 00474 */ 00475 struct ast_data *ast_data_add_node(struct ast_data *root, const char *childname); 00476 00477 /*! 00478 * \brief Add an integer node type. 00479 * \param[in] root The root of the ast_data to insert into. 00480 * \param[in] childname The name of the child element to be added. 00481 * \param[in] value The value for the new node. 00482 * \retval NULL on error (memory exhaustion only). 00483 * \retval non-NULL a newly allocated node. 00484 */ 00485 struct ast_data *ast_data_add_int(struct ast_data *root, const char *childname, 00486 int value); 00487 00488 /*! 00489 * \brief Add a char node type. 00490 * \param[in] root The root of the ast_data to insert into. 00491 * \param[in] childname The name of the child element to be added. 00492 * \param[in] value The value for the new node. 00493 * \retval NULL on error (memory exhaustion only). 00494 * \retval non-NULL a newly allocated node. 00495 */ 00496 struct ast_data *ast_data_add_char(struct ast_data *root, const char *childname, 00497 char value); 00498 00499 /*! 00500 * \brief Add an unsigned integer node type. 00501 * \param[in] root The root of the ast_data to insert into. 00502 * \param[in] childname The name of the child element to be added. 00503 * \param[in] value The value for the new node. 00504 * \retval NULL on error (memory exhaustion only). 00505 * \retval non-NULL a newly allocated node. 00506 */ 00507 struct ast_data *ast_data_add_uint(struct ast_data *root, const char *childname, 00508 unsigned int value); 00509 00510 /*! 00511 * \brief Add a floating point node type. 00512 * \param[in] root The root of the ast_data to insert into. 00513 * \param[in] childname The name of the child element to be added. 00514 * \param[in] dbl The value for the new node. 00515 * \retval NULL on error (memory exhaustion only). 00516 * \retval non-NULL a newly allocated node. 00517 */ 00518 struct ast_data *ast_data_add_dbl(struct ast_data *root, const char *childname, 00519 double dbl); 00520 /*! 00521 * \brief Add a ipv4 address type. 00522 * \param[in] root The root of the ast_data to insert into. 00523 * \param[in] childname The name of the child element to be added. 00524 * \param[in] addr The ipv4 address value. 00525 * \retval NULL on error (memory exhaustion only). 00526 * \retval non-NULL a newly allocated node. 00527 */ 00528 struct ast_data *ast_data_add_ipaddr(struct ast_data *root, const char *childname, 00529 struct in_addr addr); 00530 00531 /*! 00532 * \brief Add a ptr node type. 00533 * \param[in] root The root of the ast_data to insert into. 00534 * \param[in] childname The name of the child element to be added. 00535 * \param[in] ptr The pointer value to add. 00536 * \retval NULL on error (memory exhaustion only). 00537 * \retval non-NULL a newly allocated node. 00538 */ 00539 struct ast_data *ast_data_add_ptr(struct ast_data *root, const char *childname, 00540 void *ptr); 00541 00542 /*! 00543 * \brief Add a password node type. 00544 * \param[in] root The root of the ast_data to insert into. 00545 * \param[in] childname The name of the child element to be added. 00546 * \param[in] string The value for the new node. 00547 * \retval NULL on error (memory exhaustion only). 00548 * \retval non-NULL a newly allocated node. 00549 */ 00550 struct ast_data *ast_data_add_password(struct ast_data *root, const char *childname, 00551 const char *string); 00552 00553 /*! 00554 * \brief Add a timestamp node type. 00555 * \param[in] root The root of the ast_data to insert into. 00556 * \param[in] childname The name of the child element to be added. 00557 * \param[in] timestamp The value for the new node. 00558 * \retval NULL on error (memory exhaustion only). 00559 * \retval non-NULL a newly allocated node. 00560 */ 00561 struct ast_data *ast_data_add_timestamp(struct ast_data *root, const char *childname, 00562 unsigned int timestamp); 00563 00564 /*! 00565 * \brief Add a seconds node type. 00566 * \param[in] root The root of the ast_data to insert into. 00567 * \param[in] childname The name of the child element to be added. 00568 * \param[in] seconds The value for the new node. 00569 * \retval NULL on error (memory exhaustion only). 00570 * \retval non-NULL a newly allocated node. 00571 */ 00572 struct ast_data *ast_data_add_seconds(struct ast_data *root, const char *childname, 00573 unsigned int seconds); 00574 00575 /*! 00576 * \brief Add a milliseconds node type. 00577 * \param[in] root The root of the ast_data to insert into. 00578 * \param[in] childname The name of the child element to be added. 00579 * \param[in] milliseconds The value for the new node. 00580 * \retval NULL on error (memory exhaustion only). 00581 * \retval non-NULL a newly allocated node. 00582 */ 00583 struct ast_data *ast_data_add_milliseconds(struct ast_data *root, const char *childname, 00584 unsigned int milliseconds); 00585 00586 /*! 00587 * \brief Add a string node type. 00588 * \param[in] root The root of the ast_data to insert into. 00589 * \param[in] childname The name of the child element to be added. 00590 * \param[in] string The value for the new node. 00591 * \retval NULL on error (memory exhaustion only). 00592 * \retval non-NULL a newly allocated node. 00593 */ 00594 struct ast_data *ast_data_add_str(struct ast_data *root, const char *childname, 00595 const char *string); 00596 00597 /*! 00598 * \brief Add a boolean node type. 00599 * \param[in] root The root of the ast_data to insert into. 00600 * \param[in] childname The name of the child element to be added. 00601 * \param[in] boolean The value for the new node. 00602 * \retval NULL on error (memory exhaustion only). 00603 * \retval non-NULL a newly allocated node. 00604 */ 00605 struct ast_data *ast_data_add_bool(struct ast_data *root, const char *childname, 00606 unsigned int boolean); 00607 00608 /*! 00609 * \brief Add a complete structure to a node. 00610 * \param[in] root Where to add the structure. 00611 * \param[in] mapping The structure mapping array. 00612 * \param[in] mapping_len The lenght of the mapping array. 00613 * \param[in] structure The structure pointer. 00614 * \retval 0 on success. 00615 * \retval 1 on error. 00616 */ 00617 int __ast_data_add_structure(struct ast_data *root, 00618 const struct ast_data_mapping_structure *mapping, 00619 size_t mapping_len, void *structure); 00620 #define ast_data_add_structure(structure_name, root, structure) \ 00621 __ast_data_add_structure(root, __data_mapping_structure_##structure_name, \ 00622 ARRAY_LEN(__data_mapping_structure_##structure_name), structure) 00623 00624 /*! 00625 * \brief Remove a node that was added using ast_data_add_ 00626 * \param[in] root The root node of the node to be removed. 00627 * \param[in] child The node pointer to remove. 00628 */ 00629 void ast_data_remove_node(struct ast_data *root, struct ast_data *child); 00630 00631 /*! 00632 * \brief Initialize an iterator. 00633 * \param[in] tree The returned tree by a call to ast_data_get. 00634 * \param[in] elements Which elements to iterate through. 00635 * \retval NULL on error. 00636 * \retval non-NULL A dinamically allocated iterator structure. 00637 */ 00638 struct ast_data_iterator *ast_data_iterator_init(struct ast_data *tree, 00639 const char *elements); 00640 00641 /*! 00642 * \brief Release (stop using) an iterator. 00643 * \param[in] iterator The iterator created by ast_data_iterator_start. 00644 * \see ast_data_iterator_start 00645 */ 00646 void ast_data_iterator_end(struct ast_data_iterator *iterator); 00647 00648 /*! 00649 * \brief Get the next node of the tree. 00650 * \param[in] iterator The iterator structure returned by ast_data_iterator_start. 00651 * \retval NULL when no more nodes to return. 00652 * \retval non-NULL A node of the ast_data tree. 00653 * \see ast_data_iterator_start, ast_data_iterator_stop 00654 */ 00655 struct ast_data *ast_data_iterator_next(struct ast_data_iterator *iterator); 00656 00657 /*! 00658 * \brief Retrieve a value from a node in the tree. 00659 * \param[in] tree The structure returned by a call to ast_data_get. 00660 * \param[in] path The path to the node. 00661 * \param[out] content The node content. 00662 * \retval 0 on success. 00663 * \retval <0 on error. 00664 */ 00665 int ast_data_retrieve(struct ast_data *tree, const char *path, struct ast_data_retrieve *content); 00666 00667 /*! 00668 * \brief Retrieve the integer value of a node. 00669 * \param[in] tree The tree from where to get the value. 00670 * \param[in] path The node name or path. 00671 * \returns The value of the node. 00672 */ 00673 static inline int ast_data_retrieve_int(struct ast_data *tree, const char *path) 00674 { 00675 struct ast_data_retrieve ret; 00676 00677 ast_data_retrieve(tree, path, &ret); 00678 00679 return ret.value.AST_DATA_INTEGER; 00680 } 00681 00682 /*! 00683 * \brief Retrieve the character value of a node. 00684 * \param[in] tree The tree from where to get the value. 00685 * \param[in] path The node name or path. 00686 * \returns The value of the node. 00687 */ 00688 static inline char ast_data_retrieve_char(struct ast_data *tree, const char *path) 00689 { 00690 struct ast_data_retrieve ret; 00691 00692 ast_data_retrieve(tree, path, &ret); 00693 00694 return ret.value.AST_DATA_CHARACTER; 00695 } 00696 00697 /*! 00698 * \brief Retrieve the boolean value of a node. 00699 * \param[in] tree The tree from where to get the value. 00700 * \param[in] path The node name or path. 00701 * \returns The value of the node. 00702 */ 00703 static inline unsigned int ast_data_retrieve_bool(struct ast_data *tree, const char *path) 00704 { 00705 struct ast_data_retrieve ret; 00706 00707 ast_data_retrieve(tree, path, &ret); 00708 00709 return ret.value.AST_DATA_BOOLEAN; 00710 } 00711 00712 /*! 00713 * \brief Retrieve the unsigned integer value of a node. 00714 * \param[in] tree The tree from where to get the value. 00715 * \param[in] path The node name or path. 00716 * \returns The value of the node. 00717 */ 00718 static inline unsigned int ast_data_retrieve_uint(struct ast_data *tree, const char *path) 00719 { 00720 struct ast_data_retrieve ret; 00721 00722 ast_data_retrieve(tree, path, &ret); 00723 00724 return ret.value.AST_DATA_UNSIGNED_INTEGER; 00725 } 00726 00727 /*! 00728 * \brief Retrieve the password value of a node. 00729 * \param[in] tree The tree from where to get the value. 00730 * \param[in] path The node name or path. 00731 * \returns The value of the node. 00732 */ 00733 static inline const char *ast_data_retrieve_password(struct ast_data *tree, const char *path) 00734 { 00735 struct ast_data_retrieve ret; 00736 00737 ast_data_retrieve(tree, path, &ret); 00738 00739 return ret.value.AST_DATA_PASSWORD; 00740 } 00741 00742 /*! 00743 * \brief Retrieve the string value of a node. 00744 * \param[in] tree The tree from where to get the value. 00745 * \param[in] path The node name or path. 00746 * \returns The value of the node. 00747 */ 00748 static inline const char *ast_data_retrieve_string(struct ast_data *tree, const char *path) 00749 { 00750 struct ast_data_retrieve ret; 00751 00752 ast_data_retrieve(tree, path, &ret); 00753 00754 return ret.value.AST_DATA_STRING; 00755 } 00756 00757 /*! 00758 * \brief Retrieve the ptr value of a node. 00759 * \param[in] tree The tree from where to get the value. 00760 * \param[in] path The node name or path. 00761 * \returns The value of the node. 00762 */ 00763 static inline void *ast_data_retrieve_ptr(struct ast_data *tree, const char *path) 00764 { 00765 struct ast_data_retrieve ret; 00766 00767 ast_data_retrieve(tree, path, &ret); 00768 00769 return ret.value.AST_DATA_POINTER; 00770 } 00771 00772 /*! 00773 * \brief Retrieve the double value of a node. 00774 * \param[in] tree The tree from where to get the value. 00775 * \param[in] path The node name or path. 00776 * \returns The value of the node. 00777 */ 00778 static inline double ast_data_retrieve_dbl(struct ast_data *tree, const char *path) 00779 { 00780 struct ast_data_retrieve ret; 00781 00782 ast_data_retrieve(tree, path, &ret); 00783 00784 return ret.value.AST_DATA_DOUBLE; 00785 } 00786 00787 /*! 00788 * \brief Retrieve the ipv4 address value of a node. 00789 * \param[in] tree The tree from where to get the value. 00790 * \param[in] path The node name or path. 00791 * \returns The value of the node. 00792 */ 00793 static inline struct in_addr ast_data_retrieve_ipaddr(struct ast_data *tree, const char *path) 00794 { 00795 struct ast_data_retrieve ret; 00796 00797 ast_data_retrieve(tree, path, &ret); 00798 00799 return ret.value.AST_DATA_IPADDR; 00800 } 00801 00802 /*! 00803 * \brief Add the list of codecs in the root node based on the capability parameter. 00804 * \param[in] root The astdata root node where to add the codecs node. 00805 * \param[in] node_name The name of the node where we are going to add the list of 00806 * codecs. 00807 * \param[in] capability The codecs allowed. 00808 * \return < 0 on error. 00809 * \return 0 on success. 00810 */ 00811 int ast_data_add_codecs(struct ast_data *root, const char *node_name, format_t capability); 00812 00813 #if defined(__cplusplus) || defined(c_plusplus) 00814 } 00815 #endif 00816 00817 #endif /* ASTERISK_DATA_H */