2 This file is part of GNUnet
3 Copyright (C) 2012 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your 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 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @author Christian Grothoff
25 * API to access the DNS service.
27 * @defgroup dns DNS service
29 * @see [Documentation](https://gnunet.org/gnunet-service-dns)
33 #ifndef GNUNET_DNS_SERVICE_H
34 #define GNUNET_DNS_SERVICE_H
36 #include "gnunet_util_lib.h"
42 struct GNUNET_DNS_Handle;
45 * Handle to identify an individual DNS request.
47 struct GNUNET_DNS_RequestHandle;
50 * Flags that specify when to call the client's handler.
56 * Useless option: never call the client.
58 GNUNET_DNS_FLAG_NEVER = 0,
61 * Set this flag to see all requests first prior to resolution
62 * (for monitoring). Clients that set this flag must then
63 * call "GNUNET_DNS_request_forward" when they process a request
64 * for the first time. Caling "GNUNET_DNS_request_answer" is
65 * not allowed for MONITOR peers.
67 GNUNET_DNS_FLAG_REQUEST_MONITOR = 1,
70 * This client should be called on requests that have not
71 * yet been resolved as this client provides a resolution
72 * service. Note that this does not guarantee that the
73 * client will see all requests as another client might be
74 * called first and that client might have already done the
75 * resolution, in which case other pre-resolution clients
76 * won't see the request anymore.
78 GNUNET_DNS_FLAG_PRE_RESOLUTION = 2,
81 * This client wants to be called on the results of a DNS resolution
82 * (either resolved by PRE-RESOLUTION clients or the global DNS).
83 * The client then has a chance to modify the answer (or cause it to
84 * be dropped). There is no guarantee that other POST-RESOLUTION
85 * client's won't modify (or drop) the answer afterwards.
87 GNUNET_DNS_FLAG_POST_RESOLUTION = 4,
90 * Set this flag to see all requests just before they are
91 * returned to the network. Clients that set this flag must then
92 * call "GNUNET_DNS_request_forward" when they process a request
93 * for the last time. Caling "GNUNET_DNS_request_answer" is
94 * not allowed for MONITOR peers.
96 GNUNET_DNS_FLAG_RESPONSE_MONITOR = 8
103 * Signature of a function that is called whenever the DNS service
104 * encounters a DNS request and needs to do something with it. The
105 * function has then the chance to generate or modify the response by
106 * calling one of the three "GNUNET_DNS_request_*" continuations.
108 * When a request is intercepted, this function is called first to
109 * give the client a chance to do the complete address resolution;
110 * "rdata" will be NULL for this first call for a DNS request, unless
111 * some other client has already filled in a response.
113 * If multiple clients exist, all of them are called before the global
114 * DNS. The global DNS is only called if all of the clients'
115 * functions call GNUNET_DNS_request_forward. Functions that call
116 * GNUNET_DNS_request_forward will be called again before a final
117 * response is returned to the application. If any of the clients'
118 * functions call GNUNET_DNS_request_drop, the response is dropped.
121 * @param rh request handle to user for reply
122 * @param request_length number of bytes in request
123 * @param request udp payload of the DNS request
126 (*GNUNET_DNS_RequestHandler)(void *cls,
127 struct GNUNET_DNS_RequestHandle *rh,
128 size_t request_length,
129 const char *request);
133 * If a GNUNET_DNS_RequestHandler calls this function, the client
134 * has no desire to interfer with the request and it should
135 * continue to be processed normally.
137 * @param rh request that should now be forwarded
140 GNUNET_DNS_request_forward (struct GNUNET_DNS_RequestHandle *rh);
144 * If a GNUNET_DNS_RequestHandler calls this function, the request is
145 * to be dropped and no response should be generated.
147 * @param rh request that should now be dropped
150 GNUNET_DNS_request_drop (struct GNUNET_DNS_RequestHandle *rh);
154 * If a GNUNET_DNS_RequestHandler calls this function, the request is
155 * supposed to be answered with the data provided to this call (with
156 * the modifications the function might have made). The reply given
157 * must always be a valid DNS reply and not a mutated DNS request.
159 * @param rh request that should now be answered
160 * @param reply_length size of @a reply (uint16_t to force sane size)
161 * @param reply reply data
164 GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh,
165 uint16_t reply_length,
170 * Connect to the service-dns
172 * @param cfg configuration to use
173 * @param flags when to call @a rh
174 * @param rh function to call with DNS requests
175 * @param rh_cls closure to pass to @a rh
178 struct GNUNET_DNS_Handle *
179 GNUNET_DNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
180 enum GNUNET_DNS_Flags flags,
181 GNUNET_DNS_RequestHandler rh,
186 * Disconnect from the DNS service.
188 * @param dh DNS handle
191 GNUNET_DNS_disconnect (struct GNUNET_DNS_Handle *dh);
196 /** @} */ /* end of group */