Asterisk - The Open Source Telephony Project GIT-master-55f4e6d
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)
28extern "C" {
29#endif
30
31/*! \brief Opaque structure for a set of DNS queries */
33
34/*!
35 * \brief Callback invoked when a query set completes
36 *
37 * \param query_set The DNS query set that was invoked
38 */
39typedef 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 */
62int 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 */
71size_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 */
84struct 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 */
93void *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 */
118int 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.
struct ast_dns_query_set * ast_dns_query_set_create(void)
Create a query set to hold queries.
Definition: dns_query_set.c:60
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.
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
void * ast_dns_query_set_get_data(const struct ast_dns_query_set *query_set)
Retrieve user specific data from a query set.
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