Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
dns_internal.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 *
21 * \brief Internal DNS structure definitions
22 *
23 * \author Joshua Colp <jcolp@digium.com>
24 */
25
26#ifndef _ASTERISK_DNS_INTERNAL_H
27#define _ASTERISK_DNS_INTERNAL_H
28
29/*! \brief For AST_LIST */
31
32/*! \brief For AST_VECTOR */
33#include "asterisk/vector.h"
34
35/*! \brief For ast_dns_query_set_callback */
37
38/*! \brief Generic DNS record information */
40 /*! \brief Resource record type */
42 /*! \brief Resource record class */
44 /*! \brief Time-to-live of the record */
45 int ttl;
46 /*! \brief The size of the raw DNS record */
47 size_t data_len;
48 /*! \brief Linked list information */
50 /*! \brief pointer to record-specific data.
51 *
52 * For certain "subclasses" of DNS records, the
53 * location of the raw DNS data will differ from
54 * the generic case. This pointer will reliably
55 * be set to point to the raw DNS data, no matter
56 * where in the structure it may lie.
57 */
58 char *data_ptr;
59 /*! \brief The raw DNS record */
60 char data[0];
61};
62
63/*! \brief A TXT record */
65 /*! \brief Generic DNS record information */
67 /*! \brief The number of character strings in the TXT record */
68 size_t count;
69 /*! \brief The raw DNS record */
70 char data[0];
71};
72
73/*! \brief An SRV record */
75 /*! \brief Generic DNS record information */
77 /*! \brief The hostname in the SRV record */
78 const char *host;
79 /*! \brief The priority of the SRV record */
80 unsigned short priority;
81 /*! \brief The weight of the SRV record */
82 unsigned short weight;
83 /*! \brief The port in the SRV record */
84 unsigned short port;
85 /*! \brief The running weight sum */
86 unsigned int weight_sum;
87 /*! \brief Additional data */
88 char data[0];
89};
90
91/*! \brief A NAPTR record */
93 /*! \brief Generic DNS record information */
95 /*! \brief The flags from the NAPTR record */
96 const char *flags;
97 /*! \brief The service from the NAPTR record */
98 const char *service;
99 /*! \brief The regular expression from the NAPTR record */
100 const char *regexp;
101 /*! \brief The replacement from the NAPTR record */
102 const char *replacement;
103 /*! \brief The order for the NAPTR record */
104 unsigned short order;
105 /*! \brief The preference of the NAPTR record */
106 unsigned short preference;
107 /*! \brief Buffer for NAPTR-specific data
108 *
109 * This includes the raw NAPTR record, as well as
110 * the area where the flags, service, regexp, and
111 * replacement strings are stored.
112 */
113 char data[0];
114};
115
116/*! \brief The result of a DNS query */
118 /*! \brief Whether the result is secure */
119 unsigned int secure;
120 /*! \brief Whether the result is bogus */
121 unsigned int bogus;
122 /*! \brief Optional rcode, set if an error occurred */
123 unsigned int rcode;
124 /*! \brief Records returned */
126 /*! \brief The canonical name */
127 const char *canonical;
128 /*! \brief The raw DNS answer */
129 const char *answer;
130 /*! \brief The size of the raw DNS answer */
132 /*! \brief Buffer for dynamic data */
133 char buf[0];
134};
135
136/*! \brief A DNS query */
138 /*! \brief Callback to invoke upon completion */
140 /*! \brief User-specific data */
142 /*! \brief The resolver in use for this query */
144 /*! \brief Resolver-specific data */
146 /*! \brief Result of the DNS query */
148 /*! \brief Resource record type */
150 /*! \brief Resource record class */
152 /*! \brief The name of what is being resolved */
153 char name[0];
154};
155
156/*! \brief A recurring DNS query */
158 /*! \brief Callback to invoke upon completion */
160 /*! \brief User-specific data */
162 /*! \brief Current active query */
164 /*! \brief The recurring query has been cancelled */
165 unsigned int cancelled;
166 /*! \brief Scheduled timer for next resolution */
167 int timer;
168 /*! \brief Resource record type */
170 /*! \brief Resource record class */
172 /*! \brief The name of what is being resolved */
173 char name[0];
174};
175
176/*! \brief A DNS query set query, which includes its state */
178 /*! \brief Whether the query started successfully or not */
179 unsigned int started;
180 /*! \brief The query itself */
182};
183
184/*! \brief A set of DNS queries */
186 /*! \brief DNS queries */
188 /*! \brief Whether the query set is in progress or not */
190 /*! \brief The total number of completed queries */
192 /*! \brief The total number of cancelled queries */
194 /*! \brief Callback to invoke upon completion */
196 /*! \brief User-specific data */
198};
199
200/*! \brief An active DNS query */
202 /*! \brief The underlying DNS query */
204};
205
206struct ast_sched_context;
207
208/*!
209 * \brief Retrieve the DNS scheduler context
210 *
211 * \return scheduler context
212 */
214
215/*!
216 * \brief Allocate and parse a DNS TXT record
217 * \since 16.10.0, 17.4.0
218 *
219 * \param query The DNS query
220 * \param data This specific TXT record
221 * \param size The size of the TXT record
222 *
223 * \retval non-NULL success
224 * \retval NULL failure
225 */
226struct ast_dns_record *dns_txt_alloc(struct ast_dns_query *query, const char *data, const size_t size);
227
228/*!
229 * \brief Allocate and parse a DNS NAPTR record
230 *
231 * \param query The DNS query
232 * \param data This specific NAPTR record
233 * \param size The size of the NAPTR record
234 *
235 * \retval non-NULL success
236 * \retval NULL failure
237 */
238struct ast_dns_record *dns_naptr_alloc(struct ast_dns_query *query, const char *data, const size_t size);
239
240/*!
241 * \brief Sort the NAPTR records on a result
242 *
243 * \param result The DNS result
244 */
246
247/*!
248 * \brief Allocate and parse a DNS SRV record
249 *
250 * \param query The DNS query
251 * \param data This specific SRV record
252 * \param size The size of the SRV record
253 *
254 * \retval non-NULL success
255 * \retval NULL failure
256 */
257struct ast_dns_record *dns_srv_alloc(struct ast_dns_query *query, const char *data, const size_t size);
258
259/*!
260 * \brief Sort the SRV records on a result
261 *
262 * \param result The DNS result
263 */
265
266/*!
267 * \brief Find the location of a DNS record within the entire DNS answer
268 *
269 * The DNS record that has been returned by the resolver may be a copy of the record that was
270 * found in the complete DNS response. If so, then some DNS record types (specifically those that
271 * parse domains) will need to locate the DNS record within the complete DNS response. This is so
272 * that if the domain contains pointers to other sections of the DNS response, then the referenced
273 * domains may be located.
274 *
275 * \param record The DNS record returned by a resolver implementation
276 * \param record_size The size of the DNS record in bytes
277 * \param response The complete DNS answer
278 * \param response_size The size of the complete DNS response
279 */
280char *dns_find_record(const char *record, size_t record_size, const char *response, size_t response_size);
281
282/*!
283 * \brief Parse a 16-bit unsigned value from a DNS record
284 *
285 * \param cur Pointer to the location of the 16-bit value in the DNS record
286 * \param[out] val The parsed 16-bit unsigned integer
287 * \return The number of bytes consumed while parsing
288 */
289int dns_parse_short(unsigned char *cur, uint16_t *val);
290
291/*!
292 * \brief Parse a DNS string from a DNS record
293 *
294 * A DNS string consists of an 8-bit size, followed by the
295 * string value (not NULL-terminated).
296 *
297 * \param cur Pointer to the location of the DNS string
298 * \param[out] size The parsed size of the DNS string
299 * \param[out] val The contained string (not NULL-terminated)
300 * \return The number of bytes consumed while parsing
301 */
302int dns_parse_string(char *cur, uint8_t *size, char **val);
303
304/*!
305 * \brief Allocate a DNS query (but do not start resolution)
306 *
307 * \param name The name of what to resolve
308 * \param rr_type Resource record type
309 * \param rr_class Resource record class
310 * \param callback The callback to invoke upon completion
311 * \param data User data to make available on the query
312 *
313 * \retval non-NULL success
314 * \retval NULL failure
315 *
316 * \note The result passed to the callback does not need to be freed
317 *
318 * \note The user data MUST be an ao2 object
319 *
320 * \note This function increments the reference count of the user data, it does NOT steal
321 *
322 * \note The query must be released upon completion or cancellation using ao2_ref
323 */
324struct ast_dns_query *dns_query_alloc(const char *name, int rr_type, int rr_class, ast_dns_resolve_callback callback, void *data);
325
326#endif /* _ASTERISK_DNS_INTERNAL_H */
static PGresult * result
Definition: cel_pgsql.c:84
void(* ast_dns_resolve_callback)(const struct ast_dns_query *query)
Callback invoked when a query completes.
Definition: dns_core.h:171
void dns_naptr_sort(struct ast_dns_result *result)
Sort the NAPTR records on a result.
Definition: dns_naptr.c:551
char * dns_find_record(const char *record, size_t record_size, const char *response, size_t response_size)
Find the location of a DNS record within the entire DNS answer.
Definition: dns_core.c:703
struct ast_dns_record * dns_naptr_alloc(struct ast_dns_query *query, const char *data, const size_t size)
Allocate and parse a DNS NAPTR record.
Definition: dns_naptr.c:380
struct ast_sched_context * ast_dns_get_sched(void)
Retrieve the DNS scheduler context.
Definition: dns_core.c:52
struct ast_dns_query * dns_query_alloc(const char *name, int rr_type, int rr_class, ast_dns_resolve_callback callback, void *data)
Allocate a DNS query (but do not start resolution)
Definition: dns_core.c:193
int dns_parse_short(unsigned char *cur, uint16_t *val)
Parse a 16-bit unsigned value from a DNS record.
Definition: dns_core.c:724
int dns_parse_string(char *cur, uint8_t *size, char **val)
Parse a DNS string from a DNS record.
Definition: dns_core.c:736
struct ast_dns_record * dns_srv_alloc(struct ast_dns_query *query, const char *data, const size_t size)
Allocate and parse a DNS SRV record.
Definition: dns_srv.c:42
void dns_srv_sort(struct ast_dns_result *result)
Sort the SRV records on a result.
Definition: dns_srv.c:113
struct ast_dns_record * dns_txt_alloc(struct ast_dns_query *query, const char *data, const size_t size)
Allocate and parse a DNS TXT record.
Definition: dns_txt.c:38
DNS Query Set API.
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 macros to manage forward-linked lists.
#define AST_LIST_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:225
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
A NAPTR record.
Definition: dns_internal.h:92
unsigned short order
The order for the NAPTR record.
Definition: dns_internal.h:104
struct ast_dns_record generic
Generic DNS record information.
Definition: dns_internal.h:94
unsigned short preference
The preference of the NAPTR record.
Definition: dns_internal.h:106
const char * regexp
The regular expression from the NAPTR record.
Definition: dns_internal.h:100
char data[0]
Buffer for NAPTR-specific data.
Definition: dns_internal.h:113
const char * flags
The flags from the NAPTR record.
Definition: dns_internal.h:96
const char * service
The service from the NAPTR record.
Definition: dns_internal.h:98
const char * replacement
The replacement from the NAPTR record.
Definition: dns_internal.h:102
An active DNS query.
Definition: dns_internal.h:201
struct ast_dns_query * query
The underlying DNS query.
Definition: dns_internal.h:203
A recurring DNS query.
Definition: dns_internal.h:157
void * user_data
User-specific data.
Definition: dns_internal.h:161
ast_dns_resolve_callback callback
Callback to invoke upon completion.
Definition: dns_internal.h:159
unsigned int cancelled
The recurring query has been cancelled.
Definition: dns_internal.h:165
struct ast_dns_query_active * active
Current active query.
Definition: dns_internal.h:163
int rr_class
Resource record class.
Definition: dns_internal.h:171
int rr_type
Resource record type.
Definition: dns_internal.h:169
int timer
Scheduled timer for next resolution.
Definition: dns_internal.h:167
char name[0]
The name of what is being resolved.
Definition: dns_internal.h:173
A set of DNS queries.
Definition: dns_internal.h:185
void * user_data
User-specific data.
Definition: dns_internal.h:197
ast_dns_query_set_callback callback
Callback to invoke upon completion.
Definition: dns_internal.h:195
struct ast_dns_query_set::@216 queries
DNS queries.
int queries_cancelled
The total number of cancelled queries.
Definition: dns_internal.h:193
int queries_completed
The total number of completed queries.
Definition: dns_internal.h:191
int in_progress
Whether the query set is in progress or not.
Definition: dns_internal.h:189
A DNS query.
Definition: dns_internal.h:137
void * user_data
User-specific data.
Definition: dns_internal.h:141
void * resolver_data
Resolver-specific data.
Definition: dns_internal.h:145
ast_dns_resolve_callback callback
Callback to invoke upon completion.
Definition: dns_internal.h:139
struct ast_dns_resolver * resolver
The resolver in use for this query.
Definition: dns_internal.h:143
struct ast_dns_result * result
Result of the DNS query.
Definition: dns_internal.h:147
int rr_class
Resource record class.
Definition: dns_internal.h:151
int rr_type
Resource record type.
Definition: dns_internal.h:149
char name[0]
The name of what is being resolved.
Definition: dns_internal.h:153
For AST_LIST.
Definition: dns_internal.h:39
int ttl
Time-to-live of the record.
Definition: dns_internal.h:45
char data[0]
The raw DNS record.
Definition: dns_internal.h:60
struct ast_dns_record::@215 list
Linked list information.
int rr_class
Resource record class.
Definition: dns_internal.h:43
int rr_type
Resource record type.
Definition: dns_internal.h:41
size_t data_len
The size of the raw DNS record.
Definition: dns_internal.h:47
char * data_ptr
pointer to record-specific data.
Definition: dns_internal.h:58
DNS resolver implementation.
Definition: dns_resolver.h:32
The result of a DNS query.
Definition: dns_internal.h:117
char buf[0]
Buffer for dynamic data.
Definition: dns_internal.h:133
struct ast_dns_result::dns_records records
const char * canonical
The canonical name.
Definition: dns_internal.h:127
size_t answer_size
The size of the raw DNS answer.
Definition: dns_internal.h:131
unsigned int bogus
Whether the result is bogus.
Definition: dns_internal.h:121
unsigned int secure
Whether the result is secure.
Definition: dns_internal.h:119
const char * answer
The raw DNS answer.
Definition: dns_internal.h:129
unsigned int rcode
Optional rcode, set if an error occurred.
Definition: dns_internal.h:123
An SRV record.
Definition: dns_internal.h:74
struct ast_dns_record generic
Generic DNS record information.
Definition: dns_internal.h:76
unsigned short weight
The weight of the SRV record.
Definition: dns_internal.h:82
unsigned short priority
The priority of the SRV record.
Definition: dns_internal.h:80
unsigned int weight_sum
The running weight sum.
Definition: dns_internal.h:86
char data[0]
Additional data.
Definition: dns_internal.h:88
unsigned short port
The port in the SRV record.
Definition: dns_internal.h:84
const char * host
The hostname in the SRV record.
Definition: dns_internal.h:78
A TXT record.
Definition: dns_internal.h:64
struct ast_dns_record generic
Generic DNS record information.
Definition: dns_internal.h:66
size_t count
The number of character strings in the TXT record.
Definition: dns_internal.h:68
char data[0]
The raw DNS record.
Definition: dns_internal.h:70
A DNS query set query, which includes its state.
Definition: dns_internal.h:177
struct ast_dns_query * query
The query itself.
Definition: dns_internal.h:181
unsigned int started
Whether the query started successfully or not.
Definition: dns_internal.h:179
Definition: ast_expr2.c:325
Vector container support.
#define AST_VECTOR(name, type)
Define a vector structure.
Definition: vector.h:44