aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_nat_auto_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_nat_auto_service.h')
-rw-r--r--src/include/gnunet_nat_auto_service.h224
1 files changed, 224 insertions, 0 deletions
diff --git a/src/include/gnunet_nat_auto_service.h b/src/include/gnunet_nat_auto_service.h
new file mode 100644
index 000000000..90115ff8c
--- /dev/null
+++ b/src/include/gnunet_nat_auto_service.h
@@ -0,0 +1,224 @@
1/*
2 This file is part of GNUnet.
3 Copyright (C) 2007-2017 GNUnet e.V.
4
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.
9
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.
14
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.
19*/
20
21/**
22 * @author Christian Grothoff
23 * @author Milan Bouchet-Valat
24 *
25 * @file
26 * Service for testing and autoconfiguration of
27 * NAT traversal functionality
28 *
29 * @defgroup nat NAT testing library
30 *
31 * @{
32 */
33
34#ifndef GNUNET_NAT_AUTO_SERVICE_H
35#define GNUNET_NAT_AUTO_SERVICE_H
36
37#include "gnunet_util_lib.h"
38
39
40/**
41 * Handle to a NAT test.
42 */
43struct GNUNET_NAT_Test;
44
45
46/**
47 * Function called to report success or failure for
48 * NAT configuration test.
49 *
50 * @param cls closure
51 * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code
52 */
53typedef void
54(*GNUNET_NAT_TestCallback) (void *cls,
55 enum GNUNET_NAT_StatusCode result);
56
57
58/**
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
63 * to STUN requests.
64 *
65 * The function does some basic sanity checks on packet size and
66 * content, try to extract a bit of information.
67 *
68 * At the moment this only processes BIND requests, and returns the
69 * externally visible address of the request to the rest of the
70 * NAT logic.
71 *
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
80 */
81int
82GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nh,
83 const struct sockaddr *sender_addr,
84 size_t sender_addr_len,
85 const void *data,
86 size_t data_size);
87
88
89/**
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.
93 */
94struct GNUNET_NAT_STUN_Handle;
95
96
97/**
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.
102 *
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
106 * UDP socket
107 * @param cb callback in case of error
108 * @param cb_cls closure for @a cb
109 * @return NULL on error
110 */
111struct GNUNET_NAT_STUN_Handle *
112GNUNET_NAT_stun_make_request (const char *server,
113 uint16_t port,
114 struct GNUNET_NETWORK_Handle *sock,
115 GNUNET_NAT_TestCallback cb,
116 void *cb_cls);
117
118
119/**
120 * Cancel active STUN request. Frees associated resources
121 * and ensures that the callback is no longer invoked.
122 *
123 * @param rh request to cancel
124 */
125void
126GNUNET_NAT_stun_make_request_cancel (struct GNUNET_NAT_STUN_Handle *rh);
127
128
129/**
130 * Start testing if NAT traversal works using the given configuration
131 * (IPv4-only). The transport adapters should be down while using
132 * this function.
133 *
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
143 */
144struct GNUNET_NAT_Test *
145GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
146 uint8_t proto,
147 struct in_addr bind_ip,
148 uint16_t bnd_port,
149 struct in_addr extern_ip,
150 uint16_t extern_port,
151 GNUNET_NAT_TestCallback report,
152 void *report_cls);
153
154
155/**
156 * Stop an active NAT test.
157 *
158 * @param tst test to stop.
159 */
160void
161GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst);
162
163
164/**
165 * Handle to auto-configuration in progress.
166 */
167struct GNUNET_NAT_AutoHandle;
168
169
170/**
171 * Converts `enum GNUNET_NAT_StatusCode` to string
172 *
173 * @param err error code to resolve to a string
174 * @return point to a static string containing the error code
175 */
176const char *
177GNUNET_NAT_status2string (enum GNUNET_NAT_StatusCode err);
178
179
180/**
181 * Function called with the result from the autoconfiguration.
182 *
183 * @param cls closure
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
188 */
189typedef void
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);
194
195
196/**
197 * Start auto-configuration routine. The transport adapters should
198 * be stopped while this function is called.
199 *
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
204 */
205struct GNUNET_NAT_AutoHandle *
206GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
207 GNUNET_NAT_AutoResultCallback cb,
208 void *cb_cls);
209
210
211/**
212 * Abort autoconfiguration.
213 *
214 * @param ah handle for operation to abort
215 */
216void
217GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah);
218
219
220#endif
221
222/** @} */ /* end of group */
223
224/* end of gnunet_nat_auto_service.h */