[svn-commits] eliel: branch group/data_api_gsoc2009 r210649 - /team/group/data_api_gsoc2009...

[SVN commits to the Digium repositories]

Author: eliel
Date: Wed Aug  5 15:15:31 2009
New Revision: 210649

URL: http://svn.asterisk.org/svn-view/asterisk?view=rev&rev=210649
Log:
Add more documentation.


Modified:
    team/group/data_api_gsoc2009/include/asterisk/data.h
    team/group/data_api_gsoc2009/include/asterisk/doxyref.h

Modified: team/group/data_api_gsoc2009/include/asterisk/data.h
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/data_api_gsoc2009/include/asterisk/data.h?view=diff&rev=210649&r1=210648&r2=210649
==============================================================================
--- team/group/data_api_gsoc2009/include/asterisk/data.h (original)
+++ team/group/data_api_gsoc2009/include/asterisk/data.h Wed Aug  5 15:15:31 2009
@@ -36,12 +36,17 @@
  * To register a callback use:
  *
  * \code
- *      ast_data_register("/node/path", &callback_fn);
+ *	static const struct ast_data_handler callback_handler = {
+ *		.get = callback_handler_get_function,
+ *		.put = callback_handler_put_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 = {
+ *	static const struct ast_data_handler handler_struct1 = {
  *		.get = handler_callback_read,
  *		.put = handler_callback_write
  *	};
@@ -55,7 +60,7 @@
  *
  *      ...
  *
- *      ast_data_register_multiple(list_providers, ARRAY_LEN(list_providers));
+ *	ast_data_register_multiple(list_providers, ARRAY_LEN(list_providers));
  * \endcode
  *
  * To unregister a callback function already registered you can just call:
@@ -70,6 +75,50 @@
  *	ast_data_unregister("/node/path");
  * \endcode
  *
+ * To get the tree you need to create a query, a query is based on three parameters
+ * a path to the provider, a search condition and a 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
+ *
+ * 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).
+ * 
+ * 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)

Modified: team/group/data_api_gsoc2009/include/asterisk/doxyref.h
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/data_api_gsoc2009/include/asterisk/doxyref.h?view=diff&rev=210649&r1=210648&r2=210649
==============================================================================
--- team/group/data_api_gsoc2009/include/asterisk/doxyref.h (original)
+++ team/group/data_api_gsoc2009/include/asterisk/doxyref.h Wed Aug  5 15:15:31 2009
@@ -88,6 +88,7 @@
  * \arg \ref AstThreadStorage
  * \arg \ref DataStores
  * \arg \ref AstExtState
+ * \arg \ref AstDataRetrieval
  *
  * \subsection model_txt Generic Model
  * \verbinclude model.txt