dns_recurring.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 Recurring Resolution API
00021  * \author Joshua Colp <jcolp@digium.com>
00022  */
00023 
00024 #ifndef _ASTERISK_DNS_RECURRING_H
00025 #define _ASTERISK_DNS_RECURRING_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 /*! \brief Opaque structure for a recurring DNS query */
00032 struct ast_dns_query_recurring;
00033 
00034 /*!
00035  * \brief Asynchronously resolve a DNS query, and continue resolving it according to the lowest TTL available
00036  *
00037  * \param name The name of what to resolve
00038  * \param rr_type Resource record type
00039  * \param rr_class Resource record class
00040  * \param callback The callback to invoke upon completion
00041  * \param data User data to make available on the query
00042  *
00043  * \retval non-NULL success - query has been sent for resolution
00044  * \retval NULL failure
00045  *
00046  * \note The user data passed in to this function must be ao2 allocated
00047  *
00048  * \note This query will continue to happen according to the lowest TTL unless cancelled using ast_dns_resolve_recurring_cancel
00049  *
00050  * \note It is NOT possible for the callback to be invoked concurrently for the query multiple times
00051  *
00052  * \note The query will occur when the TTL expires, not before. This means that there is a period of time where the previous
00053  *       information can be considered stale.
00054  *
00055  * \note If the TTL is determined to be 0 (the record specifies 0, or no records exist) this will cease doing a recurring query.
00056  *       It is the responsibility of the caller to resume querying at an interval they determine.
00057  */
00058 struct ast_dns_query_recurring *ast_dns_resolve_recurring(const char *name, int rr_type, int rr_class, ast_dns_resolve_callback callback, void *data);
00059 
00060 /*!
00061  * \brief Cancel an asynchronous recurring DNS resolution
00062  *
00063  * \param query The DNS query returned from ast_dns_resolve_recurring
00064  *
00065  * \retval 0 success - any active query has been cancelled and the query will no longer occur
00066  * \retval -1 failure - an active query was in progress and could not be cancelled
00067  *
00068  * \note If successfully cancelled the callback will not be invoked
00069  *
00070  * \note This function does NOT drop your reference to the recurring query, this should be dropped using ao2_ref
00071  */
00072 int ast_dns_resolve_recurring_cancel(struct ast_dns_query_recurring *recurring);
00073 
00074 #if defined(__cplusplus) || defined(c_plusplus)
00075 }
00076 #endif
00077 
00078 #endif /* _ASTERISK_DNS_RECURRING_H */

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