diff options
Diffstat (limited to 'src/include/gnunet_nat_auto_service.h')
-rw-r--r-- | src/include/gnunet_nat_auto_service.h | 224 |
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 | */ | ||
43 | struct 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 | */ | ||
53 | typedef 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 | */ | ||
81 | int | ||
82 | GNUNET_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 | */ | ||
94 | struct 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 | */ | ||
111 | struct GNUNET_NAT_STUN_Handle * | ||
112 | GNUNET_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 | */ | ||
125 | void | ||
126 | GNUNET_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 | */ | ||
144 | struct GNUNET_NAT_Test * | ||
145 | GNUNET_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 | */ | ||
160 | void | ||
161 | GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst); | ||
162 | |||
163 | |||
164 | /** | ||
165 | * Handle to auto-configuration in progress. | ||
166 | */ | ||
167 | struct 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 | */ | ||
176 | const char * | ||
177 | GNUNET_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 | */ | ||
189 | typedef 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 | */ | ||
205 | struct GNUNET_NAT_AutoHandle * | ||
206 | GNUNET_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 | */ | ||
216 | void | ||
217 | GNUNET_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 */ | ||