2 This file is part of GNUnet.
3 Copyright (C) 2007-2017 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
23 * @author Milan Bouchet-Valat
26 * Service for testing and autoconfiguration of
27 * NAT traversal functionality
29 * @defgroup nat NAT testing library
34 #ifndef GNUNET_NAT_AUTO_SERVICE_H
35 #define GNUNET_NAT_AUTO_SERVICE_H
37 #include "gnunet_util_lib.h"
41 * Handle to a NAT test.
43 struct GNUNET_NAT_Test;
47 * Function called to report success or failure for
48 * NAT configuration test.
51 * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code
54 (*GNUNET_NAT_TestCallback) (void *cls,
55 enum GNUNET_NAT_StatusCode result);
59 * Handle an incoming STUN message. This function is useful as
60 * some GNUnet service may be listening on a UDP port and might
61 * thus receive STUN messages while trying to receive other data.
62 * In this case, this function can be used to process replies
65 * The function does some basic sanity checks on packet size and
66 * content, try to extract a bit of information.
68 * At the moment this only processes BIND requests, and returns the
69 * externally visible address of the request to the rest of the
72 * @param nh handle to the NAT service
73 * @param sender_addr address from which we got @a data
74 * @param sender_addr_len number of bytes in @a sender_addr
75 * @param data the packet
76 * @param data_size number of bytes in @a data
77 * @return #GNUNET_OK on success
78 * #GNUNET_NO if the packet is not a STUN packet
79 * #GNUNET_SYSERR on internal error handling the packet
82 GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nh,
83 const struct sockaddr *sender_addr,
84 size_t sender_addr_len,
90 * Handle to a request given to the resolver. Can be used to cancel
91 * the request prior to the timeout or successful execution. Also
92 * used to track our internal state for the request.
94 struct GNUNET_NAT_STUN_Handle;
98 * Make Generic STUN request. Sends a generic stun request to the
99 * server specified using the specified socket. If we do this,
100 * we need to watch for possible responses and call
101 * #GNUNET_NAT_stun_handle_packet() on incoming packets.
103 * @param server the address of the stun server
104 * @param port port of the stun server, in host byte order
105 * @param sock the socket used to send the request, must be a
107 * @param cb callback in case of error
108 * @param cb_cls closure for @a cb
109 * @return NULL on error
111 struct GNUNET_NAT_STUN_Handle *
112 GNUNET_NAT_stun_make_request (const char *server,
114 struct GNUNET_NETWORK_Handle *sock,
115 GNUNET_NAT_TestCallback cb,
120 * Cancel active STUN request. Frees associated resources
121 * and ensures that the callback is no longer invoked.
123 * @param rh request to cancel
126 GNUNET_NAT_stun_make_request_cancel (struct GNUNET_NAT_STUN_Handle *rh);
130 * Start testing if NAT traversal works using the given configuration
131 * (IPv4-only). The transport adapters should be down while using
134 * @param cfg configuration for the NAT traversal
135 * @param proto protocol to test, i.e. IPPROTO_TCP or IPPROTO_UDP
136 * @param bind_ip IPv4 address to bind to
137 * @param bnd_port port to bind to, 0 to test connection reversal
138 * @param extern_ip IPv4 address to externally advertise
139 * @param extern_port externally advertised port to use
140 * @param report function to call with the result of the test
141 * @param report_cls closure for @a report
142 * @return handle to cancel NAT test
144 struct GNUNET_NAT_Test *
145 GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
147 struct in_addr bind_ip,
149 struct in_addr extern_ip,
150 uint16_t extern_port,
151 GNUNET_NAT_TestCallback report,
156 * Stop an active NAT test.
158 * @param tst test to stop.
161 GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst);
165 * Handle to auto-configuration in progress.
167 struct GNUNET_NAT_AutoHandle;
171 * Converts `enum GNUNET_NAT_StatusCode` to string
173 * @param err error code to resolve to a string
174 * @return point to a static string containing the error code
177 GNUNET_NAT_status2string (enum GNUNET_NAT_StatusCode err);
181 * Function called with the result from the autoconfiguration.
184 * @param diff minimal suggested changes to the original configuration
185 * to make it work (as best as we can)
186 * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code
187 * @param type what the situation of the NAT
190 (*GNUNET_NAT_AutoResultCallback)(void *cls,
191 const struct GNUNET_CONFIGURATION_Handle *diff,
192 enum GNUNET_NAT_StatusCode result,
193 enum GNUNET_NAT_Type type);
197 * Start auto-configuration routine. The transport adapters should
198 * be stopped while this function is called.
200 * @param cfg initial configuration
201 * @param cb function to call with autoconfiguration result
202 * @param cb_cls closure for @a cb
203 * @return handle to cancel operation
205 struct GNUNET_NAT_AutoHandle *
206 GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
207 GNUNET_NAT_AutoResultCallback cb,
212 * Abort autoconfiguration.
214 * @param ah handle for operation to abort
217 GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah);
222 /** @} */ /* end of group */
224 /* end of gnunet_nat_auto_service.h */