Mon Mar 19 11:30:26 2012

Asterisk developer's documentation


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

Generated on Mon Mar 19 11:30:26 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7