Asterisk - The Open Source Telephony Project  GIT-master-4a4f1a5
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 */
30 #include "asterisk/linkedlists.h"
31 
32 /*! \brief For AST_VECTOR */
33 #include "asterisk/vector.h"
34 
35 /*! \brief For ast_dns_query_set_callback */
36 #include "asterisk/dns_query_set.h"
37 
38 /*! \brief Generic DNS record information */
40  /*! \brief Resource record type */
41  int rr_type;
42  /*! \brief Resource record class */
43  int rr_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 */
66  struct ast_dns_record generic;
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 */
76  struct ast_dns_record generic;
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 */
94  struct ast_dns_record generic;
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 */
131  size_t answer_size;
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 */
141  void *user_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 */
149  int rr_type;
150  /*! \brief Resource record class */
151  int rr_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 */
161  void *user_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 */
169  int rr_type;
170  /*! \brief Resource record class */
171  int rr_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 */
197  void *user_data;
198 };
199 
200 /*! \brief An active DNS query */
202  /*! \brief The underlying DNS query */
204 };
205 
206 struct 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  */
226 struct 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  */
238 struct 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  */
245 void dns_naptr_sort(struct ast_dns_result *result);
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  */
257 struct 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  */
264 void dns_srv_sort(struct ast_dns_result *result);
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  */
280 char *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  */
289 int 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  */
302 int 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  */
324 struct 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:88
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
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_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:722
struct ast_sched_context * ast_dns_get_sched(void)
Retrieve the DNS scheduler context.
Definition: dns_core.c:52
int dns_parse_string(char *cur, uint8_t *size, char **val)
Parse a DNS string from a DNS record.
Definition: dns_core.c:734
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
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
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:701
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
static struct queries queries
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
AST_LIST_HEAD_NOLOCK(contactliststruct, contact)
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
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
AST_VECTOR(, struct dns_query_set_query) queries
DNS queries.
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
struct ast_dns_record::@240 list
Linked list information.
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
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.