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