2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2003 Internet Software Consortium.
5 * Permission to use, copy, modify, and 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.45.2.2.4.2.26.1 2007/06/26 04:14:56 marka Exp $ */
20 #ifndef DNS_DISPATCH_H
21 #define DNS_DISPATCH_H 1
28 * DNS Dispatch Management
30 * Shared UDP and single-use TCP dispatches for queries and responses.
34 * All locking is performed internally to each dispatch.
35 * Restrictions apply to dns_dispatch_removeresponse().
43 * 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 <dns/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 */
92 * Attributes for added dispatchers.
94 * Values with the mask 0xffff0000 are application defined.
95 * Values with the mask 0x0000ffff are library defined.
97 * Insane values (like setting both TCP and UDP) are not caught. Don't
101 * The dispatcher cannot be shared.
104 * The dispatcher is a TCP or UDP socket.
107 * The dispatcher uses an ipv4 or ipv6 socket.
110 * The dispatcher should not listen on the socket.
113 * The dispatcher can be used to issue queries to other servers, and
114 * accept replies from them.
117 * Allocate UDP port randomly.
119 #define DNS_DISPATCHATTR_PRIVATE 0x00000001U
120 #define DNS_DISPATCHATTR_TCP 0x00000002U
121 #define DNS_DISPATCHATTR_UDP 0x00000004U
122 #define DNS_DISPATCHATTR_IPV4 0x00000008U
123 #define DNS_DISPATCHATTR_IPV6 0x00000010U
124 #define DNS_DISPATCHATTR_NOLISTEN 0x00000020U
125 #define DNS_DISPATCHATTR_MAKEQUERY 0x00000040U
126 #define DNS_DISPATCHATTR_CONNECTED 0x00000080U
127 #define DNS_DISPATCHATTR_RANDOMPORT 0x00000100U
130 dns_dispatchmgr_create(isc_mem_t *mctx, isc_entropy_t *entropy,
131 dns_dispatchmgr_t **mgrp);
133 * Creates a new dispatchmgr object.
136 * "mctx" be a valid memory context.
138 * mgrp != NULL && *mgrp == NULL
140 * "entropy" may be NULL, in which case an insecure random generator
141 * will be used. If it is non-NULL, it must be a valid entropy
145 * ISC_R_SUCCESS -- all ok
147 * anything else -- failure
152 dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp);
154 * Destroys the dispatchmgr when it becomes empty. This could be
158 * mgrp != NULL && *mgrp is a valid dispatchmgr.
163 dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole);
165 * Sets the dispatcher's "blackhole list," a list of addresses that will
166 * be ignored by all dispatchers created by the dispatchmgr.
169 * mgrp is a valid dispatchmgr
170 * blackhole is a valid acl
175 dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr);
177 * Gets a pointer to the dispatcher's current blackhole list,
178 * without incrementing its reference count.
181 * mgr is a valid dispatchmgr
183 * A pointer to the current blackhole list, or NULL.
187 dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr,
188 dns_portlist_t *portlist);
190 * Sets a list of UDP ports that won't be used when creating a udp
191 * dispatch with a wildcard port.
194 * mgr is a valid dispatchmgr
195 * portlist to be NULL or a valid port list.
199 dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr);
201 * Return the current port list.
204 * mgr is a valid dispatchmgr
210 dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
211 isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
212 unsigned int buffersize,
213 unsigned int maxbuffers, unsigned int maxrequests,
214 unsigned int buckets, unsigned int increment,
215 unsigned int attributes, unsigned int mask,
216 dns_dispatch_t **dispp);
218 * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
219 * otherwise create a new UDP dispatch.
222 * All pointer parameters be valid for their respective types.
224 * dispp != NULL && *disp == NULL
226 * 512 <= buffersize <= 64k
232 * increment > buckets
234 * (attributes & DNS_DISPATCHATTR_TCP) == 0
237 * ISC_R_SUCCESS -- success.
239 * Anything else -- failure.
243 dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
244 isc_taskmgr_t *taskmgr, unsigned int buffersize,
245 unsigned int maxbuffers, unsigned int maxrequests,
246 unsigned int buckets, unsigned int increment,
247 unsigned int attributes, dns_dispatch_t **dispp);
249 * Create a new dns_dispatch and attach it to the provided isc_socket_t.
251 * For all dispatches, "buffersize" is the maximum packet size we will
254 * "maxbuffers" and "maxrequests" control the number of buffers in the
255 * overall system and the number of buffers which can be allocated to
258 * "buckets" is the number of buckets to use, and should be prime.
260 * "increment" is used in a collision avoidance function, and needs to be
261 * a prime > buckets, and not 2.
265 * mgr is a valid dispatch manager.
269 * task is a valid task that can be used internally to this dispatcher.
271 * 512 <= buffersize <= 64k
275 * maxrequests <= maxbuffers.
277 * buckets < 2097169 (the next prime after 65536 * 32)
279 * increment > buckets (and prime).
281 * attributes includes DNS_DISPATCHATTR_TCP and does not include
282 * DNS_DISPATCHATTR_UDP.
285 * ISC_R_SUCCESS -- success.
287 * Anything else -- failure.
291 dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
293 * Attach to a dispatch handle.
298 * dispp != NULL && *dispp == NULL
302 dns_dispatch_detach(dns_dispatch_t **dispp);
304 * Detaches from the dispatch.
307 * dispp != NULL and *dispp be a valid dispatch.
311 dns_dispatch_starttcp(dns_dispatch_t *disp);
313 * Start processing of a TCP dispatch once the socket connects.
320 dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest,
321 isc_task_t *task, isc_taskaction_t action, void *arg,
322 isc_uint16_t *idp, dns_dispentry_t **resp);
324 * Add a response entry for this dispatch.
326 * "*idp" is filled in with the assigned message ID, and *resp is filled in
327 * to contain the magic token used to request event flow stop.
329 * Arranges for the given task to get a callback for response packets. When
330 * the event is delivered, it must be returned using dns_dispatch_freeevent()
331 * or through dns_dispatch_removeresponse() for another to be delivered.
336 * "task" "action" and "arg" be set as appropriate.
338 * "dest" be non-NULL and valid.
340 * "resp" be non-NULL and *resp be NULL
344 * <id, dest> is a unique tuple. That means incoming messages
349 * ISC_R_SUCCESS -- all is well.
350 * ISC_R_NOMEMORY -- memory could not be allocated.
351 * ISC_R_NOMORE -- no more message ids can be allocated
352 * for this destination.
357 dns_dispatch_removeresponse(dns_dispentry_t **resp,
358 dns_dispatchevent_t **sockevent);
360 * Stops the flow of responses for the provided id and destination.
361 * If "sockevent" is non-NULL, the dispatch event and associated buffer is
362 * also returned to the system.
365 * "resp" != NULL and "*resp" contain a value previously allocated
366 * by dns_dispatch_addresponse();
368 * May only be called from within the task given as the 'task'
369 * argument to dns_dispatch_addresponse() when allocating '*resp'.
374 dns_dispatch_getsocket(dns_dispatch_t *disp);
376 * Return the socket associated with this dispatcher.
382 * The socket the dispatcher is using.
386 dns_dispatch_getlocaladdress(dns_dispatch_t *disp, isc_sockaddr_t *addrp);
388 * Return the local address for this dispatch.
389 * This currently only works for dispatches using UDP sockets.
393 * addrp to be non null.
397 * ISC_R_NOTIMPLEMENTED
401 dns_dispatch_cancel(dns_dispatch_t *disp);
403 * cancel outstanding clients
410 dns_dispatch_changeattributes(dns_dispatch_t *disp,
411 unsigned int attributes, unsigned int mask);
413 * Set the bits described by "mask" to the corresponding values in
418 * new = (old & ~mask) | (attributes & mask)
420 * This function has a side effect when DNS_DISPATCHATTR_NOLISTEN changes.
421 * When the flag becomes off, the dispatch will start receiving on the
422 * corresponding socket. When the flag becomes on, receive events on the
423 * corresponding socket will be canceled.
428 * attributes are reasonable for the dispatch. That is, setting the UDP
429 * attribute on a TCP socket isn't reasonable.
433 dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event);
435 * Inform the dispatcher of a socket receive. This is used for sockets
436 * shared between dispatchers and clients. If the dispatcher fails to copy
437 * or send the event, nothing happens.
440 * disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set.
446 #endif /* DNS_DISPATCH_H */