diff options
Diffstat (limited to 'include/asterisk/dns_core.h')
| -rw-r--r-- | include/asterisk/dns_core.h | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/include/asterisk/dns_core.h b/include/asterisk/dns_core.h new file mode 100644 index 000000000..1f67bb803 --- /dev/null +++ b/include/asterisk/dns_core.h @@ -0,0 +1,267 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2015, Digium, Inc. + * + * Joshua Colp <jcolp@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Core DNS API + * \author Joshua Colp <jcolp@digium.com> + */ + +#ifndef _ASTERISK_DNS_CORE_H +#define _ASTERISK_DNS_CORE_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +/*! \brief Opaque structure for an active DNS query */ +struct ast_dns_query_active; + +/*! \brief Opaque structure for a DNS query */ +struct ast_dns_query; + +/*! + * \brief Get the name queried in a DNS query + * + * \param query The DNS query + * + * \return the name queried + */ +const char *ast_dns_query_get_name(const struct ast_dns_query *query); + +/*! + * \brief Get the record resource type of a DNS query + * + * \param query The DNS query + * + * \return the record resource type + */ +int ast_dns_query_get_rr_type(const struct ast_dns_query *query); + +/*! + * \brief Get the record resource class of a DNS query + * + * \param query The DNS query + * + * \return the record resource class + */ +int ast_dns_query_get_rr_class(const struct ast_dns_query *query); + +/*! + * \brief Get the user specific data of a DNS query + * + * \param query The DNS query + * + * \return the user specific data + * + * \note The reference count of the data is NOT incremented on return + */ +void *ast_dns_query_get_data(const struct ast_dns_query *query); + +/*! \brief Opaque structure for a DNS query result, guaranteed to be immutable */ +struct ast_dns_result; + +/*! + * \brief Get the result information for a DNS query + * + * \param query The DNS query + * + * \return the DNS result information + * + * \note The result is NOT ao2 allocated + */ +struct ast_dns_result *ast_dns_query_get_result(const struct ast_dns_query *query); + +/*! + * \brief Get whether the result is secure or not + * + * \param result The DNS result + * + * \return whether the result is secure or not + */ +unsigned int ast_dns_result_get_secure(const struct ast_dns_result *result); + +/*! + * \brief Get whether the result is bogus or not + * + * \param result The DNS result + * + * \return whether the result is bogus or not + */ +unsigned int ast_dns_result_get_bogus(const struct ast_dns_result *result); + +/*! + * \brief Get the error rcode of a DN result + * + * \param query The DNS result + * + * \return the DNS rcode + */ +unsigned int ast_dns_result_get_rcode(const struct ast_dns_result *result); + +/*! + * \brief Get the canonical name of the result + * + * \param result The DNS result + * + * \return the canonical name + */ +const char *ast_dns_result_get_canonical(const struct ast_dns_result *result); + +/*! + * \brief Get the first record of a DNS Result + * + * \param result The DNS result + * + * \return first DNS record + */ +const struct ast_dns_record *ast_dns_result_get_records(const struct ast_dns_result *result); + +/*! + * \brief Get the raw DNS answer from a DNS result + * + * \param result The DNS result + * + * \return The DNS result + */ +const char *ast_dns_result_get_answer(const struct ast_dns_result *result); + +/*! + * \brief Retrieve the lowest TTL from a result + * + * \param result The DNS result + * + * \return the lowest TTL + * + * \note If no records exist this function will return a TTL of 0 + */ +int ast_dns_result_get_lowest_ttl(const struct ast_dns_result *result); + +/*! + * \brief Free the DNS result information + * + * \param result The DNS result + */ +void ast_dns_result_free(struct ast_dns_result *result); + +/*! \brief Opaque structure for a DNS record */ +struct ast_dns_record; + +/*! + * \brief Callback invoked when a query completes + * + * \param query The DNS query that was invoked + */ +typedef void (*ast_dns_resolve_callback)(const struct ast_dns_query *query); + +/*! + * \brief Get the resource record type of a DNS record + * + * \param record The DNS record + * + * \return the resource record type + */ +int ast_dns_record_get_rr_type(const struct ast_dns_record *record); + +/*! + * \brief Get the resource record class of a DNS record + * + * \param record The DNS record + * + * \return the resource record class + */ +int ast_dns_record_get_rr_class(const struct ast_dns_record *record); + +/*! + * \brief Get the TTL of a DNS record + * + * \param record The DNS record + * + * \return the TTL + */ +int ast_dns_record_get_ttl(const struct ast_dns_record *record); + +/*! + * \brief Retrieve the raw DNS record + * + * \param record The DNS record + * + * \return the raw DNS record + */ +const char *ast_dns_record_get_data(const struct ast_dns_record *record); + +/*! + * \brief Get the next DNS record + * + * \param record The current DNS record + * + * \return the next DNS record + */ +const struct ast_dns_record *ast_dns_record_get_next(const struct ast_dns_record *record); + +/*! + * \brief Asynchronously resolve a DNS query + * + * \param name The name of what to resolve + * \param rr_type Resource record type + * \param rr_class Resource record class + * \param callback The callback to invoke upon completion + * \param data User data to make available on the query + * + * \retval non-NULL success - query has been sent for resolution + * \retval NULL failure + * + * \note The result passed to the callback does not need to be freed + * + * \note The user data MUST be an ao2 object + * + * \note This function increments the reference count of the user data, it does NOT steal + * + * \note The active query must be released upon completion or cancellation using ao2_ref + */ +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); + +/*! + * \brief Cancel an asynchronous DNS resolution + * + * \param active The active DNS query returned from ast_dns_resolve_async + * + * \retval 0 success + * \retval -1 failure + * + * \note If successfully cancelled the callback will not be invoked + */ +int ast_dns_resolve_cancel(struct ast_dns_query_active *active); + +/*! + * \brief Synchronously resolve a DNS query + * + * \param name The name of what to resolve + * \param rr_type Resource record type + * \param rr_class Resource record class + * \param result A pointer to hold the DNS result + * + * \retval 0 success - query was completed and result is available + * \retval -1 failure + */ +int ast_dns_resolve(const char *name, int rr_type, int rr_class, struct ast_dns_result **result); + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* _ASTERISK_DNS_CORE_H */ |