dns_resolver.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 Resolver API
00021  * \author Joshua Colp <jcolp@digium.com>
00022  */
00023 
00024 #ifndef _ASTERISK_DNS_RESOLVER_H
00025 #define _ASTERISK_DNS_RESOLVER_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 /*! \brief DNS resolver implementation */
00032 struct ast_dns_resolver {
00033     /*! \brief The name of the resolver implementation */
00034     const char *name;
00035 
00036     /*! \brief Priority for this resolver if multiple exist, lower being higher priority */
00037     unsigned int priority;
00038 
00039     /*!
00040      * \brief Perform resolution of a DNS query
00041      *
00042      * \note The reference count of the query should be increased and released
00043      *       upon the query completing or being successfully cancelled
00044      */
00045     int (*resolve)(struct ast_dns_query *query);
00046 
00047     /*! \brief Cancel resolution of a DNS query */
00048     int (*cancel)(struct ast_dns_query *query);
00049 
00050     /*! \brief Linked list information */
00051     AST_RWLIST_ENTRY(ast_dns_resolver) next;
00052 };
00053 
00054 /*!
00055  * \brief Set resolver specific data on a query
00056  *
00057  * \param query The DNS query
00058  * \param data The resolver specific data
00059  *
00060  * \note The resolver data MUST be an ao2 object
00061  *
00062  * \note This function increments the reference count of the resolver data, it does NOT steal
00063  *
00064  * \note Once resolver specific data has been set it can not be changed
00065  *
00066  * \retval 0 success
00067  * \retval -1 failure, resolver data is already set
00068  */
00069 int ast_dns_resolver_set_data(struct ast_dns_query *query, void *data);
00070 
00071 /*!
00072  * \brief Retrieve resolver specific data
00073  *
00074  * \param query The DNS query
00075  *
00076  * \return the resolver specific data
00077  *
00078  * \note The reference count of the resolver data is NOT incremented on return
00079  */
00080 void *ast_dns_resolver_get_data(const struct ast_dns_query *query);
00081 
00082 /*!
00083  * \brief Set result information for a DNS query
00084  *
00085  * \param query The DNS query
00086  * \param result Whether the result is secured or not
00087  * \param bogus Whether the result is bogus or not
00088  * \param rcode Optional response code
00089  * \param canonical The canonical name
00090  * \param answer The raw DNS answer
00091  * \param answer_size The size of the raw DNS answer
00092  *
00093  * \retval 0 success
00094  * \retval -1 failure
00095  */
00096 int ast_dns_resolver_set_result(struct ast_dns_query *query, unsigned int secure, unsigned int bogus,
00097    unsigned int rcode, const char *canonical, const char *answer, size_t answer_size);
00098 
00099 /*!
00100  * \brief Add a DNS record to the result of a DNS query
00101  *
00102  * \param query The DNS query
00103  * \param rr_type Resource record type
00104  * \param rr_class Resource record class
00105  * \param ttl TTL of the record
00106  * \param data The raw DNS record
00107  * \param size The size of the raw DNS record
00108  *
00109  * \retval 0 success
00110  * \retval -1 failure
00111  */
00112 int ast_dns_resolver_add_record(struct ast_dns_query *query, int rr_type, int rr_class, int ttl, const char *data, const size_t size);
00113 
00114 /*!
00115  * \brief Mark a DNS query as having been completed
00116  *
00117  * \param query The DNS query
00118  */
00119 void ast_dns_resolver_completed(struct ast_dns_query *query);
00120 
00121 /*!
00122  * \brief Register a DNS resolver
00123  *
00124  * \param resolver A DNS resolver implementation
00125  *
00126  * \retval 0 success
00127  * \retval -1 failure
00128  */
00129 int ast_dns_resolver_register(struct ast_dns_resolver *resolver);
00130 
00131 /*!
00132  * \brief Unregister a DNS resolver
00133  *
00134  * \param resolver A DNS resolver implementation
00135  */
00136 void ast_dns_resolver_unregister(struct ast_dns_resolver *resolver);
00137 
00138 #if defined(__cplusplus) || defined(c_plusplus)
00139 }
00140 #endif
00141 
00142 #endif /* _ASTERISK_DNS_RESOLVER_H */

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