From a753e8878b8a30122fd5f0af45bad242de0cb303 Mon Sep 17 00:00:00 2001 From: "Eliel C. Sardanons" Date: Thu, 22 Apr 2010 18:07:02 +0000 Subject: Asterisk data retrieval API. This module implements an abstraction for retrieving and exporting asterisk data. Developed by: Brett Bryant Eliel C. Sardanons (LU1ALY) For the Google Summer of code 2009 Project. Documentation can be found in doxygen format and inside the header include/asterisk/data.h Review: https://reviewboard.asterisk.org/r/275/ git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@258517 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/_private.h | 1 + include/asterisk/channel.h | 21 ++ include/asterisk/data.h | 788 ++++++++++++++++++++++++++++++++++++++++++++ include/asterisk/doxyref.h | 1 + include/asterisk/xml.h | 176 +++++++--- 5 files changed, 941 insertions(+), 46 deletions(-) create mode 100644 include/asterisk/data.h (limited to 'include/asterisk') diff --git a/include/asterisk/_private.h b/include/asterisk/_private.h index cb1b61810..435ee0985 100644 --- a/include/asterisk/_private.h +++ b/include/asterisk/_private.h @@ -35,6 +35,7 @@ int astobj2_init(void); /*!< Provided by astobj2.c */ int ast_file_init(void); /*!< Provided by file.c */ int ast_features_init(void); /*!< Provided by features.c */ void ast_autoservice_init(void); /*!< Provided by autoservice.c */ +int ast_data_init(void); /*!< Provided by data.c */ int ast_http_init(void); /*!< Provided by http.c */ int ast_http_reload(void); /*!< Provided by http.c */ int ast_tps_init(void); /*!< Provided by taskprocessor.c */ diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h index 119dc42e8..b2cb8e5eb 100644 --- a/include/asterisk/channel.h +++ b/include/asterisk/channel.h @@ -148,6 +148,7 @@ extern "C" { #include "asterisk/linkedlists.h" #include "asterisk/stringfields.h" #include "asterisk/datastore.h" +#include "asterisk/data.h" #include "asterisk/channelstate.h" #include "asterisk/ccss.h" @@ -2758,6 +2759,26 @@ void ast_channel_queue_redirecting_update(struct ast_channel *chan, const struct */ int ast_channel_connected_line_macro(struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const void *connected_info, int caller, int frame); +/*! + * \brief Insert into an astdata tree, the channel structure. + * \param[in] tree The ast data tree. + * \param[in] chan The channel structure to add to tree. + * \retval <0 on error. + * \retval 0 on success. + */ +int ast_channel_data_add_structure(struct ast_data *tree, struct ast_channel *chan); + +/*! + * \brief Compare to channel structures using the data api. + * \param[in] tree The search tree generated by the data api. + * \param[in] chan The channel to compare. + * \param[in] structure_name The name of the node of the channel structure. + * \retval 0 The structure matches. + * \retval 1 The structure doesn't matches. + */ +int ast_channel_data_cmp_structure(const struct ast_data_search *tree, struct ast_channel *chan, + const char *structure_name); + #include "asterisk/ccss.h" /*! diff --git a/include/asterisk/data.h b/include/asterisk/data.h new file mode 100644 index 000000000..cc92a0c10 --- /dev/null +++ b/include/asterisk/data.h @@ -0,0 +1,788 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2009, Eliel C. Sardanons (LU1ALY) + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! + * \file + * \brief Data retrieval API. + * \author Brett Bryant + * \author Eliel C. Sardanons (LU1ALY) + * \arg \ref AstDataRetrieval + */ + +#ifndef ASTERISK_DATA_H +#define ASTERISK_DATA_H + +/*! + * \page AstDataRetrieval The Asterisk DATA retrieval API. + * + * This module implements an abstraction for retrieving asterisk data and + * export it. + * + * \section USAGE + * + * \subsection Provider + * + * \b Register + * + * To register a callback use: + * + * \code + * static const struct ast_data_handler callback_handler = { + * .get = callback_handler_get_function, + * }; + * + * ast_data_register("/node/path", &callback_handler); + * \endcode + * + * If you instead want to register multiple nodes at once use: + * \code + * static const struct ast_data_handler handler_struct1 = { + * .get = handler_callback_read, + * }; + * ... other handlers ... + * + * static const struct ast_data_entry list_providers[] = { + * AST_DATA_ENTRY("/path1/node1", &handler_struct1), + * AST_DATA_ENTRY("/path2/node2", &handler_struct2), + * AST_DATA_ENTRY("/path3/node3", &handler_struct3), + * }; + * + * ... + * + * ast_data_register_multiple(list_providers, ARRAY_LEN(list_providers)); + * \endcode + * + * \b Unregister + * + * To unregister a callback function already registered you can just call: + * + * \code + * ast_data_unregister(NULL); + * \endcode + * And every node registered by the current module (file) will be unregistered. + * If you want to unregister a specific node use: + * + * \code + * ast_data_unregister("/node/path"); + * \endcode + * + * \b Implementation + * + * A simple callback function implementation: + * + * \code + * #include + * + * struct test_structure { + * int a; + * double b; + * }; + * + * DATA_EXPORT_TEST_STRUCTURE(MEMBER) \ + * MEMBER(test_structure, a, AST_DATA_INTEGER) \ + * MEMBER(test_structure, b, AST_DATA_DOUBLE) + * + * AST_DATA_STRUCTURE(test_structure, DATA_EXPORT_TEST_STRUCTURE) + * + * static int my_callback_function(struct ast_data_search *search, + * struct ast_data *root_node) + * { + * struct ast_data *internal_node; + * struct test_structure ts = { + * .a = 10, + * .b = 20 + * }; + * + * if (ast_data_search_cmp_structure(search, test_structure, "test_node")) { + * return 0; + * } + * + * internal_node = ast_data_add_node(root_node, "test_node"); + * if (!internal_node) { + * return -1; + * } + * + * ast_data_add_structure(test_structure, internal_node, ts); + * + * return 0; + * } + * + * \endcode + * + * \subsection Get + * + * \b Getting \b the \b tree + * + * To get the tree you need to create a query, a query is based on three parameters + * a \b path to the provider, a \b search condition and a \b filter condition. + * \code + * struct ast_data *result; + * struct ast_data_query query = { + * .path = "/asterisk/application/app_queue/queues", + * .search = "/queues/queue/name=queue1", + * .filter = "/queues/queue/name|wrapuptime|members/member/interface" + * }; + * + * result = ast_data_get(&query); + * \endcode + * + * After using it you need to release the allocated memory of the returned tree: + * \code + * ast_data_free(result); + * \endcode + * + * \b Iterate + * + * To retrieve nodes from the tree, it is possible to iterate through the returned + * nodes of the tree using: + * \code + * struct ast_data_iterator *i; + * struct ast_data *internal_node; + * + * i = ast_data_iterator_init(result_tree, "path/node_name"); + * while ((internal_node = ast_data_iterator_next(i))) { + * ... do something with node ... + * } + * ast_data_iterator_end(i); + * \endcode + * node_name is the name of the nodes to retrieve and path is the path to the internal + * nodes to retrieve (if needed). + * + * \b Retrieving + * + * After getting the node you where searching for, you will need to retrieve its value, + * to do that you may use one of the ast_data_retrieve_##type functions: + * \code + * int a = ast_data_retrieve_int(tree, "path/to/the/node"); + * double b = ast_data_retrieve_dbl(tree, "path/to/the/node"); + * unsigned int c = ast_data_retrieve_bool(tree, "path/to/the/node"); + * char *d = ast_data_retrieve_string(tree, "path/to/the/node"); + * struct sockaddr_in e = ast_data_retrieve_ipaddr(tree, "path/to/the/node"); + * unsigned int f = ast_data_retrieve_uint(tree, "path/to/the/node"); + * void *g = ast_data_retrieve_ptr(tree, "path/to/the/node"); + * \endcode + * + */ + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +/*! \brief The data type of the data node. */ +enum ast_data_type { + AST_DATA_CONTAINER, + AST_DATA_INTEGER, + AST_DATA_UNSIGNED_INTEGER, + AST_DATA_DOUBLE, + AST_DATA_BOOLEAN, + AST_DATA_STRING, + AST_DATA_IPADDR, + AST_DATA_POINTER +}; + +/*! \brief The Data API structures version. */ +#define AST_DATA_HANDLER_VERSION 1 +#define AST_DATA_QUERY_VERSION 1 + +/*! \brief opaque definition of an ast_data handler, a tree node. */ +struct ast_data; + +/*! \brief opaque definition of an ast_data_iterator handler. */ +struct ast_data_iterator; + +/*! \brief opaque definition of an ast_data_search structure. */ +struct ast_data_search; + +/*! \brief structure retrieved from a node, with the nodes content. */ +struct ast_data_retrieve { + /*! \brief The type of the node retrieved. */ + enum ast_data_type type; + + union { + char *AST_DATA_STRING; + int AST_DATA_INTEGER; + double AST_DATA_DOUBLE; + unsigned int AST_DATA_UNSIGNED_INTEGER; + unsigned int AST_DATA_BOOLEAN; + void *AST_DATA_POINTER; + struct in_addr AST_DATA_IPADDR; + void *AST_DATA_CONTAINER; + } value; +}; + +/*! + * \brief The get callback definition. + */ +typedef int (*ast_data_get_cb)(const struct ast_data_search *search, + struct ast_data *root); + +/*! \brief The structure of the node handler. */ +struct ast_data_handler { + /*! \brief Structure version. */ + uint32_t version; + /*! \brief Data get callback implementation. */ + ast_data_get_cb get; +}; + +/*! \brief This entries are for multiple registers. */ +struct ast_data_entry { + /*! \brief Path of the node to register. */ + const char *path; + /*! \brief Data handler structure. */ + const struct ast_data_handler *handler; +}; + +#define AST_DATA_ENTRY(__path, __handler) { .path = __path, .handler = __handler } + +/*! \brief A query to the data API is specified in this structure. */ +struct ast_data_query { + /*! \brief Data query version. */ + uint32_t version; + /*! \brief Path to the node to retrieve. */ + char *path; + /*! \brief Filter string, return the internal nodes specified here. + * Setting it to NULL will return every internal node. */ + char *filter; + /*! \brief Search condition. */ + char *search; +}; + +/*! \brief Map the members of a structure. */ +struct ast_data_mapping_structure { + /*! \brief structure member name. */ + const char *name; + /*! \brief structure member type. */ + enum ast_data_type type; + /*! \brief member getter. */ + union { + char *(*AST_DATA_STRING)(void *ptr); + int (*AST_DATA_INTEGER)(void *ptr); + double (*AST_DATA_DOUBLE)(void *ptr); + unsigned int (*AST_DATA_UNSIGNED_INTEGER)(void *ptr); + unsigned int (*AST_DATA_BOOLEAN)(void *ptr); + void *(*AST_DATA_POINTER)(void *ptr); + struct in_addr (*AST_DATA_IPADDR)(void *ptr); + void *(*AST_DATA_CONTAINER)(void *ptr); + } get; +}; + +/* Generate the structure and the functions to access the members of a structure. */ +#define AST_DATA_STRUCTURE(__struct, __name) \ + __name(__AST_DATA_MAPPING_FUNCTION); \ + static const struct ast_data_mapping_structure __data_mapping_structure_##__struct[] = { \ + __name(__AST_DATA_MAPPING_STRUCTURE) \ + } + +/* Generate the structure to access the members and setup the pointer of the getter. */ +#define __AST_DATA_MAPPING_STRUCTURE(__structure, __member, __type) \ + { .name = #__member, .get.__type = data_mapping_structure_get_##__structure##__member, \ + .type = __type }, + +/* based on the data type, specifify the type of return value for the getter function. */ +#define __AST_DATA_MAPPING_FUNCTION_AST_DATA_STRING(__structure, __member) \ + __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_STRING, char *) +#define __AST_DATA_MAPPING_FUNCTION_AST_DATA_INTEGER(__structure, __member) \ + __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_INTEGER, int) +#define __AST_DATA_MAPPING_FUNCTION_AST_DATA_UNSIGNED_INTEGER(__structure, __member) \ + __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_UNSIGNED_INTEGER, unsigned int) +#define __AST_DATA_MAPPING_FUNCTION_AST_DATA_BOOLEAN(__structure, __member) \ + __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_BOOLEAN, unsigned int) +#define __AST_DATA_MAPPING_FUNCTION_AST_DATA_POINTER(__structure, __member) \ + __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_POINTER, void *) +#define __AST_DATA_MAPPING_FUNCTION_AST_DATA_IPADDR(__structure, __member) \ + __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_IPADDR, struct in_addr) +#define __AST_DATA_MAPPING_FUNCTION_AST_DATA_DOUBLE(__structure, __member) \ + __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_DBL, double) +#define __AST_DATA_MAPPING_FUNCTION_AST_DATA_CONTAINER(__structure, __member) \ + __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, AST_DATA_CONTAINER, void *) + +#define __AST_DATA_MAPPING_FUNCTION(__structure, __member, __type) \ + __AST_DATA_MAPPING_FUNCTION_##__type(__structure, __member) + +/* Create the function to retrieve a member of the structure. */ +#define __AST_DATA_MAPPING_FUNCTION_TYPE(__structure, __member, __type, __real_type) \ + static __real_type data_mapping_structure_get_##__structure##__member(void *ptr) { \ + struct __structure *struct_##__member = (struct __structure *) ptr; \ + return (__real_type) struct_##__member->__member; \ + } + +/*! + * \brief Register a data provider. + * \param[in] path The path of the node to register. + * \param[in] handler The structure defining this node handler. + * \param[in] registrar Who is registering this node. + * \param[in] mod The module registering this handler. + * \see ast_data_unregister + * \retval <0 on error. + * \retval 0 on success. + * \see __ast_data_unregister, __ast_data_register_multiple + */ +int __ast_data_register(const char *path, const struct ast_data_handler *handler, + const char *registrar, struct ast_module *mod); +#define ast_data_register(path, handler) __ast_data_register(path, handler, __FILE__, ast_module_info->self) +#define ast_data_register_core(path, handler) __ast_data_register(path, handler, __FILE__, NULL) + +/*! + * \brief Register multiple data providers at once. + * \param[in] data_entries An array of data_entries structures. + * \param[in] entries The number of entries in the data_entries array. + * \param[in] registrar Who is registering this nodes. + * \param[in] mod The module registering this handlers. + * \retval <0 on error (none of the nodes are being registered on error). + * \retval 0 on success. + * \see __ast_data_register, __ast_data_unregister + */ +int __ast_data_register_multiple(const struct ast_data_entry *data_entries, + size_t entries, const char *registrar, struct ast_module *mod); +#define ast_data_register_multiple(data_entries, entries) \ + __ast_data_register_multiple(data_entries, entries, __FILE__, ast_module_info->self) +#define ast_data_register_multiple_core(data_entries, entries) \ + __ast_data_register_multiple(data_entries, entries, __FILE__, NULL) + +/*! + * \brief Unregister a data provider. + * \param[in] path Which node to unregister, if path is NULL unregister every node + * registered by the passed 'registrar'. + * \param[in] registrar Who is trying to unregister this node, only the owner (the + * one who registered the node) will be able to unregister it. + * \see ast_data_register + * \retval <0 on error. + * \retval 0 on success. + * \see __ast_data_register, __ast_data_register_multiple + */ +int __ast_data_unregister(const char *path, const char *registrar); +#define ast_data_unregister(path) __ast_data_unregister(path, __FILE__) + +/*! + * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the + * current string value. + * .search = "somename=somestring" + * name = "somename" + * value is the current value of something and will be evaluated against "somestring". + * \param[in] root The root node pointer of the search tree. + * \param[in] name The name of the specific. + * \param[in] value The value to compare. + * \returns The strcmp return value. + */ +int ast_data_search_cmp_string(const struct ast_data_search *root, const char *name, char *value); + +/*! + * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the + * current pointer address value. + * .search = "something=0x32323232" + * name = "something" + * value is the current value of something and will be evaluated against "0x32323232". + * \param[in] root The root node pointer of the search tree. + * \param[in] name The name of the specific. + * \param[in] ptr The pointer address to compare. + * \returns The (value - current_value) result. + */ +int ast_data_search_cmp_ptr(const struct ast_data_search *root, const char *name, + void *ptr); + +/*! + * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the + * current ipv4 address value. + * .search = "something=192.168.2.2" + * name = "something" + * value is the current value of something and will be evaluated against "192.168.2.2". + * \param[in] root The root node pointer of the search tree. + * \param[in] name The name of the specific. + * \param[in] addr The ipv4 address value to compare. + * \returns The (value - current_value) result. + */ +int ast_data_search_cmp_ipaddr(const struct ast_data_search *root, const char *name, + struct in_addr addr); + +/*! + * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the + * current double value. + * .search = "something=222" + * name = "something" + * value is the current value of something and will be evaluated against "222". + * \param[in] root The root node pointer of the search tree. + * \param[in] name The name of the specific. + * \param[in] value The double value to compare. + * \returns The (value - current_value) result. + */ +int ast_data_search_cmp_dbl(const struct ast_data_search *root, const char *name, + double value); + +/*! + * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the + * current boolean value. + * .search = "something=true" + * name = "something" + * value is the current value of something and will be evaluated against "true". + * \param[in] root The root node pointer of the search tree. + * \param[in] name The name of the specific. + * \param[in] value The boolean value to compare. + * \returns The (value - current_value) result. + */ +int ast_data_search_cmp_bool(const struct ast_data_search *root, const char *name, + unsigned int value); + +/*! + * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the + * current unsigned integer value. + * .search = "something=10" + * name = "something" + * value is the current value of something and will be evaluated against "10". + * \param[in] root The root node pointer of the search tree. + * \param[in] name The name of the specific. + * \param[in] value The unsigned value to compare. + * \returns The strcmp return value. + */ +int ast_data_search_cmp_uint(const struct ast_data_search *root, const char *name, + unsigned int value); + +/*! + * \brief Based on a search tree, evaluate the specified 'name' inside the tree with the + * current signed integer value. + * .search = "something=10" + * name = "something" + * value is the current value of something and will be evaluated against "10". + * \param[in] root The root node pointer of the search tree. + * \param[in] name The name of the specific. + * \param[in] value The value to compare. + * \returns The strcmp return value. + */ +int ast_data_search_cmp_int(const struct ast_data_search *root, const char *name, int value); + +/*! + * \brief Based on a search tree, evaluate every member of a structure against it. + * \param[in] search The search tree. + * \param[in] mapping The structure mapping. + * \param[in] mapping_len The lenght of the structure mapping. + * \param[in] structure The structure pointer. + * \param[in] structure_name The name of the structure to compare. + * \retval 0 If the structure matches. + * \retval 1 If the structure doesn't match. + */ +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); +#define ast_data_search_cmp_structure(search, structure_name, structure, structure_name_cmp) \ + __ast_data_search_cmp_structure(search, __data_mapping_structure_##structure_name, \ + ARRAY_LEN(__data_mapping_structure_##structure_name), structure, structure_name_cmp) + +/*! + * \brief Check if there is a compare condition inside the search tree with the + * passed 'compare_condition' node names. + * \param[in] search The search tree. + * \param[in] compare_condition The path of the compare condition. + * \retval 0 There is no compare condition. + * \retval 1 There is a compare condition. + */ +int ast_data_search_has_condition(const struct ast_data_search *search, + const char *compare_condition); + +/*! + * \brief Retrieve a subtree from the asterisk data API. + * \param[in] query The query structure specifying what nodes to retrieve. + * \retval NULL on error. + * \retval non-NULL The dynamically allocated requested sub-tree (it needs to be + * released using ast_data_free. + * \see ast_data_free, ast_data_get_xml + */ +struct ast_data *ast_data_get(const struct ast_data_query *query); + +/*! + * \brief Retrieve a subtree from the asterisk data API in XML format.. + * \param[in] query The query structure specifying what nodes to retrieve. + * \retval NULL on error. + * \retval non-NULL The dynamically allocated requested sub-tree (it needs to be + * released using ast_data_free. + * \see ast_data_free, ast_data_get + */ +struct ast_xml_doc *ast_data_get_xml(const struct ast_data_query *query); + +/*! + * \brief Release the allocated memory of a tree. + * \param[in] root The sub-tree pointer returned by a call to ast_data_get. + * \see ast_data_get + */ +void ast_data_free(struct ast_data *root); + +/*! + * \brief Get a node type. + * \param[in] res A pointer to the ast_data result set. + * \param[in] path A path to the node to get the type. + * \return The type of the requested node type. + */ +enum ast_data_type ast_data_retrieve_type(struct ast_data *res, const char *path); + +/*! + * \brief Get the node name. + * \param[in] node The node pointer. + * \returns The node name. + */ +char *ast_data_retrieve_name(struct ast_data *node); + +/*! + * \brief Add a container child. + * \param[in] root The root of the ast_data to insert into. + * \param[in] childname The name of the child element to be added. + * \retval NULL on error (memory exhaustion only). + * \retval non-NULL a newly allocated node. + */ +struct ast_data *ast_data_add_node(struct ast_data *root, const char *childname); + +/*! + * \brief Add an integer node type. + * \param[in] root The root of the ast_data to insert into. + * \param[in] childname The name of the child element to be added. + * \param[in] value The value for the new node. + * \retval NULL on error (memory exhaustion only). + * \retval non-NULL a newly allocated node. + */ +struct ast_data *ast_data_add_int(struct ast_data *root, const char *childname, + int value); + +/*! + * \brief Add an unsigned integer node type. + * \param[in] root The root of the ast_data to insert into. + * \param[in] childname The name of the child element to be added. + * \param[in] value The value for the new node. + * \retval NULL on error (memory exhaustion only). + * \retval non-NULL a newly allocated node. + */ +struct ast_data *ast_data_add_uint(struct ast_data *root, const char *childname, + unsigned int value); + +/*! + * \brief Add a floating point node type. + * \param[in] root The root of the ast_data to insert into. + * \param[in] childname The name of the child element to be added. + * \param[in] dbl The value for the new node. + * \retval NULL on error (memory exhaustion only). + * \retval non-NULL a newly allocated node. + */ +struct ast_data *ast_data_add_dbl(struct ast_data *root, const char *childname, + double dbl); +/*! + * \brief Add a ipv4 address type. + * \param[in] root The root of the ast_data to insert into. + * \param[in] childname The name of the child element to be added. + * \param[in] addr The ipv4 address value. + * \retval NULL on error (memory exhaustion only). + * \retval non-NULL a newly allocated node. + */ +struct ast_data *ast_data_add_ipaddr(struct ast_data *root, const char *childname, + struct in_addr addr); + +/*! + * \brief Add a ptr node type. + * \param[in] root The root of the ast_data to insert into. + * \param[in] childname The name of the child element to be added. + * \param[in] ptr The pointer value to add. + * \retval NULL on error (memory exhaustion only). + * \retval non-NULL a newly allocated node. + */ +struct ast_data *ast_data_add_ptr(struct ast_data *root, const char *childname, + void *ptr); + +/*! + * \brief Add a string node type. + * \param[in] root The root of the ast_data to insert into. + * \param[in] childname The name of the child element to be added. + * \param[in] value The value for the new node. + * \retval NULL on error (memory exhaustion only). + * \retval non-NULL a newly allocated node. + */ +struct ast_data *ast_data_add_str(struct ast_data *root, const char *childname, + const char *string); + +/*! + * \brief Add a boolean node type. + * \param[in] root The root of the ast_data to insert into. + * \param[in] childname The name of the child element to be added. + * \param[in] value The value for the new node. + * \retval NULL on error (memory exhaustion only). + * \retval non-NULL a newly allocated node. + */ +struct ast_data *ast_data_add_bool(struct ast_data *root, const char *childname, + unsigned int boolean); + +/*! + * \brief Add a complete structure to a node. + * \param[in] root Where to add the structure. + * \param[in] mapping The structure mapping array. + * \param[in] mapping_len The lenght of the mapping array. + * \param[in] structure The structure pointer. + * \retval 0 on success. + * \retval 1 on error. + */ +int __ast_data_add_structure(struct ast_data *root, + const struct ast_data_mapping_structure *mapping, + size_t mapping_len, void *structure); +#define ast_data_add_structure(structure_name, root, structure) \ + __ast_data_add_structure(root, __data_mapping_structure_##structure_name, \ + ARRAY_LEN(__data_mapping_structure_##structure_name), structure) + +/*! + * \brief Remove a node that was added using ast_data_add_ + * \param[in] root The root node of the node to be removed. + * \param[in] child The node pointer to remove. + */ +void ast_data_remove_node(struct ast_data *root, struct ast_data *child); + +/*! + * \brief Initialize an iterator. + * \param[in] tree The returned tree by a call to ast_data_get. + * \param[in] elements Which elements to iterate through. + * \retval NULL on error. + * \retval non-NULL A dinamically allocated iterator structure. + */ +struct ast_data_iterator *ast_data_iterator_init(struct ast_data *tree, + const char *elements); + +/*! + * \brief Release (stop using) an iterator. + * \param[in] iterator The iterator created by ast_data_iterator_start. + * \see ast_data_iterator_start + */ +void ast_data_iterator_end(struct ast_data_iterator *iterator); + +/*! + * \brief Get the next node of the tree. + * \param[in] iterator The iterator structure returned by ast_data_iterator_start. + * \retval NULL when no more nodes to return. + * \retval non-NULL A node of the ast_data tree. + * \see ast_data_iterator_start, ast_data_iterator_stop + */ +struct ast_data *ast_data_iterator_next(struct ast_data_iterator *iterator); + +/*! + * \brief Retrieve a value from a node in the tree. + * \param[in] tree The structure returned by a call to ast_data_get. + * \param[in] path The path to the node. + * \param[out] content The node content. + * \retval 0 on success. + * \retval <0 on error. + */ +int ast_data_retrieve(struct ast_data *tree, const char *path, struct ast_data_retrieve *content); + +/*! + * \brief Retrieve the integer value of a node. + * \param[in] tree The tree from where to get the value. + * \param[in] path The node name or path. + * \returns The value of the node. + */ +static inline int ast_data_retrieve_int(struct ast_data *tree, const char *path) +{ + struct ast_data_retrieve ret; + + ast_data_retrieve(tree, path, &ret); + + return ret.value.AST_DATA_INTEGER; +} + +/*! + * \brief Retrieve the boolean value of a node. + * \param[in] tree The tree from where to get the value. + * \param[in] path The node name or path. + * \returns The value of the node. + */ +static inline unsigned int ast_data_retrieve_bool(struct ast_data *tree, const char *path) +{ + struct ast_data_retrieve ret; + + ast_data_retrieve(tree, path, &ret); + + return ret.value.AST_DATA_BOOLEAN; +} + +/*! + * \brief Retrieve the unsigned integer value of a node. + * \param[in] tree The tree from where to get the value. + * \param[in] path The node name or path. + * \returns The value of the node. + */ +static inline unsigned int ast_data_retrieve_uint(struct ast_data *tree, const char *path) +{ + struct ast_data_retrieve ret; + + ast_data_retrieve(tree, path, &ret); + + return ret.value.AST_DATA_UNSIGNED_INTEGER; +} + +/*! + * \brief Retrieve the string value of a node. + * \param[in] tree The tree from where to get the value. + * \param[in] path The node name or path. + * \returns The value of the node. + */ +static inline const char *ast_data_retrieve_string(struct ast_data *tree, const char *path) +{ + struct ast_data_retrieve ret; + + ast_data_retrieve(tree, path, &ret); + + return ret.value.AST_DATA_STRING; +} + +/*! + * \brief Retrieve the ptr value of a node. + * \param[in] tree The tree from where to get the value. + * \param[in] path The node name or path. + * \returns The value of the node. + */ +static inline void *ast_data_retrieve_ptr(struct ast_data *tree, const char *path) +{ + struct ast_data_retrieve ret; + + ast_data_retrieve(tree, path, &ret); + + return ret.value.AST_DATA_POINTER; +} + +/*! + * \brief Retrieve the double value of a node. + * \param[in] tree The tree from where to get the value. + * \param[in] path The node name or path. + * \returns The value of the node. + */ +static inline double ast_data_retrieve_dbl(struct ast_data *tree, const char *path) +{ + struct ast_data_retrieve ret; + + ast_data_retrieve(tree, path, &ret); + + return ret.value.AST_DATA_DOUBLE; +} + +/*! + * \brief Retrieve the ipv4 address value of a node. + * \param[in] tree The tree from where to get the value. + * \param[in] path The node name or path. + * \returns The value of the node. + */ +static inline struct in_addr ast_data_retrieve_ipaddr(struct ast_data *tree, const char *path) +{ + struct ast_data_retrieve ret; + + ast_data_retrieve(tree, path, &ret); + + return ret.value.AST_DATA_IPADDR; +} + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* ASTERISK_DATA_H */ diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index 5e24274a5..43186b252 100644 --- a/include/asterisk/doxyref.h +++ b/include/asterisk/doxyref.h @@ -90,6 +90,7 @@ * \arg \ref AstThreadStorage * \arg \ref DataStores * \arg \ref AstExtState + * \arg \ref AstDataRetrieval * * \subsection model_txt Generic Model * \verbinclude model.txt diff --git a/include/asterisk/xml.h b/include/asterisk/xml.h index 2c30986cc..836a4f386 100644 --- a/include/asterisk/xml.h +++ b/include/asterisk/xml.h @@ -18,33 +18,76 @@ #define _ASTERISK_XML_H /*! \file - * \brief Asterisk XML abstraction layer + * \brief Asterisk XML abstraction layer */ struct ast_xml_node; struct ast_xml_doc; -/*! \brief Initialize the XML library implementation. +/*! + * \brief Initialize the XML library implementation. * This function is used to setup everything needed * to start working with the xml implementation. - * \retval 0 On success. - * \retval 1 On error. + * \retval 0 On success. + * \retval 1 On error. */ int ast_xml_init(void); -/*! \brief Cleanup library allocated global data. - * \retval 0 On success. - * \retval 1 On error. +/*! + * \brief Cleanup library allocated global data. + * \retval 0 On success. + * \retval 1 On error. */ int ast_xml_finish(void); -/*! \brief Open an XML document. - * \param filename Document path. - * \retval NULL on error. - * \retval The ast_xml_doc reference to the open document. +/*! + * \brief Open an XML document. + * \param filename Document path. + * \retval NULL on error. + * \retval The ast_xml_doc reference to the open document. */ struct ast_xml_doc *ast_xml_open(char *filename); +/*! + * \brief Create a XML document. + * \retval NULL on error. + * \retval non-NULL The allocated document structure. + */ +struct ast_xml_doc *ast_xml_new(void); + +/*! + * \brief Create a XML node. + * \param name The name of the node to be created. + * \retval NULL on error. + * \retval non-NULL The allocated node structe. + */ +struct ast_xml_node *ast_xml_new_node(const char *name); + +/*! + * \brief Add a child node inside a passed parent node. + * \param parent The pointer of the parent node. + * \param child_name The name of the child node to add. + * \retval NULL on error. + * \retval non-NULL The created child node pointer. + */ +struct ast_xml_node *ast_xml_new_child(struct ast_xml_node *parent, const char *child_name); + +/*! + * \brief Add a child node, to a specified parent node. + * \param parent Where to add the child node. + * \param child The child node to add. + * \retval NULL on error. + * \retval non-NULL The add child node on success. + */ +struct ast_xml_node *ast_xml_add_child(struct ast_xml_node *parent, struct ast_xml_node *child); + +/*! + * \brief Close an already open document and free the used + * structure. + * \retval doc The document reference. + */ +void ast_xml_close(struct ast_xml_doc *doc); + /*! \brief Open an XML document that resides in memory. * \param buffer The address where the document is stored * \size The number of bytes in the document @@ -53,76 +96,117 @@ struct ast_xml_doc *ast_xml_open(char *filename); */ struct ast_xml_doc *ast_xml_read_memory(char *buffer, size_t size); -/*! \brief Close an already open document and free the used - * structure. - * \retval doc The document reference. +/*! + * \brief Specify the root node of a XML document. + * \param doc The document pointer. + * \param node A pointer to the node we want to set as root node. */ -void ast_xml_close(struct ast_xml_doc *doc); +void ast_xml_set_root(struct ast_xml_doc *doc, struct ast_xml_node *node); -/*! \brief Get the document root node. - * \param doc Document reference - * \retval NULL on error - * \retval The root node on success. +/*! + * \brief Get the document root node. + * \param doc Document reference + * \retval NULL on error + * \retval The root node on success. */ struct ast_xml_node *ast_xml_get_root(struct ast_xml_doc *doc); -/*! \brief Free node - * \param node Node to be released. +/*! + * \brief Free node + * \param node Node to be released. */ void ast_xml_free_node(struct ast_xml_node *node); -/*! \brief Free an attribute returned by ast_xml_get_attribute() - * \param data pointer to be freed. +/*! + * \brief Free an attribute returned by ast_xml_get_attribute() + * \param data pointer to be freed. */ void ast_xml_free_attr(const char *attribute); -/*! \brief Free a content element that was returned by ast_xml_get_text() - * \param text text to be freed. +/*! + * \brief Get the document based on a node. + * \param node A node that is part of the dom. + * \returns The dom pointer where this node resides. + */ +struct ast_xml_doc *ast_xml_get_doc(struct ast_xml_node *node); + +/*! + * \brief Free a content element that was returned by ast_xml_get_text() + * \param text text to be freed. */ void ast_xml_free_text(const char *text); -/*! \brief Get a node attribute by name - * \param node Node where to search the attribute. - * \param attrname Attribute name. - * \retval NULL on error - * \retval The attribute value on success. +/*! + * \brief Get a node attribute by name + * \param node Node where to search the attribute. + * \param attrname Attribute name. + * \retval NULL on error + * \retval The attribute value on success. */ const char *ast_xml_get_attribute(struct ast_xml_node *node, const char *attrname); -/*! \brief Find a node element by name. - * \param node This is the node starting point. - * \param name Node name to find. - * \param attrname attribute name to match (if NULL it won't be matched). - * \param attrvalue attribute value to match (if NULL it won't be matched). - * \retval NULL if not found - * \retval The node on success. +/*! + * \brief Set an attribute to a node. + * \param node In which node we want to insert the attribute. + * \param name The attribute name. + * \param value The attribute value. + * \retval 0 on success. + * \retval -1 on error. + */ +int ast_xml_set_attribute(struct ast_xml_node *node, const char *name, const char *value); + +/*! + * \brief Find a node element by name. + * \param node This is the node starting point. + * \param name Node name to find. + * \param attrname attribute name to match (if NULL it won't be matched). + * \param attrvalue attribute value to match (if NULL it won't be matched). + * \retval NULL if not found + * \retval The node on success. */ struct ast_xml_node *ast_xml_find_element(struct ast_xml_node *root_node, const char *name, const char *attrname, const char *attrvalue); struct ast_xml_ns *ast_xml_find_namespace(struct ast_xml_doc *doc, struct ast_xml_node *node, const char *ns_name); const char *ast_xml_get_ns_href(struct ast_xml_ns *ns); -/*! \brief Get an element content string. - * \param node Node from where to get the string. - * \retval NULL on error. - * \retval The text content of node. +/*! + * \brief Get an element content string. + * \param node Node from where to get the string. + * \retval NULL on error. + * \retval The text content of node. */ const char *ast_xml_get_text(struct ast_xml_node *node); -/*! \brief Get the name of a node. */ +/*! + * \brief Set an element content string. + * \param node Node from where to set the content string. + * \param content The text to insert in the node. + */ +void ast_xml_set_text(struct ast_xml_node *node, const char *content); + +/*! + * \brief Get the name of a node. */ const char *ast_xml_node_get_name(struct ast_xml_node *node); -/*! \brief Get the node's children. */ +/*! + * \brief Get the node's children. */ struct ast_xml_node *ast_xml_node_get_children(struct ast_xml_node *node); -/*! \brief Get the next node in the same level. */ +/*! + * \brief Get the next node in the same level. */ struct ast_xml_node *ast_xml_node_get_next(struct ast_xml_node *node); -/*! \brief Get the previous node in the same leve. */ +/*! + * \brief Get the previous node in the same leve. */ struct ast_xml_node *ast_xml_node_get_prev(struct ast_xml_node *node); -/*! \brief Get the parent of a specified node. */ +/*! + * \brief Get the parent of a specified node. */ struct ast_xml_node *ast_xml_node_get_parent(struct ast_xml_node *node); +/*! + * \brief Dump the specified document to a file. */ +int ast_xml_doc_dump_file(FILE *output, struct ast_xml_doc *doc); + /* Features using ast_xml_ */ #ifdef HAVE_LIBXML2 #define AST_XML_DOCS -- cgit v1.2.3