data.h

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

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