2 This file is part of GNUnet
3 Copyright (C) 2012, 2018 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 for helper library to send DNS requests to DNS resolver
27 * @defgroup dns-stub DNS Stub library
28 * Helper library to send DNS requests to DNS resolver
31 #ifndef GNUNET_DNSSTUB_LIB_H
32 #define GNUNET_DNSSTUB_LIB_H
34 #include "gnunet_util_lib.h"
37 * Opaque handle to the stub resolver.
39 struct GNUNET_DNSSTUB_Context;
42 * Opaque handle to a socket doing UDP requests.
44 struct GNUNET_DNSSTUB_RequestSocket;
48 * Start a DNS stub resolver.
50 * @param num_sockets how many sockets should we open
51 * in parallel for DNS queries for this stub?
52 * @return NULL on error
54 struct GNUNET_DNSSTUB_Context *
55 GNUNET_DNSSTUB_start (unsigned int num_sockets);
59 * Add nameserver for use by the DNSSTUB. We will use
60 * all provided nameservers for resolution (round-robin).
62 * @param ctx resolver context to modify
63 * @param dns_ip target IP address to use (as string)
64 * @return #GNUNET_OK on success
67 GNUNET_DNSSTUB_add_dns_ip (struct GNUNET_DNSSTUB_Context *ctx,
72 * Add nameserver for use by the DNSSTUB. We will use
73 * all provided nameservers for resolution (round-robin).
75 * @param ctx resolver context to modify
76 * @param sa socket address of DNS resolver to use
77 * @return #GNUNET_OK on success
80 GNUNET_DNSSTUB_add_dns_sa (struct GNUNET_DNSSTUB_Context *ctx,
81 const struct sockaddr *sa);
85 * How long should we try requests before timing out?
86 * Only effective for requests issued after this call.
88 * @param ctx resolver context to modify
89 * @param retry_frequ how long to wait between retries
92 GNUNET_DNSSTUB_set_retry (struct GNUNET_DNSSTUB_Context *ctx,
93 struct GNUNET_TIME_Relative retry_freq);
96 * Cleanup DNSSTUB resolver.
98 * @param ctx stub resolver to clean up
101 GNUNET_DNSSTUB_stop (struct GNUNET_DNSSTUB_Context *ctx);
105 * Function called with the result of a DNS resolution.
106 * Once this function is called, the resolution request
107 * is automatically cancelled / cleaned up. In particular,
108 * the function will only be called once.
111 * @param dns dns response, NULL on hard error (i.e. timeout)
112 * @param dns_len number of bytes in @a dns
115 (*GNUNET_DNSSTUB_ResultCallback)(void *cls,
116 const struct GNUNET_TUN_DnsHeader *dns,
121 * Perform DNS resolution using our default IP from init.
123 * @param ctx stub resolver to use
124 * @param request DNS request to transmit
125 * @param request_len number of bytes in msg
126 * @param rc function to call with result (once)
127 * @param rc_cls closure for @a rc
128 * @return socket used for the request, NULL on error
130 struct GNUNET_DNSSTUB_RequestSocket *
131 GNUNET_DNSSTUB_resolve (struct GNUNET_DNSSTUB_Context *ctx,
134 GNUNET_DNSSTUB_ResultCallback rc,
139 * Cancel DNS resolution.
141 * @param rs resolution to cancel
144 GNUNET_DNSSTUB_resolve_cancel (struct GNUNET_DNSSTUB_RequestSocket *rs);
149 /** @} */ /* end of group */