dispatch.h 16 KB
Newer Older
Michael Graff's avatar
Michael Graff committed
1
/*
2
 * Copyright (C) 1999-2009, 2011-2016  Internet Systems Consortium, Inc. ("ISC")
3
 *
4
5
6
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
Michael Graff's avatar
Michael Graff committed
7
8
 */

9
10
#ifndef DNS_DISPATCH_H
#define DNS_DISPATCH_H 1
Michael Graff's avatar
Michael Graff committed
11
12
13
14
15

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

16
/*! \file dns/dispatch.h
17
 * \brief
18
19
 * DNS Dispatch Management
 * 	Shared UDP and single-use TCP dispatches for queries and responses.
Michael Graff's avatar
Michael Graff committed
20
21
22
 *
 * MP:
 *
23
 *\li     	All locking is performed internally to each dispatch.
24
 * 	Restrictions apply to dns_dispatch_removeresponse().
Michael Graff's avatar
Michael Graff committed
25
26
27
28
29
30
31
 *
 * Reliability:
 *
 * Resources:
 *
 * Security:
 *
32
 *\li	Depends on the isc_socket_t and dns_message_t for prevention of
Michael Graff's avatar
Michael Graff committed
33
34
35
36
 *	buffer overruns.
 *
 * Standards:
 *
37
 *\li	None.
Michael Graff's avatar
Michael Graff committed
38
39
40
41
42
43
44
45
 */

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

#include <isc/buffer.h>
#include <isc/lang.h>
46
#include <isc/mutex.h>
Bob Halley's avatar
Bob Halley committed
47
#include <isc/socket.h>
48
#include <isc/types.h>
Michael Graff's avatar
Michael Graff committed
49
50
51
52
53

#include <dns/types.h>

ISC_LANG_BEGINDECLS

54
/*%
55
 * This event is sent to a task when a response comes in.
Michael Graff's avatar
Michael Graff committed
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 * 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
70

Michael Graff's avatar
Michael Graff committed
71
struct dns_dispatchevent {
72
73
74
75
76
77
78
	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
79
80
};

81
82
83
84
85
86
87
88
89
90
91
92
/*%
 * 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;
};

93
94
/*@{*/
/*%
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 * 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
110
 *	The dispatcher uses an IPv4 or IPv6 socket.
111
 *
112
113
 * _NOLISTEN
 *	The dispatcher should not listen on the socket.
114
 *
115
 * _MAKEQUERY
116
117
 *	The dispatcher can be used to issue queries to other servers, and
 *	accept replies from them.
118
119
 *
 * _RANDOMPORT
120
121
122
123
124
 *	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
125
 *	A separate socket will be used on-demand for each transaction.
126
127
128
129
130
131
 */
#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
132
#define DNS_DISPATCHATTR_NOLISTEN	0x00000020U
133
#define DNS_DISPATCHATTR_MAKEQUERY	0x00000040U
134
#define DNS_DISPATCHATTR_CONNECTED	0x00000080U
135
#define DNS_DISPATCHATTR_FIXEDID	0x00000100U
136
#define DNS_DISPATCHATTR_EXCLUSIVE	0x00000200U
137
/*@}*/
138

139
140
141
142
/*
 */
#define DNS_DISPATCHOPT_FIXEDID		0x00000001U

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


void
dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp);
167
/*%<
168
169
170
171
 * Destroys the dispatchmgr when it becomes empty.  This could be
 * immediately.
 *
 * Requires:
172
 *\li	mgrp != NULL && *mgrp is a valid dispatchmgr.
173
174
175
 */


176
177
void
dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole);
178
/*%<
179
180
 * Sets the dispatcher's "blackhole list," a list of addresses that will
 * be ignored by all dispatchers created by the dispatchmgr.
181
182
 *
 * Requires:
183
184
 * \li	mgrp is a valid dispatchmgr
 * \li	blackhole is a valid acl
185
186
187
 */


188
189
dns_acl_t *
dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr);
190
/*%<
191
192
 * Gets a pointer to the dispatcher's current blackhole list,
 * without incrementing its reference count.
193
194
 *
 * Requires:
195
 *\li 	mgr is a valid dispatchmgr
196
 * Returns:
197
 *\li	A pointer to the current blackhole list, or NULL.
198
199
 */

200
201
void
dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr,
Automatic Updater's avatar
Automatic Updater committed
202
				 dns_portlist_t *portlist);
203
/*%<
204
 * This function is deprecated.  Use dns_dispatchmgr_setavailports() instead.
205
206
 *
 * Requires:
207
 *\li	mgr is a valid dispatchmgr
208
209
210
211
 */

dns_portlist_t *
dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr);
212
/*%<
213
 * This function is deprecated and always returns NULL.
214
215
 *
 * Requires:
216
 *\li	mgr is a valid dispatchmgr
217
218
 */

219
220
221
222
223
224
225
226
227
228
229
230
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
 */

231
void
232
dns_dispatchmgr_setstats(dns_dispatchmgr_t *mgr, isc_stats_t *stats);
233
234
235
236
237
238
239
240
241
242
243
244
/*%<
 * 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).
 */
245
246

isc_result_t
247
dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
248
		    isc_taskmgr_t *taskmgr, const isc_sockaddr_t *localaddr,
249
		    unsigned int buffersize,
250
		    unsigned int maxbuffers, unsigned int maxrequests,
251
		    unsigned int buckets, unsigned int increment,
252
		    unsigned int attributes, unsigned int mask,
253
		    dns_dispatch_t **dispp);
254
255
256

isc_result_t
dns_dispatch_getudp_dup(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
257
		    isc_taskmgr_t *taskmgr, const isc_sockaddr_t *localaddr,
258
259
260
261
262
		    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);
263
/*%<
264
 * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
265
 * otherwise create a new UDP dispatch.
266
267
 *
 * Requires:
268
 *\li	All pointer parameters be valid for their respective types.
269
 *
270
 *\li	dispp != NULL && *disp == NULL
271
 *
272
 *\li	512 <= buffersize <= 64k
273
 *
274
 *\li	maxbuffers > 0
275
 *
276
 *\li	buckets < 2097169
277
 *
278
 *\li	increment > buckets
279
 *
280
 *\li	(attributes & DNS_DISPATCHATTR_TCP) == 0
281
282
 *
 * Returns:
283
 *\li	ISC_R_SUCCESS	-- success.
284
 *
285
 *\li	Anything else	-- failure.
286
 */
287
288
289
290
291
292
293

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

void
344
dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
345
/*%<
346
347
348
 * Attach to a dispatch handle.
 *
 * Requires:
349
 *\li	disp is valid.
350
 *
351
 *\li	dispp != NULL && *dispp == NULL
352
353
354
355
 */

void
dns_dispatch_detach(dns_dispatch_t **dispp);
356
/*%<
357
 * Detaches from the dispatch.
Michael Graff's avatar
Michael Graff committed
358
359
 *
 * Requires:
360
 *\li	dispp != NULL and *dispp be a valid dispatch.
Michael Graff's avatar
Michael Graff committed
361
362
 */

363
void
364
dns_dispatch_starttcp(dns_dispatch_t *disp);
365
/*%<
Mark Andrews's avatar
Mark Andrews committed
366
 * Start processing of a TCP dispatch once the socket connects.
367
368
 *
 * Requires:
369
 *\li	'disp' is valid.
370
 */
371

372
isc_result_t
373
374
dns_dispatch_gettcp(dns_dispatchmgr_t *mgr, const isc_sockaddr_t *destaddr,
		    const isc_sockaddr_t *localaddr, dns_dispatch_t **dispp);
375
isc_result_t
376
377
dns_dispatch_gettcp2(dns_dispatchmgr_t *mgr, const isc_sockaddr_t *destaddr,
		     const isc_sockaddr_t *localaddr, isc_boolean_t *connected,
378
		     dns_dispatch_t **dispp);
379
/*
380
381
 * Attempt to connect to a existing TCP connection (connection completed
 * for dns_dispatch_gettcp()).
382
383
384
 */


385
386
isc_result_t
dns_dispatch_addresponse3(dns_dispatch_t *disp, unsigned int options,
387
			  const isc_sockaddr_t *dest, isc_task_t *task,
388
389
390
391
			  isc_taskaction_t action, void *arg,
			  isc_uint16_t *idp, dns_dispentry_t **resp,
			  isc_socketmgr_t *sockmgr);

392
isc_result_t
393
dns_dispatch_addresponse2(dns_dispatch_t *disp, const isc_sockaddr_t *dest,
394
395
396
397
			  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
398
isc_result_t
399
dns_dispatch_addresponse(dns_dispatch_t *disp, const isc_sockaddr_t *dest,
400
			 isc_task_t *task, isc_taskaction_t action, void *arg,
Michael Graff's avatar
Michael Graff committed
401
			 isc_uint16_t *idp, dns_dispentry_t **resp);
402
/*%<
403
 * Add a response entry for this dispatch.
Michael Graff's avatar
Michael Graff committed
404
 *
Michael Graff's avatar
Michael Graff committed
405
406
 * "*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
407
 *
Michael Graff's avatar
Michael Graff committed
408
409
410
 * 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
411
412
 *
 * Requires:
413
 *\li	"idp" be non-NULL.
Michael Graff's avatar
Michael Graff committed
414
 *
415
 *\li	"task" "action" and "arg" be set as appropriate.
Michael Graff's avatar
Michael Graff committed
416
 *
417
 *\li	"dest" be non-NULL and valid.
Michael Graff's avatar
Michael Graff committed
418
 *
419
 *\li	"resp" be non-NULL and *resp be NULL
Michael Graff's avatar
Michael Graff committed
420
 *
421
422
423
424
 *\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
425
426
 * Ensures:
 *
427
 *\li	&lt;id, dest> is a unique tuple.  That means incoming messages
Michael Graff's avatar
Michael Graff committed
428
429
430
 *	are identifiable.
 *
 * Returns:
Michael Graff's avatar
Michael Graff committed
431
 *
432
433
434
 *\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
435
 *				   for this destination.
Michael Graff's avatar
Michael Graff committed
436
437
 */

438

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

455
456
isc_socket_t *
dns_dispatch_getentrysocket(dns_dispentry_t *resp);
457

458
459
isc_socket_t *
dns_dispatch_getsocket(dns_dispatch_t *disp);
460
/*%<
461
462
463
 * Return the socket associated with this dispatcher.
 *
 * Requires:
464
 *\li	disp is valid.
465
466
 *
 * Returns:
467
 *\li	The socket the dispatcher is using.
468
469
 */

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

Michael Graff's avatar
Michael Graff committed
485
486
void
dns_dispatch_cancel(dns_dispatch_t *disp);
487
/*%<
Michael Graff's avatar
Michael Graff committed
488
 * cancel outstanding clients
489
490
 *
 * Requires:
491
 *\li	disp is valid.
492
493
 */

494
495
496
497
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
498
 * non-changeable attributes are expected to be referenced by the caller.
499
500
501
502
503
 *
 * Requires:
 *\li	disp is valid.
 */

504
505
506
void
dns_dispatch_changeattributes(dns_dispatch_t *disp,
			      unsigned int attributes, unsigned int mask);
507
/*%<
508
509
510
 * Set the bits described by "mask" to the corresponding values in
 * "attributes".
 *
511
 * That is:
512
 *
513
 * \code
514
 *	new = (old & ~mask) | (attributes & mask)
515
 * \endcode
516
 *
Automatic Updater's avatar
Automatic Updater committed
517
 * This function has a side effect when #DNS_DISPATCHATTR_NOLISTEN changes.
518
519
520
521
 * 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.
 *
522
 * Requires:
523
 *\li	disp is valid.
524
 *
525
 *\li	attributes are reasonable for the dispatch.  That is, setting the UDP
526
 *	attribute on a TCP socket isn't reasonable.
Michael Graff's avatar
Michael Graff committed
527
528
 */

529
void
530
dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event);
531
/*%<
532
533
534
 * 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.
535
 *
536
537
538
 * If the attribute DNS_DISPATCHATTR_NOLISTEN is not set, then
 * the dispatch is already handling a recv; return immediately.
 *
539
 * Requires:
540
 *\li 	disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set.
541
 * 	event != NULL
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
576
577
578
579
580
581
582
583
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
584
585
586
587
588
589
590
591
592
593
594
595
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.
 */

596
597
598
599
600
601
602
603
604
605
606
isc_result_t
dns_dispatch_getnext(dns_dispentry_t *resp, dns_dispatchevent_t **sockevent);
/*%<
 * Free the sockevent and trigger the sending of the next item off the
 * dispatch queue if present.
 *
 * Requires:
 *\li	resp is valid
 *\li	*sockevent to be valid
 */

Michael Graff's avatar
Michael Graff committed
607
608
ISC_LANG_ENDDECLS

609
#endif /* DNS_DISPATCH_H */