dns_core.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 Core DNS API
00021  * \author Joshua Colp <jcolp@digium.com>
00022  */
00023 
00024 #ifndef _ASTERISK_DNS_CORE_H
00025 #define _ASTERISK_DNS_CORE_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 /*! \brief Opaque structure for an active DNS query */
00032 struct ast_dns_query_active;
00033 
00034 /*! \brief Opaque structure for a DNS query */
00035 struct ast_dns_query;
00036 
00037 /*!
00038  * \brief Get the name queried in a DNS query
00039  *
00040  * \param query The DNS query
00041  *
00042  * \return the name queried
00043  */
00044 const char *ast_dns_query_get_name(const struct ast_dns_query *query);
00045 
00046 /*!
00047  * \brief Get the record resource type of a DNS query
00048  *
00049  * \param query The DNS query
00050  *
00051  * \return the record resource type
00052  */
00053 int ast_dns_query_get_rr_type(const struct ast_dns_query *query);
00054 
00055 /*!
00056  * \brief Get the record resource class of a DNS query
00057  *
00058  * \param query The DNS query
00059  *
00060  * \return the record resource class
00061  */
00062 int ast_dns_query_get_rr_class(const struct ast_dns_query *query);
00063 
00064 /*!
00065  * \brief Get the user specific data of a DNS query
00066  *
00067  * \param query The DNS query
00068  *
00069  * \return the user specific data
00070  *
00071  * \note The reference count of the data is NOT incremented on return
00072  */
00073 void *ast_dns_query_get_data(const struct ast_dns_query *query);
00074 
00075 /*! \brief Opaque structure for a DNS query result, guaranteed to be immutable */
00076 struct ast_dns_result;
00077 
00078 /*!
00079  * \brief Get the result information for a DNS query
00080  *
00081  * \param query The DNS query
00082  *
00083  * \return the DNS result information
00084  *
00085  * \note The result is NOT ao2 allocated
00086  */
00087 struct ast_dns_result *ast_dns_query_get_result(const struct ast_dns_query *query);
00088 
00089 /*!
00090  * \brief Get whether the result is secure or not
00091  *
00092  * \param result The DNS result
00093  *
00094  * \return whether the result is secure or not
00095  */
00096 unsigned int ast_dns_result_get_secure(const struct ast_dns_result *result);
00097 
00098 /*!
00099  * \brief Get whether the result is bogus or not
00100  *
00101  * \param result The DNS result
00102  *
00103  * \return whether the result is bogus or not
00104  */
00105 unsigned int ast_dns_result_get_bogus(const struct ast_dns_result *result);
00106 
00107 /*!
00108  * \brief Get the error rcode of a DN result
00109  *
00110  * \param query The DNS result
00111  *
00112  * \return the DNS rcode
00113  */
00114 unsigned int ast_dns_result_get_rcode(const struct ast_dns_result *result);
00115 
00116 /*!
00117  * \brief Get the canonical name of the result
00118  *
00119  * \param result The DNS result
00120  *
00121  * \return the canonical name
00122  */
00123 const char *ast_dns_result_get_canonical(const struct ast_dns_result *result);
00124 
00125 /*!
00126  * \brief Get the first record of a DNS Result
00127  *
00128  * \param result The DNS result
00129  *
00130  * \return first DNS record
00131  */
00132 const struct ast_dns_record *ast_dns_result_get_records(const struct ast_dns_result *result);
00133 
00134 /*!
00135  * \brief Get the raw DNS answer from a DNS result
00136  *
00137  * \param result The DNS result
00138  *
00139  * \return The DNS result
00140  */
00141 const char *ast_dns_result_get_answer(const struct ast_dns_result *result);
00142 
00143 /*!
00144  * \brief Retrieve the lowest TTL from a result
00145  *
00146  * \param result The DNS result
00147  *
00148  * \return the lowest TTL
00149  *
00150  * \note If no records exist this function will return a TTL of 0
00151  */
00152 int ast_dns_result_get_lowest_ttl(const struct ast_dns_result *result);
00153 
00154 /*!
00155  * \brief Free the DNS result information
00156  *
00157  * \param result The DNS result
00158  */
00159 void ast_dns_result_free(struct ast_dns_result *result);
00160 
00161 /*! \brief Opaque structure for a DNS record */
00162 struct ast_dns_record;
00163 
00164 /*!
00165  * \brief Callback invoked when a query completes
00166  *
00167  * \param query The DNS query that was invoked
00168  */
00169 typedef void (*ast_dns_resolve_callback)(const struct ast_dns_query *query);
00170 
00171 /*!
00172  * \brief Get the resource record type of a DNS record
00173  *
00174  * \param record The DNS record
00175  *
00176  * \return the resource record type
00177  */
00178 int ast_dns_record_get_rr_type(const struct ast_dns_record *record);
00179 
00180 /*!
00181  * \brief Get the resource record class of a DNS record
00182  *
00183  * \param record The DNS record
00184  *
00185  * \return the resource record class
00186  */
00187 int ast_dns_record_get_rr_class(const struct ast_dns_record *record);
00188 
00189 /*!
00190  * \brief Get the TTL of a DNS record
00191  *
00192  * \param record The DNS record
00193  *
00194  * \return the TTL
00195  */
00196 int ast_dns_record_get_ttl(const struct ast_dns_record *record);
00197 
00198 /*!
00199  * \brief Retrieve the raw DNS record
00200  *
00201  * \param record The DNS record
00202  *
00203  * \return the raw DNS record
00204  */
00205 const char *ast_dns_record_get_data(const struct ast_dns_record *record);
00206 
00207 /*!
00208  * \brief Get the next DNS record
00209  *
00210  * \param record The current DNS record
00211  *
00212  * \return the next DNS record
00213  */
00214 const struct ast_dns_record *ast_dns_record_get_next(const struct ast_dns_record *record);
00215 
00216 /*!
00217  * \brief Asynchronously resolve a DNS query
00218  *
00219  * \param name The name of what to resolve
00220  * \param rr_type Resource record type
00221  * \param rr_class Resource record class
00222  * \param callback The callback to invoke upon completion
00223  * \param data User data to make available on the query
00224  *
00225  * \retval non-NULL success - query has been sent for resolution
00226  * \retval NULL failure
00227  *
00228  * \note The result passed to the callback does not need to be freed
00229  *
00230  * \note The user data MUST be an ao2 object
00231  *
00232  * \note This function increments the reference count of the user data, it does NOT steal
00233  *
00234  * \note The active query must be released upon completion or cancellation using ao2_ref
00235  */
00236 struct ast_dns_query_active *ast_dns_resolve_async(const char *name, int rr_type, int rr_class, ast_dns_resolve_callback callback, void *data);
00237 
00238 /*!
00239  * \brief Cancel an asynchronous DNS resolution
00240  *
00241  * \param active The active DNS query returned from ast_dns_resolve_async
00242  *
00243  * \retval 0 success
00244  * \retval -1 failure
00245  *
00246  * \note If successfully cancelled the callback will not be invoked
00247  */
00248 int ast_dns_resolve_cancel(struct ast_dns_query_active *active);
00249 
00250 /*!
00251  * \brief Synchronously resolve a DNS query
00252  *
00253  * \param name The name of what to resolve
00254  * \param rr_type Resource record type
00255  * \param rr_class Resource record class
00256  * \param result A pointer to hold the DNS result
00257  *
00258  * \retval 0 success - query was completed and result is available
00259  * \retval -1 failure
00260  */
00261 int ast_dns_resolve(const char *name, int rr_type, int rr_class, struct ast_dns_result **result);
00262 
00263 #if defined(__cplusplus) || defined(c_plusplus)
00264 }
00265 #endif
00266 
00267 #endif /* _ASTERISK_DNS_CORE_H */

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