request.h 9.99 KB
Newer Older
Bob Halley's avatar
add  
Bob Halley committed
1
/*
Automatic Updater's avatar
Automatic Updater committed
2
 * Copyright (C) 2004-2007, 2009  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.29 2009/01/17 23:47:43 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 50 51
#define DNS_REQUESTOPT_TCP 0x00000001U

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

57 58
ISC_LANG_BEGINDECLS

Bob Halley's avatar
add  
Bob Halley committed
59 60
isc_result_t
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,
Bob Halley's avatar
add  
Bob Halley committed
63 64
		      dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6,
		      dns_requestmgr_t **requestmgrp);
65
/*%<
Bob Halley's avatar
add  
Bob Halley committed
66 67 68 69
 * Create a request manager.
 *
 * Requires:
 *
70
 *\li	'mctx' is a valid memory context.
Bob Halley's avatar
add  
Bob Halley committed
71
 *
72
 *\li	'timermgr' is a valid timer manager.
Bob Halley's avatar
add  
Bob Halley committed
73
 *
74
 *\li	'socketmgr' is a valid socket manager.
Mark Andrews's avatar
Mark Andrews committed
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.
Bob Halley's avatar
add  
Bob Halley committed
79
 *
80
 *\li	'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL.
Bob Halley's avatar
add  
Bob Halley committed
81
 *
82
 *\li	requestmgrp != NULL && *requestmgrp == NULL
Bob Halley's avatar
add  
Bob Halley committed
83 84 85
 *
 * Ensures:
 *
86
 *\li	On success, *requestmgrp is a valid request manager.
Bob Halley's avatar
add  
Bob Halley committed
87 88 89
 *
 * Returns:
 *
90
 *\li	ISC_R_SUCCESS
Bob Halley's avatar
add  
Bob Halley committed
91
 *
92
 *\li	Any other result indicates failure.
Bob Halley's avatar
add  
Bob Halley committed
93 94 95 96 97
 */

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

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

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

void
Mark Andrews's avatar
Mark Andrews committed
148
dns_requestmgr_detach(dns_requestmgr_t **requestmgrp);
149
/*%<
150 151 152 153 154 155
 *	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:
 *
156
 *\li	'*requestmgrp' is a valid requestmgr.
157 158
 *
 * Ensures:
159
 *\li	'*requestmgrp' is NULL.
160
 */
Bob Halley's avatar
add  
Bob Halley committed
161 162 163 164

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

194
/*% See dns_request_createvia3() */
195 196 197 198 199 200 201
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);
202

203
/*% See dns_request_createvia3() */
204 205 206 207
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
208
		       unsigned int timeout, unsigned int udptimeout,
209 210
		       isc_task_t *task, isc_taskaction_t action, void *arg,
		       dns_request_t **requestp);
Michael Graff's avatar
Michael Graff committed
211 212 213 214 215 216 217 218 219

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);
Automatic Updater's avatar
Automatic Updater committed
220
/*%<
221 222 223 224
 * Create and send a request.
 *
 * Notes:
 *
225 226
 *\li	'message' will be rendered and sent to 'address'.  If the
 *	#DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
227
 *	will timeout after 'timeout' seconds.  UDP requests will be resent
Michael Graff's avatar
Michael Graff committed
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 232 233 234
 *	because it was canceled, a completion event will be sent to 'task'.
 *
 * Requires:
 *
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 252 253 254 255 256
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);
257

258
/*% See dns_request_createraw3() */
259 260 261 262
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
263
		       unsigned int udptimeout, isc_task_t *task,
264 265
		       isc_taskaction_t action, void *arg,
		       dns_request_t **requestp);
Michael Graff's avatar
Michael Graff committed
266 267 268 269 270 271 272 273

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);
Automatic Updater's avatar
Automatic Updater committed
274
/*!<
275
 * \brief Create and send a request.
276 277 278
 *
 * Notes:
 *
279 280
 *\li	'msgbuf' will be sent to 'destaddr' after setting the id.  If the
 *	#DNS_REQUESTOPT_TCP option is set, TCP will be used.  The request
281
 *	will timeout after 'timeout' seconds.   UDP requests will be resent
Michael Graff's avatar
Michael Graff committed
282
 *	at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero.
Automatic Updater's avatar
Automatic Updater committed
283
 *
284
 *\li	When the request completes, successfully, due to a timeout, or
285 286 287 288
 *	because it was canceled, a completion event will be sent to 'task'.
 *
 * Requires:
 *
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
Bob Halley's avatar
add  
Bob Halley committed
305
dns_request_cancel(dns_request_t *request);
306
/*%<
Bob Halley's avatar
add  
Bob Halley committed
307 308 309 310
 * Cancel 'request'.
 *
 * Requires:
 *
311
 *\li	'request' is a valid request.
Bob Halley's avatar
add  
Bob Halley committed
312 313 314
 *
 * Ensures:
 *
315
 *\li	If the completion event for 'request' has not yet been sent, it
Bob Halley's avatar
add  
Bob Halley committed
316 317 318 319
 *	will be sent, and the result code will be ISC_R_CANCELED.
 */

isc_result_t
320
dns_request_getresponse(dns_request_t *request, dns_message_t *message,
321
			unsigned int options);
322
/*%<
323 324
 * Get the response to 'request' by filling in 'message'.
 *
325
 * 'options' is passed to dns_message_parse().  See dns_message_parse()
326
 * for more details.
Bob Halley's avatar
add  
Bob Halley committed
327 328 329
 *
 * Requires:
 *
330
 *\li	'request' is a valid request for which the caller has received the
Bob Halley's avatar
add  
Bob Halley committed
331 332
 *	completion event.
 *
333
 *\li	The result code of the completion event was #ISC_R_SUCCESS.
Bob Halley's avatar
add  
Bob Halley committed
334 335 336
 *
 * Returns:
 *
337
 *\li	ISC_R_SUCCESS
Bob Halley's avatar
add  
Bob Halley committed
338
 *
339
 *\li	Any result that dns_message_parse() can return.
Bob Halley's avatar
add  
Bob Halley committed
340 341
 */

342 343
isc_boolean_t
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
Francis Dupont's avatar
Francis Dupont committed
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 354
 *\li	ISC_TRUE	if TCP was used.
 *\li	ISC_FALSE	if UDP was used.
355 356
 */

Bob Halley's avatar
add  
Bob Halley committed
357 358
void
dns_request_destroy(dns_request_t **requestp);
359
/*%<
Bob Halley's avatar
add  
Bob Halley committed
360 361 362 363
 * Destroy 'request'.
 *
 * Requires:
 *
364
 *\li	'request' is a valid request for which the caller has received the
Bob Halley's avatar
add  
Bob Halley committed
365 366 367 368
 *	completion event.
 *
 * Ensures:
 *
369
 *\li	*requestp == NULL
Bob Halley's avatar
add  
Bob Halley committed
370 371 372 373 374
 */

ISC_LANG_ENDDECLS

#endif /* DNS_REQUEST_H */