Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
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)
28 extern "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 */
37 struct 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  */
46 const 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  */
55 int 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  */
64 int 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  */
75 void *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 */
78 struct 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  */
89 struct 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  */
98 unsigned 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  */
107 unsigned 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 query The DNS result
113  *
114  * \return the DNS rcode
115  */
116 unsigned 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  */
125 const 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  */
143 const 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 */
164 struct ast_dns_record;
165 
166 /*!
167  * \brief Callback invoked when a query completes
168  *
169  * \param query The DNS query that was invoked
170  */
171 typedef 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  */
180 int 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  */
189 int 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  */
198 int 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  */
207 const 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  */
216 size_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  */
225 const 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  */
247 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);
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  */
259 int ast_dns_resolve_cancel(struct ast_dns_query_active *active);
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  */
272 int 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  * occurrs.
291  */
292 int 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 */
int ast_dns_record_get_ttl(const struct ast_dns_record *record)
Get the TTL of a DNS record.
Definition: dns_core.c:155
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 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
static const char name[]
Definition: format_mp3.c:68
const char * ast_dns_record_get_data(const struct ast_dns_record *record)
Retrieve the raw DNS record.
Definition: dns_core.c:160
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
void ast_dns_result_free(struct ast_dns_result *result)
Free the DNS result information.
Definition: dns_core.c:130
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
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
void(* ast_dns_resolve_callback)(const struct ast_dns_query *query)
Callback invoked when a query completes.
Definition: dns_core.h:171
char * address
Definition: f2c.h:59
For AST_LIST.
Definition: dns_internal.h:39
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_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
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
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
Socket address structure.
Definition: netsock2.h:97
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
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
Network socket handling.
The result of a DNS query.
Definition: dns_internal.h:117
An active DNS query.
Definition: dns_internal.h:201
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
A DNS query.
Definition: dns_internal.h:137
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
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_resolve_cancel(struct ast_dns_query_active *active)
Cancel an asynchronous DNS resolution.
Definition: dns_core.c:272
static PGresult * result
Definition: cel_pgsql.c:88
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
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_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_rcode(const struct ast_dns_result *result)
Get the error rcode of a DN result.
Definition: dns_core.c:92