Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / dns / include / dns / request.h
1 /*
2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
3  * Copyright (C) 2000-2002  Internet Software Consortium.
4  *
5  * Permission to use, copy, modify, and/or distribute this software for any
6  * purpose with or without fee is hereby granted, provided that the above
7  * copyright notice and this permission notice appear in all copies.
8  *
9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15  * PERFORMANCE OF THIS SOFTWARE.
16  */
17
18 /* $Id: request.h,v 1.27.128.2 2009/01/19 23:47:03 tbox Exp $ */
19
20 #ifndef DNS_REQUEST_H
21 #define DNS_REQUEST_H 1
22
23 /*****
24  ***** Module Info
25  *****/
26
27 /*! \file dns/request.h
28  *
29  * \brief
30  * The request module provides simple request/response services useful for
31  * sending SOA queries, DNS Notify messages, and dynamic update requests.
32  *
33  * MP:
34  *\li   The module ensures appropriate synchronization of data structures it
35  *      creates and manipulates.
36  *
37  * Resources:
38  *\li   TBS
39  *
40  * Security:
41  *\li   No anticipated impact.
42  */
43
44 #include <isc/lang.h>
45 #include <isc/event.h>
46
47 #include <dns/types.h>
48
49 #define DNS_REQUESTOPT_TCP 0x00000001U
50
51 typedef struct dns_requestevent {
52         ISC_EVENT_COMMON(struct dns_requestevent);
53         isc_result_t result;
54         dns_request_t *request;
55 } dns_requestevent_t;
56
57 ISC_LANG_BEGINDECLS
58
59 isc_result_t
60 dns_requestmgr_create(isc_mem_t *mctx, isc_timermgr_t *timermgr,
61                       isc_socketmgr_t *socketmgr, isc_taskmgr_t *taskmgr,
62                       dns_dispatchmgr_t *dispatchmgr,
63                       dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6,
64                       dns_requestmgr_t **requestmgrp);
65 /*%<
66  * Create a request manager.
67  *
68  * Requires:
69  *
70  *\li   'mctx' is a valid memory context.
71  *
72  *\li   'timermgr' is a valid timer manager.
73  *
74  *\li   'socketmgr' is a valid socket manager.
75  *
76  *\li   'taskmgr' is a valid task manager.
77  *
78  *\li   'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
79  *
80  *\li   'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
81  *
82  *\li   requestmgrp != NULL && *requestmgrp == NULL
83  *
84  * Ensures:
85  *
86  *\li   On success, *requestmgrp is a valid request manager.
87  *
88  * Returns:
89  *
90  *\li   ISC_R_SUCCESS
91  *
92  *\li   Any other result indicates failure.
93  */
94
95 void
96 dns_requestmgr_whenshutdown(dns_requestmgr_t *requestmgr, isc_task_t *task,
97                             isc_event_t **eventp);
98 /*%<
99  * Send '*eventp' to 'task' when 'requestmgr' has completed shutdown.
100  *
101  * Notes:
102  *
103  *\li   It is not safe to detach the last reference to 'requestmgr' until
104  *      shutdown is complete.
105  *
106  * Requires:
107  *
108  *\li   'requestmgr' is a valid request manager.
109  *
110  *\li   'task' is a valid task.
111  *
112  *\li   *eventp is a valid event.
113  *
114  * Ensures:
115  *
116  *\li   *eventp == NULL.
117  */
118
119 void
120 dns_requestmgr_shutdown(dns_requestmgr_t *requestmgr);
121 /*%<
122  * Start the shutdown process for 'requestmgr'.
123  *
124  * Notes:
125  *
126  *\li   This call has no effect if the request manager is already shutting
127  *      down.
128  *
129  * Requires:
130  *
131  *\li   'requestmgr' is a valid requestmgr.
132  */
133
134 void
135 dns_requestmgr_attach(dns_requestmgr_t *source, dns_requestmgr_t **targetp);
136 /*%<
137  *      Attach to the request manager.  dns_requestmgr_shutdown() must not
138  *      have been called on 'source' prior to calling dns_requestmgr_attach().
139  *
140  * Requires:
141  *
142  *\li   'source' is a valid requestmgr.
143  *
144  *\li   'targetp' to be non NULL and '*targetp' to be NULL.
145  */
146
147 void
148 dns_requestmgr_detach(dns_requestmgr_t **requestmgrp);
149 /*%<
150  *      Detach from the given requestmgr.  If this is the final detach
151  *      requestmgr will be destroyed.  dns_requestmgr_shutdown() must
152  *      be called before the final detach.
153  *
154  * Requires:
155  *
156  *\li   '*requestmgrp' is a valid requestmgr.
157  *
158  * Ensures:
159  *\li   '*requestmgrp' is NULL.
160  */
161
162 isc_result_t
163 dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message,
164                    isc_sockaddr_t *address, unsigned int options,
165                    dns_tsigkey_t *key,
166                    unsigned int timeout, isc_task_t *task,
167                    isc_taskaction_t action, void *arg,
168                    dns_request_t **requestp);
169 /*%<
170  * Create and send a request.
171  *
172  * Notes:
173  *
174  *\li   'message' will be rendered and sent to 'address'.  If the
175  *      #DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
176  *      will timeout after 'timeout' seconds.
177  *
178  *\li   When the request completes, successfully, due to a timeout, or
179  *      because it was canceled, a completion event will be sent to 'task'.
180  *
181  * Requires:
182  *
183  *\li   'message' is a valid DNS message.
184  *
185  *\li   'address' is a valid sockaddr.
186  *
187  *\li   'timeout' > 0
188  *
189  *\li   'task' is a valid task.
190  *
191  *\li   requestp != NULL && *requestp == NULL
192  */
193
194 /*% See dns_request_createvia3() */
195 isc_result_t
196 dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message,
197                       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
198                       unsigned int options, dns_tsigkey_t *key,
199                       unsigned int timeout, isc_task_t *task,
200                       isc_taskaction_t action, void *arg,
201                       dns_request_t **requestp);
202
203 /*% See dns_request_createvia3() */
204 isc_result_t
205 dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message,
206                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
207                        unsigned int options, dns_tsigkey_t *key,
208                        unsigned int timeout, unsigned int udptimeout,
209                        isc_task_t *task, isc_taskaction_t action, void *arg,
210                        dns_request_t **requestp);
211
212 isc_result_t
213 dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message,
214                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
215                        unsigned int options, dns_tsigkey_t *key,
216                        unsigned int timeout, unsigned int udptimeout,
217                        unsigned int udpretries, isc_task_t *task,
218                        isc_taskaction_t action, void *arg,
219                        dns_request_t **requestp);
220 /*%<
221  * Create and send a request.
222  *
223  * Notes:
224  *
225  *\li   'message' will be rendered and sent to 'address'.  If the
226  *      #DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
227  *      will timeout after 'timeout' seconds.  UDP requests will be resent
228  *      at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero.
229  *
230  *\li   When the request completes, successfully, due to a timeout, or
231  *      because it was canceled, a completion event will be sent to 'task'.
232  *
233  * Requires:
234  *
235  *\li   'message' is a valid DNS message.
236  *
237  *\li   'dstaddr' is a valid sockaddr.
238  *
239  *\li   'srcaddr' is a valid sockaddr or NULL.
240  *
241  *\li   'srcaddr' and 'dstaddr' are the same protocol family.
242  *
243  *\li   'timeout' > 0
244  *
245  *\li   'task' is a valid task.
246  *
247  *\li   requestp != NULL && *requestp == NULL
248  */
249
250 /*% See dns_request_createraw3() */
251 isc_result_t
252 dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
253                       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
254                       unsigned int options, unsigned int timeout,
255                       isc_task_t *task, isc_taskaction_t action, void *arg,
256                       dns_request_t **requestp);
257
258 /*% See dns_request_createraw3() */
259 isc_result_t
260 dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
261                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
262                        unsigned int options, unsigned int timeout,
263                        unsigned int udptimeout, isc_task_t *task,
264                        isc_taskaction_t action, void *arg,
265                        dns_request_t **requestp);
266
267 isc_result_t
268 dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
269                        isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
270                        unsigned int options, unsigned int timeout,
271                        unsigned int udptimeout, unsigned int udpretries,
272                        isc_task_t *task, isc_taskaction_t action, void *arg,
273                        dns_request_t **requestp);
274 /*!<
275  * \brief Create and send a request.
276  *
277  * Notes:
278  *
279  *\li   'msgbuf' will be sent to 'destaddr' after setting the id.  If the
280  *      #DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
281  *      will timeout after 'timeout' seconds.   UDP requests will be resent
282  *      at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero.
283  *
284  *\li   When the request completes, successfully, due to a timeout, or
285  *      because it was canceled, a completion event will be sent to 'task'.
286  *
287  * Requires:
288  *
289  *\li   'msgbuf' is a valid DNS message in compressed wire format.
290  *
291  *\li   'destaddr' is a valid sockaddr.
292  *
293  *\li   'srcaddr' is a valid sockaddr or NULL.
294  *
295  *\li   'srcaddr' and 'dstaddr' are the same protocol family.
296  *
297  *\li   'timeout' > 0
298  *
299  *\li   'task' is a valid task.
300  *
301  *\li   requestp != NULL && *requestp == NULL
302  */
303
304 void
305 dns_request_cancel(dns_request_t *request);
306 /*%<
307  * Cancel 'request'.
308  *
309  * Requires:
310  *
311  *\li   'request' is a valid request.
312  *
313  * Ensures:
314  *
315  *\li   If the completion event for 'request' has not yet been sent, it
316  *      will be sent, and the result code will be ISC_R_CANCELED.
317  */
318
319 isc_result_t
320 dns_request_getresponse(dns_request_t *request, dns_message_t *message,
321                         unsigned int options);
322 /*%<
323  * Get the response to 'request' by filling in 'message'.
324  *
325  * 'options' is passed to dns_message_parse().  See dns_message_parse()
326  * for more details.
327  *
328  * Requires:
329  *
330  *\li   'request' is a valid request for which the caller has received the
331  *      completion event.
332  *
333  *\li   The result code of the completion event was #ISC_R_SUCCESS.
334  *
335  * Returns:
336  *
337  *\li   ISC_R_SUCCESS
338  *
339  *\li   Any result that dns_message_parse() can return.
340  */
341
342 isc_boolean_t
343 dns_request_usedtcp(dns_request_t *request);
344 /*%<
345  * Return whether this query used TCP or not.  Setting #DNS_REQUESTOPT_TCP
346  * in the call to dns_request_create() will cause the function to return
347  * #ISC_TRUE, otherwise the result is based on the query message size.
348  *
349  * Requires:
350  *\li   'request' is a valid request.
351  *
352  * Returns:
353  *\li   ISC_TRUE        if TCP was used.
354  *\li   ISC_FALSE       if UDP was used.
355  */
356
357 void
358 dns_request_destroy(dns_request_t **requestp);
359 /*%<
360  * Destroy 'request'.
361  *
362  * Requires:
363  *
364  *\li   'request' is a valid request for which the caller has received the
365  *      completion event.
366  *
367  * Ensures:
368  *
369  *\li   *requestp == NULL
370  */
371
372 ISC_LANG_ENDDECLS
373
374 #endif /* DNS_REQUEST_H */