2 * Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2003 Internet Software Consortium.
5 * Permission to use, copy, modify, and/or 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: dispatch.h,v 1.62 2009-01-27 23:47:54 tbox Exp $ */
20 #ifndef DNS_DISPATCH_H
21 #define DNS_DISPATCH_H 1
27 /*! \file dns/dispatch.h
29 * DNS Dispatch Management
30 * Shared UDP and single-use TCP dispatches for queries and responses.
34 *\li All locking is performed internally to each dispatch.
35 * Restrictions apply to dns_dispatch_removeresponse().
43 *\li Depends on the isc_socket_t and dns_message_t for prevention of
55 #include <isc/buffer.h>
57 #include <isc/socket.h>
58 #include <isc/types.h>
60 #include <dns/types.h>
65 * This event is sent to a task when a response comes in.
66 * No part of this structure should ever be modified by the caller,
67 * other than parts of the buffer. The holy parts of the buffer are
68 * the base and size of the buffer. All other parts of the buffer may
69 * be used. On event delivery the used region contains the packet.
71 * "id" is the received message id,
73 * "addr" is the host that sent it to us,
75 * "buffer" holds state on the received data.
77 * The "free" routine for this event will clean up itself as well as
78 * any buffer space allocated from common pools.
81 struct dns_dispatchevent {
82 ISC_EVENT_COMMON(dns_dispatchevent_t); /*%< standard event common */
83 isc_result_t result; /*%< result code */
84 isc_int32_t id; /*%< message id */
85 isc_sockaddr_t addr; /*%< address recv'd from */
86 struct in6_pktinfo pktinfo; /*%< reply info for v6 */
87 isc_buffer_t buffer; /*%< data buffer */
88 isc_uint32_t attributes; /*%< mirrored from socket.h */
93 * Attributes for added dispatchers.
95 * Values with the mask 0xffff0000 are application defined.
96 * Values with the mask 0x0000ffff are library defined.
98 * Insane values (like setting both TCP and UDP) are not caught. Don't
102 * The dispatcher cannot be shared.
105 * The dispatcher is a TCP or UDP socket.
108 * The dispatcher uses an IPv4 or IPv6 socket.
111 * The dispatcher should not listen on the socket.
114 * The dispatcher can be used to issue queries to other servers, and
115 * accept replies from them.
118 * Previously used to indicate that the port of a dispatch UDP must be
119 * chosen randomly. This behavior now always applies and the attribute
123 * A separate socket will be used on-demand for each transaction.
125 #define DNS_DISPATCHATTR_PRIVATE 0x00000001U
126 #define DNS_DISPATCHATTR_TCP 0x00000002U
127 #define DNS_DISPATCHATTR_UDP 0x00000004U
128 #define DNS_DISPATCHATTR_IPV4 0x00000008U
129 #define DNS_DISPATCHATTR_IPV6 0x00000010U
130 #define DNS_DISPATCHATTR_NOLISTEN 0x00000020U
131 #define DNS_DISPATCHATTR_MAKEQUERY 0x00000040U
132 #define DNS_DISPATCHATTR_CONNECTED 0x00000080U
133 /*#define DNS_DISPATCHATTR_RANDOMPORT 0x00000100U*/
134 #define DNS_DISPATCHATTR_EXCLUSIVE 0x00000200U
138 dns_dispatchmgr_create(isc_mem_t *mctx, isc_entropy_t *entropy,
139 dns_dispatchmgr_t **mgrp);
141 * Creates a new dispatchmgr object.
144 *\li "mctx" be a valid memory context.
146 *\li mgrp != NULL && *mgrp == NULL
148 *\li "entropy" may be NULL, in which case an insecure random generator
149 * will be used. If it is non-NULL, it must be a valid entropy
153 *\li ISC_R_SUCCESS -- all ok
155 *\li anything else -- failure
160 dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp);
162 * Destroys the dispatchmgr when it becomes empty. This could be
166 *\li mgrp != NULL && *mgrp is a valid dispatchmgr.
171 dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole);
173 * Sets the dispatcher's "blackhole list," a list of addresses that will
174 * be ignored by all dispatchers created by the dispatchmgr.
177 * \li mgrp is a valid dispatchmgr
178 * \li blackhole is a valid acl
183 dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr);
185 * Gets a pointer to the dispatcher's current blackhole list,
186 * without incrementing its reference count.
189 *\li mgr is a valid dispatchmgr
191 *\li A pointer to the current blackhole list, or NULL.
195 dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr,
196 dns_portlist_t *portlist);
198 * This function is deprecated. Use dns_dispatchmgr_setavailports() instead.
201 *\li mgr is a valid dispatchmgr
205 dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr);
207 * This function is deprecated and always returns NULL.
210 *\li mgr is a valid dispatchmgr
214 dns_dispatchmgr_setavailports(dns_dispatchmgr_t *mgr, isc_portset_t *v4portset,
215 isc_portset_t *v6portset);
217 * Sets a list of UDP ports that can be used for outgoing UDP messages.
220 *\li mgr is a valid dispatchmgr
221 *\li v4portset is NULL or a valid port set
222 *\li v6portset is NULL or a valid port set
226 dns_dispatchmgr_setstats(dns_dispatchmgr_t *mgr, isc_stats_t *stats);
228 * Sets statistics counter for the dispatchmgr. This function is expected to
229 * be called only on zone creation (when necessary).
230 * Once installed, it cannot be removed or replaced. Also, there is no
231 * interface to get the installed stats from the zone; the caller must keep the
232 * stats to reference (e.g. dump) it later.
235 *\li mgr is a valid dispatchmgr with no managed dispatch.
236 *\li stats is a valid statistics supporting resolver statistics counters
241 dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
242 isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
243 unsigned int buffersize,
244 unsigned int maxbuffers, unsigned int maxrequests,
245 unsigned int buckets, unsigned int increment,
246 unsigned int attributes, unsigned int mask,
247 dns_dispatch_t **dispp);
249 * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
250 * otherwise create a new UDP dispatch.
253 *\li All pointer parameters be valid for their respective types.
255 *\li dispp != NULL && *disp == NULL
257 *\li 512 <= buffersize <= 64k
261 *\li buckets < 2097169
263 *\li increment > buckets
265 *\li (attributes & DNS_DISPATCHATTR_TCP) == 0
268 *\li ISC_R_SUCCESS -- success.
270 *\li Anything else -- failure.
274 dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
275 isc_taskmgr_t *taskmgr, unsigned int buffersize,
276 unsigned int maxbuffers, unsigned int maxrequests,
277 unsigned int buckets, unsigned int increment,
278 unsigned int attributes, dns_dispatch_t **dispp);
280 * Create a new dns_dispatch and attach it to the provided isc_socket_t.
282 * For all dispatches, "buffersize" is the maximum packet size we will
285 * "maxbuffers" and "maxrequests" control the number of buffers in the
286 * overall system and the number of buffers which can be allocated to
289 * "buckets" is the number of buckets to use, and should be prime.
291 * "increment" is used in a collision avoidance function, and needs to be
292 * a prime > buckets, and not 2.
296 *\li mgr is a valid dispatch manager.
298 *\li sock is a valid.
300 *\li task is a valid task that can be used internally to this dispatcher.
302 * \li 512 <= buffersize <= 64k
306 *\li maxrequests <= maxbuffers.
308 *\li buckets < 2097169 (the next prime after 65536 * 32)
310 *\li increment > buckets (and prime).
312 *\li attributes includes #DNS_DISPATCHATTR_TCP and does not include
313 * #DNS_DISPATCHATTR_UDP.
316 *\li ISC_R_SUCCESS -- success.
318 *\li Anything else -- failure.
322 dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
324 * Attach to a dispatch handle.
329 *\li dispp != NULL && *dispp == NULL
333 dns_dispatch_detach(dns_dispatch_t **dispp);
335 * Detaches from the dispatch.
338 *\li dispp != NULL and *dispp be a valid dispatch.
342 dns_dispatch_starttcp(dns_dispatch_t *disp);
344 * Start processing of a TCP dispatch once the socket connects.
347 *\li 'disp' is valid.
351 dns_dispatch_addresponse2(dns_dispatch_t *disp, isc_sockaddr_t *dest,
352 isc_task_t *task, isc_taskaction_t action, void *arg,
353 isc_uint16_t *idp, dns_dispentry_t **resp,
354 isc_socketmgr_t *sockmgr);
357 dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest,
358 isc_task_t *task, isc_taskaction_t action, void *arg,
359 isc_uint16_t *idp, dns_dispentry_t **resp);
361 * Add a response entry for this dispatch.
363 * "*idp" is filled in with the assigned message ID, and *resp is filled in
364 * to contain the magic token used to request event flow stop.
366 * Arranges for the given task to get a callback for response packets. When
367 * the event is delivered, it must be returned using dns_dispatch_freeevent()
368 * or through dns_dispatch_removeresponse() for another to be delivered.
371 *\li "idp" be non-NULL.
373 *\li "task" "action" and "arg" be set as appropriate.
375 *\li "dest" be non-NULL and valid.
377 *\li "resp" be non-NULL and *resp be NULL
379 *\li "sockmgr" be NULL or a valid socket manager. If 'disp' has
380 * the DNS_DISPATCHATTR_EXCLUSIVE attribute, this must not be NULL,
381 * which also means dns_dispatch_addresponse() cannot be used.
385 *\li <id, dest> is a unique tuple. That means incoming messages
390 *\li ISC_R_SUCCESS -- all is well.
391 *\li ISC_R_NOMEMORY -- memory could not be allocated.
392 *\li ISC_R_NOMORE -- no more message ids can be allocated
393 * for this destination.
398 dns_dispatch_removeresponse(dns_dispentry_t **resp,
399 dns_dispatchevent_t **sockevent);
401 * Stops the flow of responses for the provided id and destination.
402 * If "sockevent" is non-NULL, the dispatch event and associated buffer is
403 * also returned to the system.
406 *\li "resp" != NULL and "*resp" contain a value previously allocated
407 * by dns_dispatch_addresponse();
409 *\li May only be called from within the task given as the 'task'
410 * argument to dns_dispatch_addresponse() when allocating '*resp'.
414 dns_dispatch_getentrysocket(dns_dispentry_t *resp);
417 dns_dispatch_getsocket(dns_dispatch_t *disp);
419 * Return the socket associated with this dispatcher.
425 *\li The socket the dispatcher is using.
429 dns_dispatch_getlocaladdress(dns_dispatch_t *disp, isc_sockaddr_t *addrp);
431 * Return the local address for this dispatch.
432 * This currently only works for dispatches using UDP sockets.
436 *\li addrp to be non null.
440 *\li ISC_R_NOTIMPLEMENTED
444 dns_dispatch_cancel(dns_dispatch_t *disp);
446 * cancel outstanding clients
453 dns_dispatch_getattributes(dns_dispatch_t *disp);
455 * Return the attributes (DNS_DISPATCHATTR_xxx) of this dispatch. Only the
456 * non-changeable attributes are expected to be referenced by the caller.
463 dns_dispatch_changeattributes(dns_dispatch_t *disp,
464 unsigned int attributes, unsigned int mask);
466 * Set the bits described by "mask" to the corresponding values in
472 * new = (old & ~mask) | (attributes & mask)
475 * This function has a side effect when #DNS_DISPATCHATTR_NOLISTEN changes.
476 * When the flag becomes off, the dispatch will start receiving on the
477 * corresponding socket. When the flag becomes on, receive events on the
478 * corresponding socket will be canceled.
483 *\li attributes are reasonable for the dispatch. That is, setting the UDP
484 * attribute on a TCP socket isn't reasonable.
488 dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event);
490 * Inform the dispatcher of a socket receive. This is used for sockets
491 * shared between dispatchers and clients. If the dispatcher fails to copy
492 * or send the event, nothing happens.
495 *\li disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set.
501 #endif /* DNS_DISPATCH_H */