Asterisk - The Open Source Telephony Project GIT-master-7921072
dns_core.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 Core DNS API
21 * \author Joshua Colp <jcolp@digium.com>
22 */
23
24#ifndef _ASTERISK_DNS_CORE_H
25#define _ASTERISK_DNS_CORE_H
26
27#if defined(__cplusplus) || defined(c_plusplus)
28extern "C" {
29#endif
30
31#include "asterisk/netsock2.h"
32
33/*! \brief Opaque structure for an active DNS query */
35
36/*! \brief Opaque structure for a DNS query */
37struct ast_dns_query;
38
39/*!
40 * \brief Get the name queried in a DNS query
41 *
42 * \param query The DNS query
43 *
44 * \return the name queried
45 */
46const char *ast_dns_query_get_name(const struct ast_dns_query *query);
47
48/*!
49 * \brief Get the record resource type of a DNS query
50 *
51 * \param query The DNS query
52 *
53 * \return the record resource type
54 */
55int ast_dns_query_get_rr_type(const struct ast_dns_query *query);
56
57/*!
58 * \brief Get the record resource class of a DNS query
59 *
60 * \param query The DNS query
61 *
62 * \return the record resource class
63 */
64int ast_dns_query_get_rr_class(const struct ast_dns_query *query);
65
66/*!
67 * \brief Get the user specific data of a DNS query
68 *
69 * \param query The DNS query
70 *
71 * \return the user specific data
72 *
73 * \note The reference count of the data is NOT incremented on return
74 */
75void *ast_dns_query_get_data(const struct ast_dns_query *query);
76
77/*! \brief Opaque structure for a DNS query result, guaranteed to be immutable */
78struct ast_dns_result;
79
80/*!
81 * \brief Get the result information for a DNS query
82 *
83 * \param query The DNS query
84 *
85 * \return the DNS result information
86 *
87 * \note The result is NOT ao2 allocated
88 */
89struct ast_dns_result *ast_dns_query_get_result(const struct ast_dns_query *query);
90
91/*!
92 * \brief Get whether the result is secure or not
93 *
94 * \param result The DNS result
95 *
96 * \return whether the result is secure or not
97 */
98unsigned int ast_dns_result_get_secure(const struct ast_dns_result *result);
99
100/*!
101 * \brief Get whether the result is bogus or not
102 *
103 * \param result The DNS result
104 *
105 * \return whether the result is bogus or not
106 */
107unsigned int ast_dns_result_get_bogus(const struct ast_dns_result *result);
108
109/*!
110 * \brief Get the error rcode of a DN result
111 *
112 * \param result The DNS result
113 *
114 * \return the DNS rcode
115 */
116unsigned int ast_dns_result_get_rcode(const struct ast_dns_result *result);
117
118/*!
119 * \brief Get the canonical name of the result
120 *
121 * \param result The DNS result
122 *
123 * \return the canonical name
124 */
125const char *ast_dns_result_get_canonical(const struct ast_dns_result *result);
126
127/*!
128 * \brief Get the first record of a DNS Result
129 *
130 * \param result The DNS result
131 *
132 * \return first DNS record
133 */
135
136/*!
137 * \brief Get the raw DNS answer from a DNS result
138 *
139 * \param result The DNS result
140 *
141 * \return The DNS result
142 */
143const char *ast_dns_result_get_answer(const struct ast_dns_result *result);
144
145/*!
146 * \brief Retrieve the lowest TTL from a result
147 *
148 * \param result The DNS result
149 *
150 * \return the lowest TTL
151 *
152 * \note If no records exist this function will return a TTL of 0
153 */
155
156/*!
157 * \brief Free the DNS result information
158 *
159 * \param result The DNS result
160 */
162
163/*! \brief Opaque structure for a DNS record */
164struct ast_dns_record;
165
166/*!
167 * \brief Callback invoked when a query completes
168 *
169 * \param query The DNS query that was invoked
170 */
171typedef void (*ast_dns_resolve_callback)(const struct ast_dns_query *query);
172
173/*!
174 * \brief Get the resource record type of a DNS record
175 *
176 * \param record The DNS record
177 *
178 * \return the resource record type
179 */
180int ast_dns_record_get_rr_type(const struct ast_dns_record *record);
181
182/*!
183 * \brief Get the resource record class of a DNS record
184 *
185 * \param record The DNS record
186 *
187 * \return the resource record class
188 */
189int ast_dns_record_get_rr_class(const struct ast_dns_record *record);
190
191/*!
192 * \brief Get the TTL of a DNS record
193 *
194 * \param record The DNS record
195 *
196 * \return the TTL
197 */
198int ast_dns_record_get_ttl(const struct ast_dns_record *record);
199
200/*!
201 * \brief Retrieve the raw DNS record
202 *
203 * \param record The DNS record
204 *
205 * \return the raw DNS record
206 */
207const char *ast_dns_record_get_data(const struct ast_dns_record *record);
208
209/*!
210 * \brief Retrieve the size of the raw DNS record
211 *
212 * \param record The DNS record
213 *
214 * \return the size of the raw DNS record
215 */
216size_t ast_dns_record_get_data_size(const struct ast_dns_record *record);
217
218/*!
219 * \brief Get the next DNS record
220 *
221 * \param record The current DNS record
222 *
223 * \return the next DNS record
224 */
225const struct ast_dns_record *ast_dns_record_get_next(const struct ast_dns_record *record);
226
227/*!
228 * \brief Asynchronously resolve a DNS query
229 *
230 * \param name The name of what to resolve
231 * \param rr_type Resource record type
232 * \param rr_class Resource record class
233 * \param callback The callback to invoke upon completion
234 * \param data User data to make available on the query
235 *
236 * \retval non-NULL success - query has been sent for resolution
237 * \retval NULL failure
238 *
239 * \note The result passed to the callback does not need to be freed
240 *
241 * \note The user data MUST be an ao2 object
242 *
243 * \note This function increments the reference count of the user data, it does NOT steal
244 *
245 * \note The active query must be released upon completion or cancellation using ao2_ref
246 */
247struct ast_dns_query_active *ast_dns_resolve_async(const char *name, int rr_type, int rr_class, ast_dns_resolve_callback callback, void *data);
248
249/*!
250 * \brief Cancel an asynchronous DNS resolution
251 *
252 * \param active The active DNS query returned from ast_dns_resolve_async
253 *
254 * \retval 0 success
255 * \retval -1 failure
256 *
257 * \note If successfully cancelled the callback will not be invoked
258 */
260
261/*!
262 * \brief Synchronously resolve a DNS query
263 *
264 * \param name The name of what to resolve
265 * \param rr_type Resource record type
266 * \param rr_class Resource record class
267 * \param result A pointer to hold the DNS result
268 *
269 * \retval 0 success - query was completed and result is available
270 * \retval -1 failure
271 */
272int ast_dns_resolve(const char *name, int rr_type, int rr_class, struct ast_dns_result **result);
273
274/*!
275 * \brief Synchronously resolves host to an AAAA or A record
276 * \since 16.6.0
277 *
278 * \param address A pointer to an ast_sockaddr structure to receive the IPv6 or IPv4 address
279 * \param host The hostname to resolve
280 * \param port (optional) A port to parse into the final ast_sockaddr structure
281 *
282 * \retval 0 success - query was completed and result is available
283 * \retval -1 failure
284 *
285 * \note This function makes parallel queries for both AAAA and A records for the host.
286 * The first returned AAAA record (if any) is used and if not found, the first A record
287 * is used.
288 *
289 * \warning This function is synchronous and will block until records are returned or an error
290 * occurs.
291 */
292int ast_dns_resolve_ipv6_and_ipv4(struct ast_sockaddr *address, const char *host, const char *port);
293
294#if defined(__cplusplus) || defined(c_plusplus)
295}
296#endif
297
298#endif /* _ASTERISK_DNS_CORE_H */
static PGresult * result
Definition: cel_pgsql.c:84
int ast_dns_query_get_rr_type(const struct ast_dns_query *query)
Get the record resource type of a DNS query.
Definition: dns_core.c:62
int ast_dns_record_get_rr_class(const struct ast_dns_record *record)
Get the resource record class of a DNS record.
Definition: dns_core.c:150
int ast_dns_record_get_ttl(const struct ast_dns_record *record)
Get the TTL of a DNS record.
Definition: dns_core.c:155
const struct ast_dns_record * ast_dns_record_get_next(const struct ast_dns_record *record)
Get the next DNS record.
Definition: dns_core.c:170
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)
Asynchronously resolve a DNS query.
Definition: dns_core.c:247
int ast_dns_resolve_cancel(struct ast_dns_query_active *active)
Cancel an asynchronous DNS resolution.
Definition: dns_core.c:272
int ast_dns_query_get_rr_class(const struct ast_dns_query *query)
Get the record resource class of a DNS query.
Definition: dns_core.c:67
int ast_dns_resolve_ipv6_and_ipv4(struct ast_sockaddr *address, const char *host, const char *port)
Synchronously resolves host to an AAAA or A record.
Definition: dns_core.c:369
int ast_dns_result_get_lowest_ttl(const struct ast_dns_result *result)
Retrieve the lowest TTL from a result.
Definition: dns_core.c:112
const char * ast_dns_result_get_canonical(const struct ast_dns_result *result)
Get the canonical name of the result.
Definition: dns_core.c:97
void(* ast_dns_resolve_callback)(const struct ast_dns_query *query)
Callback invoked when a query completes.
Definition: dns_core.h:171
unsigned int ast_dns_result_get_rcode(const struct ast_dns_result *result)
Get the error rcode of a DN result.
Definition: dns_core.c:92
const char * ast_dns_record_get_data(const struct ast_dns_record *record)
Retrieve the raw DNS record.
Definition: dns_core.c:160
const struct ast_dns_record * ast_dns_result_get_records(const struct ast_dns_result *result)
Get the first record of a DNS Result.
Definition: dns_core.c:102
void * ast_dns_query_get_data(const struct ast_dns_query *query)
Get the user specific data of a DNS query.
Definition: dns_core.c:72
void ast_dns_result_free(struct ast_dns_result *result)
Free the DNS result information.
Definition: dns_core.c:130
struct ast_dns_result * ast_dns_query_get_result(const struct ast_dns_query *query)
Get the result information for a DNS query.
Definition: dns_core.c:77
int ast_dns_record_get_rr_type(const struct ast_dns_record *record)
Get the resource record type of a DNS record.
Definition: dns_core.c:145
unsigned int ast_dns_result_get_bogus(const struct ast_dns_result *result)
Get whether the result is bogus or not.
Definition: dns_core.c:87
int ast_dns_resolve(const char *name, int rr_type, int rr_class, struct ast_dns_result **result)
Synchronously resolve a DNS query.
Definition: dns_core.c:314
unsigned int ast_dns_result_get_secure(const struct ast_dns_result *result)
Get whether the result is secure or not.
Definition: dns_core.c:82
const char * ast_dns_query_get_name(const struct ast_dns_query *query)
Get the name queried in a DNS query.
Definition: dns_core.c:57
const char * ast_dns_result_get_answer(const struct ast_dns_result *result)
Get the raw DNS answer from a DNS result.
Definition: dns_core.c:107
size_t ast_dns_record_get_data_size(const struct ast_dns_record *record)
Retrieve the size of the raw DNS record.
Definition: dns_core.c:165
char * address
Definition: f2c.h:59
static const char name[]
Definition: format_mp3.c:68
Network socket handling.
An active DNS query.
Definition: dns_internal.h:201
A DNS query.
Definition: dns_internal.h:137
For AST_LIST.
Definition: dns_internal.h:39
The result of a DNS query.
Definition: dns_internal.h:117
Socket address structure.
Definition: netsock2.h:97