Thu Apr 16 06:48:10 2015

Asterisk developer's documentation


The Asterisk DATA retrieval API.

This module implements an abstraction for retrieving asterisk data and export it.

USAGE

Provider

Register

To register a callback use:

   static const struct ast_data_handler callback_handler = {
      .get = callback_handler_get_function,
   };

   ast_data_register("/node/path", &callback_handler);

If you instead want to register multiple nodes at once use:

   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));

Unregister

To unregister a callback function already registered you can just call:

   ast_data_unregister(NULL);
And every node registered by the current module (file) will be unregistered. If you want to unregister a specific node use:

   ast_data_unregister("/node/path");

Implementation

A simple callback function implementation:

   #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
      };

      internal_node = ast_data_add_node(root_node, "test_node");
      if (!internal_node) {
         return -1;
      }

      ast_data_add_structure(test_structure, internal_node, ts);

      if (!ast_data_search_match(search, internal_node)) {
         ast_data_remove_node(root_node, internal_node);
      }

      return 0;
   }

Get

Getting the tree

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.

   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);

After using it you need to release the allocated memory of the returned tree:

   ast_data_free(result);

Iterate

To retrieve nodes from the tree, it is possible to iterate through the returned nodes of the tree using:

   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);
node_name is the name of the nodes to retrieve and path is the path to the internal nodes to retrieve (if needed).

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:

   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");

Generated on Thu Apr 16 06:48:10 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6