1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2015, Digium, Inc.
*
* Joshua Colp <jcolp@digium.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
/*! \file
* \brief Core DNS API
* \author Joshua Colp <jcolp@digium.com>
*/
#ifndef _ASTERISK_DNS_CORE_H
#define _ASTERISK_DNS_CORE_H
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
/*! \brief Opaque structure for an active DNS query */
struct ast_dns_query_active;
/*! \brief Opaque structure for a DNS query */
struct ast_dns_query;
/*!
* \brief Get the name queried in a DNS query
*
* \param query The DNS query
*
* \return the name queried
*/
const char *ast_dns_query_get_name(const struct ast_dns_query *query);
/*!
* \brief Get the record resource type of a DNS query
*
* \param query The DNS query
*
* \return the record resource type
*/
int ast_dns_query_get_rr_type(const struct ast_dns_query *query);
/*!
* \brief Get the record resource class of a DNS query
*
* \param query The DNS query
*
* \return the record resource class
*/
int ast_dns_query_get_rr_class(const struct ast_dns_query *query);
/*!
* \brief Get the user specific data of a DNS query
*
* \param query The DNS query
*
* \return the user specific data
*
* \note The reference count of the data is NOT incremented on return
*/
void *ast_dns_query_get_data(const struct ast_dns_query *query);
/*! \brief Opaque structure for a DNS query result, guaranteed to be immutable */
struct ast_dns_result;
/*!
* \brief Get the result information for a DNS query
*
* \param query The DNS query
*
* \return the DNS result information
*
* \note The result is NOT ao2 allocated
*/
struct ast_dns_result *ast_dns_query_get_result(const struct ast_dns_query *query);
/*!
* \brief Get whether the result is secure or not
*
* \param result The DNS result
*
* \return whether the result is secure or not
*/
unsigned int ast_dns_result_get_secure(const struct ast_dns_result *result);
/*!
* \brief Get whether the result is bogus or not
*
* \param result The DNS result
*
* \return whether the result is bogus or not
*/
unsigned int ast_dns_result_get_bogus(const struct ast_dns_result *result);
/*!
* \brief Get the error rcode of a DN result
*
* \param query The DNS result
*
* \return the DNS rcode
*/
unsigned int ast_dns_result_get_rcode(const struct ast_dns_result *result);
/*!
* \brief Get the canonical name of the result
*
* \param result The DNS result
*
* \return the canonical name
*/
const char *ast_dns_result_get_canonical(const struct ast_dns_result *result);
/*!
* \brief Get the first record of a DNS Result
*
* \param result The DNS result
*
* \return first DNS record
*/
const struct ast_dns_record *ast_dns_result_get_records(const struct ast_dns_result *result);
/*!
* \brief Get the raw DNS answer from a DNS result
*
* \param result The DNS result
*
* \return The DNS result
*/
const char *ast_dns_result_get_answer(const struct ast_dns_result *result);
/*!
* \brief Retrieve the lowest TTL from a result
*
* \param result The DNS result
*
* \return the lowest TTL
*
* \note If no records exist this function will return a TTL of 0
*/
int ast_dns_result_get_lowest_ttl(const struct ast_dns_result *result);
/*!
* \brief Free the DNS result information
*
* \param result The DNS result
*/
void ast_dns_result_free(struct ast_dns_result *result);
/*! \brief Opaque structure for a DNS record */
struct ast_dns_record;
/*!
* \brief Callback invoked when a query completes
*
* \param query The DNS query that was invoked
*/
typedef void (*ast_dns_resolve_callback)(const struct ast_dns_query *query);
/*!
* \brief Get the resource record type of a DNS record
*
* \param record The DNS record
*
* \return the resource record type
*/
int ast_dns_record_get_rr_type(const struct ast_dns_record *record);
/*!
* \brief Get the resource record class of a DNS record
*
* \param record The DNS record
*
* \return the resource record class
*/
int ast_dns_record_get_rr_class(const struct ast_dns_record *record);
/*!
* \brief Get the TTL of a DNS record
*
* \param record The DNS record
*
* \return the TTL
*/
int ast_dns_record_get_ttl(const struct ast_dns_record *record);
/*!
* \brief Retrieve the raw DNS record
*
* \param record The DNS record
*
* \return the raw DNS record
*/
const char *ast_dns_record_get_data(const struct ast_dns_record *record);
/*!
* \brief Retrieve the size of the raw DNS record
*
* \param record The DNS record
*
* \return the size of the raw DNS record
*/
size_t ast_dns_record_get_data_size(const struct ast_dns_record *record);
/*!
* \brief Get the next DNS record
*
* \param record The current DNS record
*
* \return the next DNS record
*/
const struct ast_dns_record *ast_dns_record_get_next(const struct ast_dns_record *record);
/*!
* \brief Asynchronously resolve a DNS query
*
* \param name The name of what to resolve
* \param rr_type Resource record type
* \param rr_class Resource record class
* \param callback The callback to invoke upon completion
* \param data User data to make available on the query
*
* \retval non-NULL success - query has been sent for resolution
* \retval NULL failure
*
* \note The result passed to the callback does not need to be freed
*
* \note The user data MUST be an ao2 object
*
* \note This function increments the reference count of the user data, it does NOT steal
*
* \note The active query must be released upon completion or cancellation using ao2_ref
*/
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);
/*!
* \brief Cancel an asynchronous DNS resolution
*
* \param active The active DNS query returned from ast_dns_resolve_async
*
* \retval 0 success
* \retval -1 failure
*
* \note If successfully cancelled the callback will not be invoked
*/
int ast_dns_resolve_cancel(struct ast_dns_query_active *active);
/*!
* \brief Synchronously resolve a DNS query
*
* \param name The name of what to resolve
* \param rr_type Resource record type
* \param rr_class Resource record class
* \param result A pointer to hold the DNS result
*
* \retval 0 success - query was completed and result is available
* \retval -1 failure
*/
int ast_dns_resolve(const char *name, int rr_type, int rr_class, struct ast_dns_result **result);
#if defined(__cplusplus) || defined(c_plusplus)
}
#endif
#endif /* _ASTERISK_DNS_CORE_H */
|
