2 This file is part of GNUnet
3 (C) 2012 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_dns_service.h
23 * @brief API to access the DNS service.
24 * @author Christian Grothoff
26 #ifndef GNUNET_DNS_SERVICE_NEW_H
27 #define GNUNET_DNS_SERVICE_NEW_H
29 #include "gnunet_common.h"
30 #include "gnunet_util_lib.h"
36 struct GNUNET_DNS_Handle;
39 * Handle to identify an individual DNS request.
41 struct GNUNET_DNS_RequestHandle;
44 * Flags that specify when to call the client's handler.
50 * Useless option: never call the client.
52 GNUNET_DNS_FLAG_NEVER = 0,
55 * Set this flag to see all requests first prior to resolution
56 * (for monitoring). Clients that set this flag must then
57 * call "GNUNET_DNS_request_forward" when they process a request
58 * for the first time. Caling "GNUNET_DNS_request_answer" is
59 * not allowed for MONITOR peers.
61 GNUNET_DNS_FLAG_REQUEST_MONITOR = 1,
64 * This client should be called on requests that have not
65 * yet been resolved as this client provides a resolution
66 * service. Note that this does not guarantee that the
67 * client will see all requests as another client might be
68 * called first and that client might have already done the
69 * resolution, in which case other pre-resolution clients
70 * won't see the request anymore.
72 GNUNET_DNS_FLAG_PRE_RESOLUTION = 2,
75 * This client wants to be called on the results of a DNS resolution
76 * (either resolved by PRE-RESOLUTION clients or the global DNS).
77 * The client then has a chance to modify the answer (or cause it to
78 * be dropped). There is no guarantee that other POST-RESOLUTION
79 * client's won't modify (or drop) the answer afterwards.
81 GNUNET_DNS_FLAG_POST_RESOLUTION = 4,
84 * Set this flag to see all requests just before they are
85 * returned to the network. Clients that set this flag must then
86 * call "GNUNET_DNS_request_forward" when they process a request
87 * for the last time. Caling "GNUNET_DNS_request_answer" is
88 * not allowed for MONITOR peers.
90 GNUNET_DNS_FLAG_RESPONSE_MONITOR = 8
97 * Signature of a function that is called whenever the DNS service
98 * encounters a DNS request and needs to do something with it. The
99 * function has then the chance to generate or modify the response by
100 * calling one of the three "GNUNET_DNS_request_*" continuations.
102 * When a request is intercepted, this function is called first to
103 * give the client a chance to do the complete address resolution;
104 * "rdata" will be NULL for this first call for a DNS request, unless
105 * some other client has already filled in a response.
107 * If multiple clients exist, all of them are called before the global
108 * DNS. The global DNS is only called if all of the clients'
109 * functions call GNUNET_DNS_request_forward. Functions that call
110 * GNUNET_DNS_request_forward will be called again before a final
111 * response is returned to the application. If any of the clients'
112 * functions call GNUNET_DNS_request_drop, the response is dropped.
115 * @param rh request handle to user for reply
116 * @param request_length number of bytes in request
117 * @param request udp payload of the DNS request
119 typedef void (*GNUNET_DNS_RequestHandler)(void *cls,
120 struct GNUNET_DNS_RequestHandle *rh,
121 size_t request_length,
122 const char *request);
126 * If a GNUNET_DNS_RequestHandler calls this function, the client
127 * has no desire to interfer with the request and it should
128 * continue to be processed normally.
130 * @param rh request that should now be forwarded
133 GNUNET_DNS_request_forward (struct GNUNET_DNS_RequestHandle *rh);
137 * If a GNUNET_DNS_RequestHandler calls this function, the request is
138 * to be dropped and no response should be generated.
140 * @param rh request that should now be dropped
143 GNUNET_DNS_request_drop (struct GNUNET_DNS_RequestHandle *rh);
147 * If a GNUNET_DNS_RequestHandler calls this function, the request is
148 * supposed to be answered with the data provided to this call (with
149 * the modifications the function might have made). The reply given
150 * must always be a valid DNS reply and not a mutated DNS request.
152 * @param rh request that should now be answered
153 * @param reply_length size of reply (uint16_t to force sane size)
154 * @param reply reply data
157 GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh,
158 uint16_t reply_length,
163 * Connect to the service-dns
165 * @param cfg configuration to use
166 * @param flags when to call rh
167 * @param rh function to call with DNS requests
168 * @param rh_cls closure to pass to rh
171 struct GNUNET_DNS_Handle *
172 GNUNET_DNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
173 enum GNUNET_DNS_Flags flags,
174 GNUNET_DNS_RequestHandler rh,
179 * Disconnect from the DNS service.
181 * @param dh DNS handle
184 GNUNET_DNS_disconnect (struct GNUNET_DNS_Handle *dh);