Asterisk data retrieval API.

This module implements an abstraction for retrieving and exporting
asterisk data.
Developed by:
	Brett Bryant <brettbryant@gmail.com>
	Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
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

5 files changed, 941 insertions, 46 deletions

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) <eliels@gmail.com>
+ *
+ * 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 <brettbryant@gmail.com>
+ * \author Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
+ * \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 <data.h>
+ *
+ *	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