2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000-2002 Internet Software Consortium.
5 * Permission to use, copy, modify, and 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.
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.
18 /* $Id: request.h,v 1.17.12.5 2004/03/08 09:04:39 marka Exp $ */
21 #define DNS_REQUEST_H 1
30 * The request module provides simple request/response services useful for
31 * sending SOA queries, DNS Notify messages, and dynamic update requests.
34 * The module ensures appropriate synchronization of data structures it
35 * creates and manipulates.
41 * No anticipated impact.
45 #include <isc/event.h>
47 #include <dns/types.h>
49 #define DNS_REQUESTOPT_TCP 0x00000001U
51 typedef struct dns_requestevent {
52 ISC_EVENT_COMMON(struct dns_requestevent);
54 dns_request_t *request;
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);
66 * Create a request manager.
70 * 'mctx' is a valid memory context.
72 * 'timermgr' is a valid timer manager.
74 * 'socketmgr' is a valid socket manager.
76 * 'taskmgr' is a valid task manager.
78 * 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
80 * 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
82 * requestmgrp != NULL && *requestmgrp == NULL
86 * On success, *requestmgrp is a valid request manager.
92 * Any other result indicates failure.
96 dns_requestmgr_whenshutdown(dns_requestmgr_t *requestmgr, isc_task_t *task,
97 isc_event_t **eventp);
99 * Send '*eventp' to 'task' when 'requestmgr' has completed shutdown.
103 * It is not safe to detach the last reference to 'requestmgr' until
104 * shutdown is complete.
108 * 'requestmgr' is a valid request manager.
110 * 'task' is a valid task.
112 * *eventp is a valid event.
120 dns_requestmgr_shutdown(dns_requestmgr_t *requestmgr);
122 * Start the shutdown process for 'requestmgr'.
126 * This call has no effect if the request manager is already shutting
131 * 'requestmgr' is a valid requestmgr.
135 dns_requestmgr_attach(dns_requestmgr_t *source, dns_requestmgr_t **targetp);
137 * Attach to the request manager. dns_requestmgr_shutdown() must not
138 * have been called on 'source' prior to calling dns_requestmgr_attach().
142 * 'source' is a valid requestmgr.
144 * 'targetp' to be non NULL and '*targetp' to be NULL.
148 dns_requestmgr_detach(dns_requestmgr_t **requestmgrp);
151 * Detach from the given requestmgr. If this is the final detach
152 * requestmgr will be destroyed. dns_requestmgr_shutdown() must
153 * be called before the final detach.
157 * '*requestmgrp' is a valid requestmgr.
160 * '*requestmgrp' is NULL.
164 dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message,
165 isc_sockaddr_t *address, unsigned int options,
167 unsigned int timeout, isc_task_t *task,
168 isc_taskaction_t action, void *arg,
169 dns_request_t **requestp);
171 * Create and send a request.
175 * 'message' will be rendered and sent to 'address'. If the
176 * DNS_REQUESTOPT_TCP option is set, TCP will be used. The request
177 * will timeout after 'timeout' seconds.
179 * When the request completes, successfully, due to a timeout, or
180 * because it was canceled, a completion event will be sent to 'task'.
184 * 'message' is a valid DNS message.
186 * 'address' is a valid sockaddr.
190 * 'task' is a valid task.
192 * requestp != NULL && *requestp == NULL
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);
204 dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message,
205 isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
206 unsigned int options, dns_tsigkey_t *key,
207 unsigned int timeout, unsigned int udptimeout,
208 isc_task_t *task, isc_taskaction_t action, void *arg,
209 dns_request_t **requestp);
212 dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message,
213 isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
214 unsigned int options, dns_tsigkey_t *key,
215 unsigned int timeout, unsigned int udptimeout,
216 unsigned int udpretries, isc_task_t *task,
217 isc_taskaction_t action, void *arg,
218 dns_request_t **requestp);
220 * Create and send a request.
224 * 'message' will be rendered and sent to 'address'. If the
225 * DNS_REQUESTOPT_TCP option is set, TCP will be used. The request
226 * will timeout after 'timeout' seconds. UDP requests will be resent
227 * at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero.
229 * When the request completes, successfully, due to a timeout, or
230 * because it was canceled, a completion event will be sent to 'task'.
234 * 'message' is a valid DNS message.
236 * 'dstaddr' is a valid sockaddr.
238 * 'srcaddr' is a valid sockaddr or NULL.
240 * 'srcaddr' and 'dstaddr' are the same protocol family.
244 * 'task' is a valid task.
246 * requestp != NULL && *requestp == NULL
250 dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
251 isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
252 unsigned int options, unsigned int timeout,
253 isc_task_t *task, isc_taskaction_t action, void *arg,
254 dns_request_t **requestp);
257 dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
258 isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
259 unsigned int options, unsigned int timeout,
260 unsigned int udptimeout, isc_task_t *task,
261 isc_taskaction_t action, void *arg,
262 dns_request_t **requestp);
265 dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
266 isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
267 unsigned int options, unsigned int timeout,
268 unsigned int udptimeout, unsigned int udpretries,
269 isc_task_t *task, isc_taskaction_t action, void *arg,
270 dns_request_t **requestp);
272 * Create and send a request.
276 * 'msgbuf' will be sent to 'destaddr' after setting the id. If the
277 * DNS_REQUESTOPT_TCP option is set, TCP will be used. The request
278 * will timeout after 'timeout' seconds. UDP requests will be resent
279 * at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero.
281 * When the request completes, successfully, due to a timeout, or
282 * because it was canceled, a completion event will be sent to 'task'.
286 * 'msgbuf' is a valid DNS message in compressed wire format.
288 * 'destaddr' is a valid sockaddr.
290 * 'srcaddr' is a valid sockaddr or NULL.
292 * 'srcaddr' and 'dstaddr' are the same protocol family.
296 * 'task' is a valid task.
298 * requestp != NULL && *requestp == NULL
302 dns_request_cancel(dns_request_t *request);
308 * 'request' is a valid request.
312 * If the completion event for 'request' has not yet been sent, it
313 * will be sent, and the result code will be ISC_R_CANCELED.
317 dns_request_getresponse(dns_request_t *request, dns_message_t *message,
318 unsigned int options);
320 * Get the response to 'request' by filling in 'message'.
322 * 'options' is passed to dns_message_parse(). See dns_message_parse()
327 * 'request' is a valid request for which the caller has received the
330 * The result code of the completion event was ISC_R_SUCCESS.
336 * Any result that dns_message_parse() can return.
340 dns_request_usedtcp(dns_request_t *request);
342 * Return whether this query used TCP or not. Setting DNS_REQUESTOPT_TCP
343 * in the call to dns_request_create() will cause the function to return
344 * ISC_TRUE, othewise the result is based on the query message size.
347 * 'request' is a valid request.
350 * ISC_TRUE if TCP was used.
351 * ISC_FALSE if UDP was used.
355 dns_request_destroy(dns_request_t **requestp);
361 * 'request' is a valid request for which the caller has received the
371 #endif /* DNS_REQUEST_H */