dispatch.h 15.7 KB
Newer Older
Michael Graff's avatar
Michael Graff committed
1
/*
Mark Andrews's avatar
Mark Andrews committed
2
 * Copyright (C) 2004-2009, 2011-2014  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 1999-2003  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
Michael Graff's avatar
Michael Graff 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.
Michael Graff's avatar
Michael Graff committed
16 17
 */

Automatic Updater's avatar
Automatic Updater committed
18
/* $Id: dispatch.h,v 1.64 2011/07/28 23:47:58 tbox Exp $ */
David Lawrence's avatar
David Lawrence committed
19

20 21
#ifndef DNS_DISPATCH_H
#define DNS_DISPATCH_H 1
Michael Graff's avatar
Michael Graff committed
22 23 24 25 26

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

27
/*! \file dns/dispatch.h
28
 * \brief
29 30
 * DNS Dispatch Management
 * 	Shared UDP and single-use TCP dispatches for queries and responses.
Michael Graff's avatar
Michael Graff committed
31 32 33
 *
 * MP:
 *
34
 *\li     	All locking is performed internally to each dispatch.
35
 * 	Restrictions apply to dns_dispatch_removeresponse().
Michael Graff's avatar
Michael Graff committed
36 37 38 39 40 41 42
 *
 * Reliability:
 *
 * Resources:
 *
 * Security:
 *
43
 *\li	Depends on the isc_socket_t and dns_message_t for prevention of
Michael Graff's avatar
Michael Graff committed
44 45 46 47
 *	buffer overruns.
 *
 * Standards:
 *
48
 *\li	None.
Michael Graff's avatar
Michael Graff committed
49 50 51 52 53 54 55 56
 */

/***
 *** Imports
 ***/

#include <isc/buffer.h>
#include <isc/lang.h>
57
#include <isc/mutex.h>
Bob Halley's avatar
Bob Halley committed
58
#include <isc/socket.h>
59
#include <isc/types.h>
Michael Graff's avatar
Michael Graff committed
60 61 62 63 64

#include <dns/types.h>

ISC_LANG_BEGINDECLS

65
/*%
66
 * This event is sent to a task when a response comes in.
Michael Graff's avatar
Michael Graff committed
67 68 69 70 71 72 73 74 75 76 77 78 79 80
 * No part of this structure should ever be modified by the caller,
 * other than parts of the buffer.  The holy parts of the buffer are
 * the base and size of the buffer.  All other parts of the buffer may
 * be used.  On event delivery the used region contains the packet.
 *
 * "id" is the received message id,
 *
 * "addr" is the host that sent it to us,
 *
 * "buffer" holds state on the received data.
 *
 * The "free" routine for this event will clean up itself as well as
 * any buffer space allocated from common pools.
 */
Bob Halley's avatar
Bob Halley committed
81

Michael Graff's avatar
Michael Graff committed
82
struct dns_dispatchevent {
83 84 85 86 87 88 89
	ISC_EVENT_COMMON(dns_dispatchevent_t);	/*%< standard event common */
	isc_result_t		result;		/*%< result code */
	isc_int32_t		id;		/*%< message id */
	isc_sockaddr_t		addr;		/*%< address recv'd from */
	struct in6_pktinfo	pktinfo;	/*%< reply info for v6 */
	isc_buffer_t	        buffer;		/*%< data buffer */
	isc_uint32_t		attributes;	/*%< mirrored from socket.h */
Michael Graff's avatar
Michael Graff committed
90 91
};

92 93 94 95 96 97 98 99 100 101 102 103
/*%
 * This is a set of one or more dispatches which can be retrieved
 * round-robin fashion.
 */
struct dns_dispatchset {
	isc_mem_t		*mctx;
	dns_dispatch_t		**dispatches;
	int			ndisp;
	int			cur;
	isc_mutex_t		lock;
};

104 105
/*@{*/
/*%
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120
 * Attributes for added dispatchers.
 *
 * Values with the mask 0xffff0000 are application defined.
 * Values with the mask 0x0000ffff are library defined.
 *
 * Insane values (like setting both TCP and UDP) are not caught.  Don't
 * do that.
 *
 * _PRIVATE
 *	The dispatcher cannot be shared.
 *
 * _TCP, _UDP
 *	The dispatcher is a TCP or UDP socket.
 *
 * _IPV4, _IPV6
121
 *	The dispatcher uses an IPv4 or IPv6 socket.
122
 *
123 124
 * _NOLISTEN
 *	The dispatcher should not listen on the socket.
125
 *
126
 * _MAKEQUERY
127 128
 *	The dispatcher can be used to issue queries to other servers, and
 *	accept replies from them.
129 130
 *
 * _RANDOMPORT
131 132 133 134 135
 *	Previously used to indicate that the port of a dispatch UDP must be
 *	chosen randomly.  This behavior now always applies and the attribute
 *	is obsoleted.
 *
 * _EXCLUSIVE
Automatic Updater's avatar
Automatic Updater committed
136
 *	A separate socket will be used on-demand for each transaction.
137 138 139 140 141 142
 */
#define DNS_DISPATCHATTR_PRIVATE	0x00000001U
#define DNS_DISPATCHATTR_TCP		0x00000002U
#define DNS_DISPATCHATTR_UDP		0x00000004U
#define DNS_DISPATCHATTR_IPV4		0x00000008U
#define DNS_DISPATCHATTR_IPV6		0x00000010U
143
#define DNS_DISPATCHATTR_NOLISTEN	0x00000020U
144
#define DNS_DISPATCHATTR_MAKEQUERY	0x00000040U
145
#define DNS_DISPATCHATTR_CONNECTED	0x00000080U
146 147
/*#define DNS_DISPATCHATTR_RANDOMPORT	0x00000100U*/
#define DNS_DISPATCHATTR_EXCLUSIVE	0x00000200U
148
/*@}*/
149

Michael Graff's avatar
Michael Graff committed
150
isc_result_t
151 152
dns_dispatchmgr_create(isc_mem_t *mctx, isc_entropy_t *entropy,
		       dns_dispatchmgr_t **mgrp);
153
/*%<
154 155 156
 * Creates a new dispatchmgr object.
 *
 * Requires:
157
 *\li	"mctx" be a valid memory context.
158
 *
159
 *\li	mgrp != NULL && *mgrp == NULL
160
 *
161
 *\li	"entropy" may be NULL, in which case an insecure random generator
162 163 164
 *	will be used.  If it is non-NULL, it must be a valid entropy
 *	source.
 *
165
 * Returns:
166
 *\li	ISC_R_SUCCESS	-- all ok
167
 *
168
 *\li	anything else	-- failure
169 170 171 172 173
 */


void
dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp);
174
/*%<
175 176 177 178
 * Destroys the dispatchmgr when it becomes empty.  This could be
 * immediately.
 *
 * Requires:
179
 *\li	mgrp != NULL && *mgrp is a valid dispatchmgr.
180 181 182
 */


183 184
void
dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole);
185
/*%<
186 187
 * Sets the dispatcher's "blackhole list," a list of addresses that will
 * be ignored by all dispatchers created by the dispatchmgr.
188 189
 *
 * Requires:
190 191
 * \li	mgrp is a valid dispatchmgr
 * \li	blackhole is a valid acl
192 193 194
 */


195 196
dns_acl_t *
dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr);
197
/*%<
198 199
 * Gets a pointer to the dispatcher's current blackhole list,
 * without incrementing its reference count.
200 201
 *
 * Requires:
202
 *\li 	mgr is a valid dispatchmgr
203
 * Returns:
204
 *\li	A pointer to the current blackhole list, or NULL.
205 206
 */

207 208
void
dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr,
Automatic Updater's avatar
Automatic Updater committed
209
				 dns_portlist_t *portlist);
210
/*%<
211
 * This function is deprecated.  Use dns_dispatchmgr_setavailports() instead.
212 213
 *
 * Requires:
214
 *\li	mgr is a valid dispatchmgr
215 216 217 218
 */

dns_portlist_t *
dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr);
219
/*%<
220
 * This function is deprecated and always returns NULL.
221 222
 *
 * Requires:
223
 *\li	mgr is a valid dispatchmgr
224 225
 */

226 227 228 229 230 231 232 233 234 235 236 237
isc_result_t
dns_dispatchmgr_setavailports(dns_dispatchmgr_t *mgr, isc_portset_t *v4portset,
			      isc_portset_t *v6portset);
/*%<
 * Sets a list of UDP ports that can be used for outgoing UDP messages.
 *
 * Requires:
 *\li	mgr is a valid dispatchmgr
 *\li	v4portset is NULL or a valid port set
 *\li	v6portset is NULL or a valid port set
 */

238
void
239
dns_dispatchmgr_setstats(dns_dispatchmgr_t *mgr, isc_stats_t *stats);
240 241 242 243 244 245 246 247 248 249 250 251
/*%<
 * Sets statistics counter for the dispatchmgr.  This function is expected to
 * be called only on zone creation (when necessary).
 * Once installed, it cannot be removed or replaced.  Also, there is no
 * interface to get the installed stats from the zone; the caller must keep the
 * stats to reference (e.g. dump) it later.
 *
 * Requires:
 *\li	mgr is a valid dispatchmgr with no managed dispatch.
 *\li	stats is a valid statistics supporting resolver statistics counters
 *	(see dns/stats.h).
 */
252 253

isc_result_t
254 255 256
dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
		    isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
		    unsigned int buffersize,
257
		    unsigned int maxbuffers, unsigned int maxrequests,
258
		    unsigned int buckets, unsigned int increment,
259
		    unsigned int attributes, unsigned int mask,
260
		    dns_dispatch_t **dispp);
261 262 263 264 265 266 267 268 269

isc_result_t
dns_dispatch_getudp_dup(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
		    isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
		    unsigned int buffersize,
		    unsigned int maxbuffers, unsigned int maxrequests,
		    unsigned int buckets, unsigned int increment,
		    unsigned int attributes, unsigned int mask,
		    dns_dispatch_t **dispp, dns_dispatch_t *dup);
270
/*%<
271
 * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
272
 * otherwise create a new UDP dispatch.
273 274
 *
 * Requires:
275
 *\li	All pointer parameters be valid for their respective types.
276
 *
277
 *\li	dispp != NULL && *disp == NULL
278
 *
279
 *\li	512 <= buffersize <= 64k
280
 *
281
 *\li	maxbuffers > 0
282
 *
283
 *\li	buckets < 2097169
284
 *
285
 *\li	increment > buckets
286
 *
287
 *\li	(attributes & DNS_DISPATCHATTR_TCP) == 0
288 289
 *
 * Returns:
290
 *\li	ISC_R_SUCCESS	-- success.
291
 *
292
 *\li	Anything else	-- failure.
293
 */
294 295 296 297 298 299 300

isc_result_t
dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
		       isc_taskmgr_t *taskmgr, unsigned int buffersize,
		       unsigned int maxbuffers, unsigned int maxrequests,
		       unsigned int buckets, unsigned int increment,
		       unsigned int attributes, dns_dispatch_t **dispp);
301 302
isc_result_t
dns_dispatch_createtcp2(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
Mark Andrews's avatar
Mark Andrews committed
303 304 305 306 307
			isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
			isc_sockaddr_t *destaddr, unsigned int buffersize,
			unsigned int maxbuffers, unsigned int maxrequests,
			unsigned int buckets, unsigned int increment,
			unsigned int attributes, dns_dispatch_t **dispp);
308
/*%<
309
 * Create a new dns_dispatch and attach it to the provided isc_socket_t.
Michael Graff's avatar
Michael Graff committed
310
 *
311
 * For all dispatches, "buffersize" is the maximum packet size we will
Michael Graff's avatar
Michael Graff committed
312
 * accept.
Michael Graff's avatar
Michael Graff committed
313 314 315 316 317
 *
 * "maxbuffers" and "maxrequests" control the number of buffers in the
 * overall system and the number of buffers which can be allocated to
 * requests.
 *
318 319 320 321
 * "buckets" is the number of buckets to use, and should be prime.
 *
 * "increment" is used in a collision avoidance function, and needs to be
 * a prime > buckets, and not 2.
Michael Graff's avatar
Michael Graff committed
322
 *
Michael Graff's avatar
Michael Graff committed
323 324
 * Requires:
 *
325
 *\li	mgr is a valid dispatch manager.
Michael Graff's avatar
Michael Graff committed
326
 *
327
 *\li	sock is a valid.
Michael Graff's avatar
Michael Graff committed
328
 *
329
 *\li	task is a valid task that can be used internally to this dispatcher.
Michael Graff's avatar
Michael Graff committed
330
 *
331
 * \li	512 <= buffersize <= 64k
Michael Graff's avatar
Michael Graff committed
332
 *
333
 *\li	maxbuffers > 0.
Michael Graff's avatar
Michael Graff committed
334
 *
335
 *\li	maxrequests <= maxbuffers.
Michael Graff's avatar
Michael Graff committed
336
 *
337
 *\li	buckets < 2097169 (the next prime after 65536 * 32)
338
 *
339
 *\li	increment > buckets (and prime).
340
 *
341 342
 *\li	attributes includes #DNS_DISPATCHATTR_TCP and does not include
 *	#DNS_DISPATCHATTR_UDP.
343 344
 *
 * Returns:
345
 *\li	ISC_R_SUCCESS	-- success.
346
 *
347
 *\li	Anything else	-- failure.
Michael Graff's avatar
Michael Graff committed
348 349 350
 */

void
351
dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
352
/*%<
353 354 355
 * Attach to a dispatch handle.
 *
 * Requires:
356
 *\li	disp is valid.
357
 *
358
 *\li	dispp != NULL && *dispp == NULL
359 360 361 362
 */

void
dns_dispatch_detach(dns_dispatch_t **dispp);
363
/*%<
364
 * Detaches from the dispatch.
Michael Graff's avatar
Michael Graff committed
365 366
 *
 * Requires:
367
 *\li	dispp != NULL and *dispp be a valid dispatch.
Michael Graff's avatar
Michael Graff committed
368 369
 */

370
void
371
dns_dispatch_starttcp(dns_dispatch_t *disp);
372
/*%<
Mark Andrews's avatar
Mark Andrews committed
373
 * Start processing of a TCP dispatch once the socket connects.
374 375
 *
 * Requires:
376
 *\li	'disp' is valid.
377
 */
378

379 380
isc_result_t
dns_dispatch_gettcp(dns_dispatchmgr_t *mgr, isc_sockaddr_t *destaddr,
Mark Andrews's avatar
Mark Andrews committed
381
		    isc_sockaddr_t *localaddr, dns_dispatch_t **dispp);
382 383 384 385 386
/*
 * Attempt to connect to a existing TCP connection.
 */


387 388 389 390 391 392
isc_result_t
dns_dispatch_addresponse2(dns_dispatch_t *disp, isc_sockaddr_t *dest,
			  isc_task_t *task, isc_taskaction_t action, void *arg,
			  isc_uint16_t *idp, dns_dispentry_t **resp,
			  isc_socketmgr_t *sockmgr);

Michael Graff's avatar
Michael Graff committed
393
isc_result_t
Michael Graff's avatar
Michael Graff committed
394
dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest,
395
			 isc_task_t *task, isc_taskaction_t action, void *arg,
Michael Graff's avatar
Michael Graff committed
396
			 isc_uint16_t *idp, dns_dispentry_t **resp);
397
/*%<
398
 * Add a response entry for this dispatch.
Michael Graff's avatar
Michael Graff committed
399
 *
Michael Graff's avatar
Michael Graff committed
400 401
 * "*idp" is filled in with the assigned message ID, and *resp is filled in
 * to contain the magic token used to request event flow stop.
Michael Graff's avatar
Michael Graff committed
402
 *
Michael Graff's avatar
Michael Graff committed
403 404 405
 * Arranges for the given task to get a callback for response packets.  When
 * the event is delivered, it must be returned using dns_dispatch_freeevent()
 * or through dns_dispatch_removeresponse() for another to be delivered.
Michael Graff's avatar
Michael Graff committed
406 407
 *
 * Requires:
408
 *\li	"idp" be non-NULL.
Michael Graff's avatar
Michael Graff committed
409
 *
410
 *\li	"task" "action" and "arg" be set as appropriate.
Michael Graff's avatar
Michael Graff committed
411
 *
412
 *\li	"dest" be non-NULL and valid.
Michael Graff's avatar
Michael Graff committed
413
 *
414
 *\li	"resp" be non-NULL and *resp be NULL
Michael Graff's avatar
Michael Graff committed
415
 *
416 417 418 419
 *\li	"sockmgr" be NULL or a valid socket manager.  If 'disp' has
 *	the DNS_DISPATCHATTR_EXCLUSIVE attribute, this must not be NULL,
 *	which also means dns_dispatch_addresponse() cannot be used.
 *
Michael Graff's avatar
Michael Graff committed
420 421
 * Ensures:
 *
422
 *\li	&lt;id, dest> is a unique tuple.  That means incoming messages
Michael Graff's avatar
Michael Graff committed
423 424 425
 *	are identifiable.
 *
 * Returns:
Michael Graff's avatar
Michael Graff committed
426
 *
427 428 429
 *\li	ISC_R_SUCCESS		-- all is well.
 *\li	ISC_R_NOMEMORY		-- memory could not be allocated.
 *\li	ISC_R_NOMORE		-- no more message ids can be allocated
Michael Graff's avatar
Michael Graff committed
430
 *				   for this destination.
Michael Graff's avatar
Michael Graff committed
431 432
 */

433

Michael Graff's avatar
Michael Graff committed
434
void
435
dns_dispatch_removeresponse(dns_dispentry_t **resp,
Michael Graff's avatar
Michael Graff committed
436
			    dns_dispatchevent_t **sockevent);
437
/*%<
Michael Graff's avatar
Michael Graff committed
438
 * Stops the flow of responses for the provided id and destination.
439
 * If "sockevent" is non-NULL, the dispatch event and associated buffer is
Michael Graff's avatar
Michael Graff committed
440 441 442
 * also returned to the system.
 *
 * Requires:
443
 *\li	"resp" != NULL and "*resp" contain a value previously allocated
Michael Graff's avatar
Michael Graff committed
444
 *	by dns_dispatch_addresponse();
445
 *
Automatic Updater's avatar
Automatic Updater committed
446
 *\li	May only be called from within the task given as the 'task'
447
 * 	argument to dns_dispatch_addresponse() when allocating '*resp'.
Michael Graff's avatar
Michael Graff committed
448 449
 */

450 451
isc_socket_t *
dns_dispatch_getentrysocket(dns_dispentry_t *resp);
452

453 454
isc_socket_t *
dns_dispatch_getsocket(dns_dispatch_t *disp);
455
/*%<
456 457 458
 * Return the socket associated with this dispatcher.
 *
 * Requires:
459
 *\li	disp is valid.
460 461
 *
 * Returns:
462
 *\li	The socket the dispatcher is using.
463 464
 */

Automatic Updater's avatar
Automatic Updater committed
465
isc_result_t
466
dns_dispatch_getlocaladdress(dns_dispatch_t *disp, isc_sockaddr_t *addrp);
467
/*%<
468 469 470 471
 * Return the local address for this dispatch.
 * This currently only works for dispatches using UDP sockets.
 *
 * Requires:
472 473
 *\li	disp is valid.
 *\li	addrp to be non null.
474 475
 *
 * Returns:
Automatic Updater's avatar
Automatic Updater committed
476
 *\li	ISC_R_SUCCESS
477
 *\li	ISC_R_NOTIMPLEMENTED
478
 */
479

Michael Graff's avatar
Michael Graff committed
480 481
void
dns_dispatch_cancel(dns_dispatch_t *disp);
482
/*%<
Michael Graff's avatar
Michael Graff committed
483
 * cancel outstanding clients
484 485
 *
 * Requires:
486
 *\li	disp is valid.
487 488
 */

489 490 491 492
unsigned int
dns_dispatch_getattributes(dns_dispatch_t *disp);
/*%<
 * Return the attributes (DNS_DISPATCHATTR_xxx) of this dispatch.  Only the
Automatic Updater's avatar
Automatic Updater committed
493
 * non-changeable attributes are expected to be referenced by the caller.
494 495 496 497 498
 *
 * Requires:
 *\li	disp is valid.
 */

499 500 501
void
dns_dispatch_changeattributes(dns_dispatch_t *disp,
			      unsigned int attributes, unsigned int mask);
502
/*%<
503 504 505
 * Set the bits described by "mask" to the corresponding values in
 * "attributes".
 *
506
 * That is:
507
 *
508
 * \code
509
 *	new = (old & ~mask) | (attributes & mask)
510
 * \endcode
511
 *
Automatic Updater's avatar
Automatic Updater committed
512
 * This function has a side effect when #DNS_DISPATCHATTR_NOLISTEN changes.
513 514 515 516
 * When the flag becomes off, the dispatch will start receiving on the
 * corresponding socket.  When the flag becomes on, receive events on the
 * corresponding socket will be canceled.
 *
517
 * Requires:
518
 *\li	disp is valid.
519
 *
520
 *\li	attributes are reasonable for the dispatch.  That is, setting the UDP
521
 *	attribute on a TCP socket isn't reasonable.
Michael Graff's avatar
Michael Graff committed
522 523
 */

524
void
525
dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event);
526
/*%<
527 528 529
 * Inform the dispatcher of a socket receive.  This is used for sockets
 * shared between dispatchers and clients.  If the dispatcher fails to copy
 * or send the event, nothing happens.
530 531
 *
 * Requires:
532
 *\li 	disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set.
533
 * 	event != NULL
534 535
 */

536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575
dns_dispatch_t *
dns_dispatchset_get(dns_dispatchset_t *dset);
/*%<
 * Retrieve the next dispatch from dispatch set 'dset', and increment
 * the round-robin counter.
 *
 * Requires:
 *\li 	dset != NULL
 */

isc_result_t
dns_dispatchset_create(isc_mem_t *mctx, isc_socketmgr_t *sockmgr,
		       isc_taskmgr_t *taskmgr, dns_dispatch_t *source,
		       dns_dispatchset_t **dsetp, int n);
/*%<
 * Given a valid dispatch 'source', create a dispatch set containing
 * 'n' UDP dispatches, with the remainder filled out by clones of the
 * source.
 *
 * Requires:
 *\li 	source is a valid UDP dispatcher
 *\li 	dsetp != NULL, *dsetp == NULL
 */

void
dns_dispatchset_cancelall(dns_dispatchset_t *dset, isc_task_t *task);
/*%<
 * Cancel socket operations for the dispatches in 'dset'.
 */

void
dns_dispatchset_destroy(dns_dispatchset_t **dsetp);
/*%<
 * Dereference all the dispatches in '*dsetp', free the dispatchset
 * memory, and set *dsetp to NULL.
 *
 * Requires:
 *\li 	dset is valid
 */

Evan Hunt's avatar
Evan Hunt committed
576 577 578 579 580 581 582 583 584 585 586 587
void
dns_dispatch_setdscp(dns_dispatch_t *disp, isc_dscp_t dscp);
isc_dscp_t
dns_dispatch_getdscp(dns_dispatch_t *disp);
/*%<
 * Set/get the DSCP value to be used when sending responses to clients,
 * as defined in the "listen-on" or "listen-on-v6" statements.
 *
 * Requires:
 *\li	disp is valid.
 */

Michael Graff's avatar
Michael Graff committed
588 589
ISC_LANG_ENDDECLS

590
#endif /* DNS_DISPATCH_H */