request.h 11.4 KB
Newer Older
Bob Halley's avatar
add  
Bob Halley committed
1
/*
2
 * Copyright (C) 2004-2007, 2009, 2010, 2013-2015  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 2000-2002  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
Bob Halley's avatar
add  
Bob Halley committed
6 7
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
Bob Halley's avatar
add  
Bob Halley committed
16 17
 */

Automatic Updater's avatar
Automatic Updater committed
18
/* $Id: request.h,v 1.31 2010/03/04 23:50:34 tbox Exp $ */
David Lawrence's avatar
David Lawrence committed
19

Bob Halley's avatar
add  
Bob Halley committed
20 21 22 23 24 25 26
#ifndef DNS_REQUEST_H
#define DNS_REQUEST_H 1

/*****
 ***** Module Info
 *****/

27
/*! \file dns/request.h
Bob Halley's avatar
add  
Bob Halley committed
28
 *
29
 * \brief
Bob Halley's avatar
add  
Bob Halley committed
30 31 32 33
 * The request module provides simple request/response services useful for
 * sending SOA queries, DNS Notify messages, and dynamic update requests.
 *
 * MP:
34
 *\li	The module ensures appropriate synchronization of data structures it
Bob Halley's avatar
add  
Bob Halley committed
35 36 37
 *	creates and manipulates.
 *
 * Resources:
38
 *\li	TBS
Bob Halley's avatar
add  
Bob Halley committed
39 40
 *
 * Security:
41
 *\li	No anticipated impact.
Bob Halley's avatar
add  
Bob Halley committed
42 43 44 45 46 47 48
 */

#include <isc/lang.h>
#include <isc/event.h>

#include <dns/types.h>

Mark Andrews's avatar
Mark Andrews committed
49
#define DNS_REQUESTOPT_TCP 0x00000001U
50
#define DNS_REQUESTOPT_CASE 0x00000002U
51
#define DNS_REQUESTOPT_FIXEDID 0x00000004U
52
#define DNS_REQUESTOPT_SHARE 0x00000008U
Mark Andrews's avatar
Mark Andrews committed
53 54

typedef struct dns_requestevent {
Automatic Updater's avatar
Automatic Updater committed
55
	ISC_EVENT_COMMON(struct dns_requestevent);
Mark Andrews's avatar
Mark Andrews committed
56 57 58 59
	isc_result_t result;
	dns_request_t *request;
} dns_requestevent_t;

60 61
ISC_LANG_BEGINDECLS

Bob Halley's avatar
add  
Bob Halley committed
62 63
isc_result_t
dns_requestmgr_create(isc_mem_t *mctx, isc_timermgr_t *timermgr,
64
		      isc_socketmgr_t *socketmgr, isc_taskmgr_t *taskmgr,
65
		      dns_dispatchmgr_t *dispatchmgr,
Bob Halley's avatar
add  
Bob Halley committed
66 67
		      dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6,
		      dns_requestmgr_t **requestmgrp);
68
/*%<
Bob Halley's avatar
add  
Bob Halley committed
69 70 71 72
 * Create a request manager.
 *
 * Requires:
 *
73
 *\li	'mctx' is a valid memory context.
Bob Halley's avatar
add  
Bob Halley committed
74
 *
75
 *\li	'timermgr' is a valid timer manager.
Bob Halley's avatar
add  
Bob Halley committed
76
 *
77
 *\li	'socketmgr' is a valid socket manager.
Mark Andrews's avatar
Mark Andrews committed
78
 *
79
 *\li	'taskmgr' is a valid task manager.
80
 *
81
 *\li	'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL.
Bob Halley's avatar
add  
Bob Halley committed
82
 *
83
 *\li	'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
Bob Halley's avatar
add  
Bob Halley committed
84
 *
85
 *\li	requestmgrp != NULL && *requestmgrp == NULL
Bob Halley's avatar
add  
Bob Halley committed
86 87 88
 *
 * Ensures:
 *
89
 *\li	On success, *requestmgrp is a valid request manager.
Bob Halley's avatar
add  
Bob Halley committed
90 91 92
 *
 * Returns:
 *
93
 *\li	ISC_R_SUCCESS
Bob Halley's avatar
add  
Bob Halley committed
94
 *
95
 *\li	Any other result indicates failure.
Bob Halley's avatar
add  
Bob Halley committed
96 97 98 99 100
 */

void
dns_requestmgr_whenshutdown(dns_requestmgr_t *requestmgr, isc_task_t *task,
			    isc_event_t **eventp);
101
/*%<
Bob Halley's avatar
add  
Bob Halley committed
102 103 104 105
 * Send '*eventp' to 'task' when 'requestmgr' has completed shutdown.
 *
 * Notes:
 *
106
 *\li	It is not safe to detach the last reference to 'requestmgr' until
Bob Halley's avatar
add  
Bob Halley committed
107 108 109 110
 *	shutdown is complete.
 *
 * Requires:
 *
111
 *\li	'requestmgr' is a valid request manager.
Bob Halley's avatar
add  
Bob Halley committed
112
 *
113
 *\li	'task' is a valid task.
Bob Halley's avatar
add  
Bob Halley committed
114
 *
115
 *\li	*eventp is a valid event.
Bob Halley's avatar
add  
Bob Halley committed
116 117 118
 *
 * Ensures:
 *
119
 *\li	*eventp == NULL.
Bob Halley's avatar
add  
Bob Halley committed
120 121 122 123
 */

void
dns_requestmgr_shutdown(dns_requestmgr_t *requestmgr);
124
/*%<
Bob Halley's avatar
add  
Bob Halley committed
125 126 127 128
 * Start the shutdown process for 'requestmgr'.
 *
 * Notes:
 *
129
 *\li	This call has no effect if the request manager is already shutting
Bob Halley's avatar
add  
Bob Halley committed
130 131 132 133
 *	down.
 *
 * Requires:
 *
134
 *\li	'requestmgr' is a valid requestmgr.
Bob Halley's avatar
add  
Bob Halley committed
135 136 137
 */

void
Mark Andrews's avatar
Mark Andrews committed
138
dns_requestmgr_attach(dns_requestmgr_t *source, dns_requestmgr_t **targetp);
139
/*%<
140 141 142 143 144
 *	Attach to the request manager.  dns_requestmgr_shutdown() must not
 *	have been called on 'source' prior to calling dns_requestmgr_attach().
 *
 * Requires:
 *
145
 *\li	'source' is a valid requestmgr.
146
 *
147
 *\li	'targetp' to be non NULL and '*targetp' to be NULL.
148
 */
Bob Halley's avatar
add  
Bob Halley committed
149 150

void
Mark Andrews's avatar
Mark Andrews committed
151
dns_requestmgr_detach(dns_requestmgr_t **requestmgrp);
152
/*%<
153 154 155 156 157 158
 *	Detach from the given requestmgr.  If this is the final detach
 *	requestmgr will be destroyed.  dns_requestmgr_shutdown() must
 *	be called before the final detach.
 *
 * Requires:
 *
159
 *\li	'*requestmgrp' is a valid requestmgr.
160 161
 *
 * Ensures:
162
 *\li	'*requestmgrp' is NULL.
163
 */
Bob Halley's avatar
add  
Bob Halley committed
164 165 166 167

isc_result_t
dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message,
		   isc_sockaddr_t *address, unsigned int options,
168
		   dns_tsigkey_t *key,
Bob Halley's avatar
add  
Bob Halley committed
169 170 171
		   unsigned int timeout, isc_task_t *task,
		   isc_taskaction_t action, void *arg,
		   dns_request_t **requestp);
172
/*%<
Bob Halley's avatar
add  
Bob Halley committed
173 174 175 176
 * Create and send a request.
 *
 * Notes:
 *
177
 *\li	'message' will be rendered and sent to 'address'.  If the
178 179 180
 *	#DNS_REQUESTOPT_TCP option is set, TCP will be used,
 *	#DNS_REQUESTOPT_SHARE option is set too, connecting TCP
 *	(vs. connected) will be shared too.  The request
Bob Halley's avatar
add  
Bob Halley committed
181 182
 *	will timeout after 'timeout' seconds.
 *
183 184 185
 *\li	If the #DNS_REQUESTOPT_CASE option is set, use case sensitive
 *	compression.
 *
186
 *\li	When the request completes, successfully, due to a timeout, or
Bob Halley's avatar
add  
Bob Halley committed
187 188 189 190
 *	because it was canceled, a completion event will be sent to 'task'.
 *
 * Requires:
 *
191
 *\li	'message' is a valid DNS message.
Bob Halley's avatar
add  
Bob Halley committed
192
 *
193
 *\li	'address' is a valid sockaddr.
Bob Halley's avatar
add  
Bob Halley committed
194
 *
195
 *\li	'timeout' > 0
Bob Halley's avatar
add  
Bob Halley committed
196
 *
197
 *\li	'task' is a valid task.
Bob Halley's avatar
add  
Bob Halley committed
198
 *
199
 *\li	requestp != NULL && *requestp == NULL
Bob Halley's avatar
add  
Bob Halley committed
200 201
 */

Evan Hunt's avatar
Evan Hunt committed
202
/*% See dns_request_createvia4() */
203 204 205 206 207 208 209
isc_result_t
dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message,
		      isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
		      unsigned int options, dns_tsigkey_t *key,
		      unsigned int timeout, isc_task_t *task,
		      isc_taskaction_t action, void *arg,
		      dns_request_t **requestp);
210

Evan Hunt's avatar
Evan Hunt committed
211
/*% See dns_request_createvia4() */
212 213 214 215
isc_result_t
dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message,
		       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
		       unsigned int options, dns_tsigkey_t *key,
Michael Graff's avatar
Michael Graff committed
216
		       unsigned int timeout, unsigned int udptimeout,
217 218
		       isc_task_t *task, isc_taskaction_t action, void *arg,
		       dns_request_t **requestp);
Michael Graff's avatar
Michael Graff committed
219

Evan Hunt's avatar
Evan Hunt committed
220
/*% See dns_request_createvia4() */
Michael Graff's avatar
Michael Graff committed
221 222 223 224 225 226 227 228
isc_result_t
dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message,
		       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
		       unsigned int options, dns_tsigkey_t *key,
		       unsigned int timeout, unsigned int udptimeout,
		       unsigned int udpretries, isc_task_t *task,
		       isc_taskaction_t action, void *arg,
		       dns_request_t **requestp);
Evan Hunt's avatar
Evan Hunt committed
229 230 231 232 233 234

isc_result_t
dns_request_createvia4(dns_requestmgr_t *requestmgr, dns_message_t *message,
		       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
		       isc_dscp_t dscp, unsigned int options,
		       dns_tsigkey_t *key, unsigned int timeout,
Tinderbox User's avatar
Tinderbox User committed
235
		       unsigned int udptimeout, unsigned int udpretries,
Evan Hunt's avatar
Evan Hunt committed
236 237
		       isc_task_t *task, isc_taskaction_t action, void *arg,
		       dns_request_t **requestp);
Automatic Updater's avatar
Automatic Updater committed
238
/*%<
239 240 241 242
 * Create and send a request.
 *
 * Notes:
 *
243
 *\li	'message' will be rendered and sent to 'address'.  If the
244 245 246
 *	#DNS_REQUESTOPT_TCP option is set, TCP will be used,
 *	#DNS_REQUESTOPT_SHARE option is set too, connecting TCP
 *	(vs. connected) will be shared too.  The request
247
 *	will timeout after 'timeout' seconds.  UDP requests will be resent
Michael Graff's avatar
Michael Graff committed
248
 *	at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero.
249
 *
250 251 252
 *\li	If the #DNS_REQUESTOPT_CASE option is set, use case sensitive
 *	compression.
 *
253
 *\li	When the request completes, successfully, due to a timeout, or
254 255 256 257
 *	because it was canceled, a completion event will be sent to 'task'.
 *
 * Requires:
 *
258
 *\li	'message' is a valid DNS message.
259
 *
260
 *\li	'dstaddr' is a valid sockaddr.
261
 *
262
 *\li	'srcaddr' is a valid sockaddr or NULL.
263
 *
264
 *\li	'srcaddr' and 'dstaddr' are the same protocol family.
265
 *
266
 *\li	'timeout' > 0
267
 *
268
 *\li	'task' is a valid task.
269
 *
270
 *\li	requestp != NULL && *requestp == NULL
271 272
 */

Evan Hunt's avatar
Evan Hunt committed
273
/*% See dns_request_createraw4() */
274 275 276 277 278 279
isc_result_t
dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
		      isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
		      unsigned int options, unsigned int timeout,
		      isc_task_t *task, isc_taskaction_t action, void *arg,
		      dns_request_t **requestp);
280

Evan Hunt's avatar
Evan Hunt committed
281
/*% See dns_request_createraw4() */
282 283 284 285
isc_result_t
dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
		       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
		       unsigned int options, unsigned int timeout,
Michael Graff's avatar
Michael Graff committed
286
		       unsigned int udptimeout, isc_task_t *task,
287 288
		       isc_taskaction_t action, void *arg,
		       dns_request_t **requestp);
Michael Graff's avatar
Michael Graff committed
289

Evan Hunt's avatar
Evan Hunt committed
290
/*% See dns_request_createraw4() */
Michael Graff's avatar
Michael Graff committed
291 292 293 294 295 296 297
isc_result_t
dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
		       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
		       unsigned int options, unsigned int timeout,
		       unsigned int udptimeout, unsigned int udpretries,
		       isc_task_t *task, isc_taskaction_t action, void *arg,
		       dns_request_t **requestp);
Evan Hunt's avatar
Evan Hunt committed
298 299 300 301 302 303 304 305 306

isc_result_t
dns_request_createraw4(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf,
		       isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr,
		       isc_dscp_t dscp, unsigned int options,
		       unsigned int timeout, unsigned int udptimeout,
		       unsigned int udpretries, isc_task_t *task,
		       isc_taskaction_t action, void *arg,
		       dns_request_t **requestp);
Automatic Updater's avatar
Automatic Updater committed
307
/*!<
308
 * \brief Create and send a request.
309 310 311
 *
 * Notes:
 *
312
 *\li	'msgbuf' will be sent to 'destaddr' after setting the id.  If the
313 314 315
 *	#DNS_REQUESTOPT_TCP option is set, TCP will be used,
 *	#DNS_REQUESTOPT_SHARE option is set too, connecting TCP
 *	(vs. connected) will be shared too.  The request
316
 *	will timeout after 'timeout' seconds.   UDP requests will be resent
Michael Graff's avatar
Michael Graff committed
317
 *	at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero.
Automatic Updater's avatar
Automatic Updater committed
318
 *
319
 *\li	When the request completes, successfully, due to a timeout, or
320 321 322 323
 *	because it was canceled, a completion event will be sent to 'task'.
 *
 * Requires:
 *
324
 *\li	'msgbuf' is a valid DNS message in compressed wire format.
325
 *
326
 *\li	'destaddr' is a valid sockaddr.
327
 *
328
 *\li	'srcaddr' is a valid sockaddr or NULL.
329
 *
330
 *\li	'srcaddr' and 'dstaddr' are the same protocol family.
331
 *
332
 *\li	'timeout' > 0
333
 *
334
 *\li	'task' is a valid task.
335
 *
336
 *\li	requestp != NULL && *requestp == NULL
337 338
 */

339
void
Bob Halley's avatar
add  
Bob Halley committed
340
dns_request_cancel(dns_request_t *request);
341
/*%<
Bob Halley's avatar
add  
Bob Halley committed
342 343 344 345
 * Cancel 'request'.
 *
 * Requires:
 *
346
 *\li	'request' is a valid request.
Bob Halley's avatar
add  
Bob Halley committed
347 348 349
 *
 * Ensures:
 *
350
 *\li	If the completion event for 'request' has not yet been sent, it
Bob Halley's avatar
add  
Bob Halley committed
351 352 353 354
 *	will be sent, and the result code will be ISC_R_CANCELED.
 */

isc_result_t
355
dns_request_getresponse(dns_request_t *request, dns_message_t *message,
356
			unsigned int options);
357
/*%<
358 359
 * Get the response to 'request' by filling in 'message'.
 *
360
 * 'options' is passed to dns_message_parse().  See dns_message_parse()
361
 * for more details.
Bob Halley's avatar
add  
Bob Halley committed
362 363 364
 *
 * Requires:
 *
365
 *\li	'request' is a valid request for which the caller has received the
Bob Halley's avatar
add  
Bob Halley committed
366 367
 *	completion event.
 *
368
 *\li	The result code of the completion event was #ISC_R_SUCCESS.
Bob Halley's avatar
add  
Bob Halley committed
369 370 371
 *
 * Returns:
 *
372
 *\li	ISC_R_SUCCESS
Bob Halley's avatar
add  
Bob Halley committed
373
 *
374
 *\li	Any result that dns_message_parse() can return.
Bob Halley's avatar
add  
Bob Halley committed
375 376
 */

377 378
isc_boolean_t
dns_request_usedtcp(dns_request_t *request);
379 380
/*%<
 * Return whether this query used TCP or not.  Setting #DNS_REQUESTOPT_TCP
381
 * in the call to dns_request_create() will cause the function to return
Francis Dupont's avatar
Francis Dupont committed
382
 * #ISC_TRUE, otherwise the result is based on the query message size.
383 384
 *
 * Requires:
385
 *\li	'request' is a valid request.
386 387
 *
 * Returns:
388 389
 *\li	ISC_TRUE	if TCP was used.
 *\li	ISC_FALSE	if UDP was used.
390 391
 */

Bob Halley's avatar
add  
Bob Halley committed
392 393
void
dns_request_destroy(dns_request_t **requestp);
394
/*%<
Bob Halley's avatar
add  
Bob Halley committed
395 396 397 398
 * Destroy 'request'.
 *
 * Requires:
 *
399
 *\li	'request' is a valid request for which the caller has received the
Bob Halley's avatar
add  
Bob Halley committed
400 401 402 403
 *	completion event.
 *
 * Ensures:
 *
404
 *\li	*requestp == NULL
Bob Halley's avatar
add  
Bob Halley committed
405 406 407 408 409
 */

ISC_LANG_ENDDECLS

#endif /* DNS_REQUEST_H */