dns_query_set.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2015, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief DNS Query Set API
00021  * \author Joshua Colp <jcolp@digium.com>
00022  */
00023 
00024 #ifndef _ASTERISK_DNS_QUERY_SET_H
00025 #define _ASTERISK_DNS_QUERY_SET_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 /*! \brief Opaque structure for a set of DNS queries */
00032 struct ast_dns_query_set;
00033 
00034 /*!
00035  * \brief Callback invoked when a query set completes
00036  *
00037  * \param query_set The DNS query set that was invoked
00038  */
00039 typedef void (*ast_dns_query_set_callback)(const struct ast_dns_query_set *query_set);
00040 
00041 /*!
00042  * \brief Create a query set to hold queries
00043  *
00044  * \retval non-NULL success
00045  * \retval NULL failure
00046  */
00047 struct ast_dns_query_set *ast_dns_query_set_create(void);
00048 
00049 /*!
00050  * \brief Add a query to a query set
00051  *
00052  * \param query_set A DNS query set
00053  * \param name The name of what to resolve
00054  * \param rr_type Resource record type
00055  * \param rr_class Resource record class
00056  *
00057  * \retval 0 success
00058  * \retval -1 failure
00059  */
00060 int ast_dns_query_set_add(struct ast_dns_query_set *query_set, const char *name, int rr_type, int rr_class);
00061 
00062 /*!
00063  * \brief Retrieve the number of queries in a query set
00064  *
00065  * \param query_set A DNS query set
00066  *
00067  * \return the number of queries
00068  */
00069 size_t ast_dns_query_set_num_queries(const struct ast_dns_query_set *query_set);
00070 
00071 /*!
00072  * \brief Retrieve a query from a query set
00073  *
00074  * \param query_set A DNS query set
00075  * \param index The index of the query to retrieve
00076  *
00077  * \retval non-NULL success
00078  * \retval NULL failure
00079  */
00080 struct ast_dns_query *ast_dns_query_set_get(const struct ast_dns_query_set *query_set, unsigned int index);
00081 
00082 /*!
00083  * \brief Retrieve user specific data from a query set
00084  *
00085  * \param query_set A DNS query set
00086  *
00087  * \return user specific data
00088  */
00089 void *ast_dns_query_set_get_data(const struct ast_dns_query_set *query_set);
00090 
00091 /*!
00092  * \brief Asynchronously resolve queries in a query set
00093  *
00094  * \param query_set The query set
00095  * \param callback The callback to invoke upon completion
00096  * \param data User data to make available on the query set
00097  *
00098  * \note The callback will be invoked when all queries have completed
00099  *
00100  * \note The user data passed in to this function must be ao2 allocated
00101  */
00102 void ast_dns_query_set_resolve_async(struct ast_dns_query_set *query_set, ast_dns_query_set_callback callback, void *data);
00103 
00104 /*!
00105  * \brief Synchronously resolve queries in a query set
00106  *
00107  * \param query_set The query set
00108  *
00109  * \note This function will return when all queries have been completed
00110  */
00111 void ast_query_set_resolve(struct ast_dns_query_set *query_set);
00112 
00113 /*!
00114  * \brief Cancel an asynchronous DNS query set resolution
00115  *
00116  * \param query_set The DNS query set
00117  *
00118  * \retval 0 success
00119  * \retval -1 failure
00120  *
00121  * \note If successfully cancelled the callback will not be invoked
00122  */
00123 int ast_dns_query_set_resolve_cancel(struct ast_dns_query_set *query_set);
00124 
00125 /*!
00126  * \brief Free a query set
00127  *
00128  * \param query_set A DNS query set
00129  */
00130 void ast_dns_query_set_free(struct ast_dns_query_set *query_set);
00131 
00132 #if defined(__cplusplus) || defined(c_plusplus)
00133 }
00134 #endif
00135 
00136 #endif /* _ASTERISK_DNS_QUERY_SET_H */

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