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
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, 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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
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_common.h"
35 #include "gnunet_tun_lib.h"
38 * Opaque handle to the stub resolver.
40 struct GNUNET_DNSSTUB_Context;
43 * Opaque handle to a socket doing UDP requests.
45 struct GNUNET_DNSSTUB_RequestSocket;
49 * Start a DNS stub resolver.
51 * @param num_sockets how many sockets should we open
52 * in parallel for DNS queries for this stub?
53 * @return NULL on error
55 struct GNUNET_DNSSTUB_Context *
56 GNUNET_DNSSTUB_start (unsigned int num_sockets);
60 * Add nameserver for use by the DNSSTUB. We will use
61 * all provided nameservers for resolution (round-robin).
63 * @param ctx resolver context to modify
64 * @param dns_ip target IP address to use (as string)
65 * @return #GNUNET_OK on success
68 GNUNET_DNSSTUB_add_dns_ip (struct GNUNET_DNSSTUB_Context *ctx,
73 * Add nameserver for use by the DNSSTUB. We will use
74 * all provided nameservers for resolution (round-robin).
76 * @param ctx resolver context to modify
77 * @param sa socket address of DNS resolver to use
78 * @return #GNUNET_OK on success
81 GNUNET_DNSSTUB_add_dns_sa (struct GNUNET_DNSSTUB_Context *ctx,
82 const struct sockaddr *sa);
86 * How long should we try requests before timing out?
87 * Only effective for requests issued after this call.
89 * @param ctx resolver context to modify
90 * @param retry_frequ how long to wait between retries
93 GNUNET_DNSSTUB_set_retry (struct GNUNET_DNSSTUB_Context *ctx,
94 struct GNUNET_TIME_Relative retry_freq);
97 * Cleanup DNSSTUB resolver.
99 * @param ctx stub resolver to clean up
102 GNUNET_DNSSTUB_stop (struct GNUNET_DNSSTUB_Context *ctx);
106 * Function called with the result of a DNS resolution.
107 * Once this function is called, the resolution request
108 * is automatically cancelled / cleaned up. In particular,
109 * the function will only be called once.
112 * @param dns dns response, NULL on hard error (i.e. timeout)
113 * @param dns_len number of bytes in @a dns
116 (*GNUNET_DNSSTUB_ResultCallback)(void *cls,
117 const struct GNUNET_TUN_DnsHeader *dns,
122 * Perform DNS resolution using our default IP from init.
124 * @param ctx stub resolver to use
125 * @param request DNS request to transmit
126 * @param request_len number of bytes in msg
127 * @param rc function to call with result (once)
128 * @param rc_cls closure for @a rc
129 * @return socket used for the request, NULL on error
131 struct GNUNET_DNSSTUB_RequestSocket *
132 GNUNET_DNSSTUB_resolve (struct GNUNET_DNSSTUB_Context *ctx,
135 GNUNET_DNSSTUB_ResultCallback rc,
140 * Cancel DNS resolution.
142 * @param rs resolution to cancel
145 GNUNET_DNSSTUB_resolve_cancel (struct GNUNET_DNSSTUB_RequestSocket *rs);
150 /** @} */ /* end of group */