Asterisk - The Open Source Telephony Project  GIT-master-4a4f1a5
dns_query_set.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2015, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  * \brief DNS Query Set API
21  * \author Joshua Colp <jcolp@digium.com>
22  */
23 
24 #ifndef _ASTERISK_DNS_QUERY_SET_H
25 #define _ASTERISK_DNS_QUERY_SET_H
26 
27 #if defined(__cplusplus) || defined(c_plusplus)
28 extern "C" {
29 #endif
30 
31 /*! \brief Opaque structure for a set of DNS queries */
32 struct ast_dns_query_set;
33 
34 /*!
35  * \brief Callback invoked when a query set completes
36  *
37  * \param query_set The DNS query set that was invoked
38  */
39 typedef void (*ast_dns_query_set_callback)(const struct ast_dns_query_set *query_set);
40 
41 /*!
42  * \brief Create a query set to hold queries
43  *
44  * \retval non-NULL success
45  * \retval NULL failure
46  *
47  * \note The query set must be released upon cancellation or completion using ao2_ref
48  */
50 
51 /*!
52  * \brief Add a query to a query set
53  *
54  * \param query_set A DNS query set
55  * \param name The name of what to resolve
56  * \param rr_type Resource record type
57  * \param rr_class Resource record class
58  *
59  * \retval 0 success
60  * \retval -1 failure
61  */
62 int ast_dns_query_set_add(struct ast_dns_query_set *query_set, const char *name, int rr_type, int rr_class);
63 
64 /*!
65  * \brief Retrieve the number of queries in a query set
66  *
67  * \param query_set A DNS query set
68  *
69  * \return the number of queries
70  */
71 size_t ast_dns_query_set_num_queries(const struct ast_dns_query_set *query_set);
72 
73 /*!
74  * \brief Retrieve a query from a query set
75  *
76  * \param query_set A DNS query set
77  * \param index The index of the query to retrieve
78  *
79  * \retval non-NULL success
80  * \retval NULL failure
81  *
82  * \note The returned query is only valid for the lifetime of the query set itself
83  */
84 struct ast_dns_query *ast_dns_query_set_get(const struct ast_dns_query_set *query_set, unsigned int index);
85 
86 /*!
87  * \brief Retrieve user specific data from a query set
88  *
89  * \param query_set A DNS query set
90  *
91  * \return user specific data
92  */
93 void *ast_dns_query_set_get_data(const struct ast_dns_query_set *query_set);
94 
95 /*!
96  * \brief Asynchronously resolve queries in a query set
97  *
98  * \param query_set The query set
99  * \param callback The callback to invoke upon completion
100  * \param data User data to make available on the query set
101  *
102  * \note The callback will be invoked when all queries have completed
103  *
104  * \note The user data passed in to this function must be ao2 allocated
105  */
107 
108 /*!
109  * \brief Synchronously resolve queries in a query set
110  *
111  * \param query_set The query set
112  *
113  * \retval 0 success
114  * \retval -1 failure
115  *
116  * \note This function will return when all queries have been completed
117  */
118 int ast_query_set_resolve(struct ast_dns_query_set *query_set);
119 
120 /*!
121  * \brief Cancel an asynchronous DNS query set resolution
122  *
123  * \param query_set The DNS query set
124  *
125  * \retval 0 success (all queries have been cancelled)
126  * \retval -1 failure (some queries could not be cancelled)
127  *
128  * \note If successfully cancelled the callback will not be invoked
129  */
131 
132 #if defined(__cplusplus) || defined(c_plusplus)
133 }
134 #endif
135 
136 #endif /* _ASTERISK_DNS_QUERY_SET_H */
struct ast_dns_query * ast_dns_query_set_get(const struct ast_dns_query_set *query_set, unsigned int index)
Retrieve a query from a query set.
size_t ast_dns_query_set_num_queries(const struct ast_dns_query_set *query_set)
Retrieve the number of queries in a query set.
void * ast_dns_query_set_get_data(const struct ast_dns_query_set *query_set)
Retrieve user specific data from a query set.
struct ast_dns_query_set * ast_dns_query_set_create(void)
Create a query set to hold queries.
Definition: dns_query_set.c:60
int ast_dns_query_set_add(struct ast_dns_query_set *query_set, const char *name, int rr_type, int rr_class)
Add a query to a query set.
int ast_query_set_resolve(struct ast_dns_query_set *query_set)
Synchronously resolve queries in a query set.
int ast_dns_query_set_resolve_cancel(struct ast_dns_query_set *query_set)
Cancel an asynchronous DNS query set resolution.
void ast_dns_query_set_resolve_async(struct ast_dns_query_set *query_set, ast_dns_query_set_callback callback, void *data)
Asynchronously resolve queries in a query set.
void(* ast_dns_query_set_callback)(const struct ast_dns_query_set *query_set)
Callback invoked when a query set completes.
Definition: dns_query_set.h:39
static const char name[]
Definition: format_mp3.c:68
A set of DNS queries.
Definition: dns_internal.h:185
A DNS query.
Definition: dns_internal.h:137
ast_dns_resolve_callback callback
Callback to invoke upon completion.
Definition: dns_internal.h:139