diff options
author | Christian Grothoff <christian@grothoff.org> | 2016-10-23 19:53:59 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2016-10-23 19:53:59 +0000 |
commit | 10f9bc91ab9d758d0d60dd672206027cd136342a (patch) | |
tree | cb8c09ffe145ae925d5a51d4bd85029bb61f7df2 /src/include/gnunet_nat_service.h | |
parent | 588f820301bf298496e7bf0e6dea7b2c60ab3936 (diff) | |
download | gnunet-10f9bc91ab9d758d0d60dd672206027cd136342a.tar.gz gnunet-10f9bc91ab9d758d0d60dd672206027cd136342a.zip |
new NAT lib client api skeleton
Diffstat (limited to 'src/include/gnunet_nat_service.h')
-rw-r--r-- | src/include/gnunet_nat_service.h | 198 |
1 files changed, 92 insertions, 106 deletions
diff --git a/src/include/gnunet_nat_service.h b/src/include/gnunet_nat_service.h index 5ac936065..28a6bc59f 100644 --- a/src/include/gnunet_nat_service.h +++ b/src/include/gnunet_nat_service.h | |||
@@ -108,7 +108,8 @@ enum GNUNET_NAT_AddressClass | |||
108 | * a function to call whenever our set of 'valid' addresses changes. | 108 | * a function to call whenever our set of 'valid' addresses changes. |
109 | * | 109 | * |
110 | * @param cls closure | 110 | * @param cls closure |
111 | * @param add_remove #GNUNET_YES to add a new public IP address, #GNUNET_NO to remove a previous (now invalid) one | 111 | * @param add_remove #GNUNET_YES to add a new public IP address, |
112 | * #GNUNET_NO to remove a previous (now invalid) one | ||
112 | * @param ac address class the address belongs to | 113 | * @param ac address class the address belongs to |
113 | * @param addr either the previous or the new public IP address | 114 | * @param addr either the previous or the new public IP address |
114 | * @param addrlen actual length of the @a addr | 115 | * @param addrlen actual length of the @a addr |
@@ -137,24 +138,6 @@ typedef void | |||
137 | 138 | ||
138 | 139 | ||
139 | /** | 140 | /** |
140 | * Signature of a callback that is given an IPv4 address | ||
141 | * which is now presumably a global IPv4 address under which | ||
142 | * this peer is visible (external IP address of our NAT). | ||
143 | * Note that the NAT may not have punched holes, so it is | ||
144 | * possible that while this is "our" IPv4 address, it still | ||
145 | * does not work for receiving traffic. | ||
146 | * | ||
147 | * @param cls closure | ||
148 | * @param add_remove #GNUNET_YES to add a new public IP address, #GNUNET_NO to remove a previous (now invalid) one | ||
149 | * @param addr the address to add or remove | ||
150 | */ | ||
151 | typedef void | ||
152 | (*GNUNET_NAT_IPv4Callback) (void *cls, | ||
153 | int add_remove, | ||
154 | const struct in_addr *addr); | ||
155 | |||
156 | |||
157 | /** | ||
158 | * Handle for active NAT registrations. | 141 | * Handle for active NAT registrations. |
159 | */ | 142 | */ |
160 | struct GNUNET_NAT_Handle; | 143 | struct GNUNET_NAT_Handle; |
@@ -175,7 +158,6 @@ struct GNUNET_NAT_Handle; | |||
175 | * @param num_addrs number of addresses in @a addrs | 158 | * @param num_addrs number of addresses in @a addrs |
176 | * @param addrs list of local addresses packets should be redirected to | 159 | * @param addrs list of local addresses packets should be redirected to |
177 | * @param addrlens actual lengths of the addresses in @a addrs | 160 | * @param addrlens actual lengths of the addresses in @a addrs |
178 | * @param ip_callback function to call whenever our (external) IPv4 address changes (or becomes known) | ||
179 | * @param address_callback function to call everytime the public IP address changes | 161 | * @param address_callback function to call everytime the public IP address changes |
180 | * @param reversal_callback function to call if someone wants connection reversal from us, | 162 | * @param reversal_callback function to call if someone wants connection reversal from us, |
181 | * NULL if connection reversal is not supported | 163 | * NULL if connection reversal is not supported |
@@ -184,12 +166,11 @@ struct GNUNET_NAT_Handle; | |||
184 | */ | 166 | */ |
185 | struct GNUNET_NAT_Handle * | 167 | struct GNUNET_NAT_Handle * |
186 | GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, | 168 | GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, |
187 | int proto, | 169 | uint8_t proto, |
188 | uint16_t adv_port, | 170 | uint16_t adv_port, |
189 | unsigned int num_addrs, | 171 | unsigned int num_addrs, |
190 | const struct sockaddr **addrs, | 172 | const struct sockaddr **addrs, |
191 | const socklen_t *addrlens, | 173 | const socklen_t *addrlens, |
192 | GNUNET_NAT_IPv4Callback ip_callback, | ||
193 | GNUNET_NAT_AddressCallback address_callback, | 174 | GNUNET_NAT_AddressCallback address_callback, |
194 | GNUNET_NAT_ReversalCallback reversal_callback, | 175 | GNUNET_NAT_ReversalCallback reversal_callback, |
195 | void *callback_cls); | 176 | void *callback_cls); |
@@ -209,7 +190,7 @@ GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
209 | * At the moment this only processes BIND requests, and returns the | 190 | * At the moment this only processes BIND requests, and returns the |
210 | * externally visible address of the request. | 191 | * externally visible address of the request. |
211 | * | 192 | * |
212 | * @param nat handle to the NAT service | 193 | * @param nh handle to the NAT service |
213 | * @param sender_addr address from which we got @a data | 194 | * @param sender_addr address from which we got @a data |
214 | * @param data the packet | 195 | * @param data the packet |
215 | * @param data_size number of bytes in @a data | 196 | * @param data_size number of bytes in @a data |
@@ -218,7 +199,7 @@ GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
218 | * #GNUNET_SYSERR on internal error handling the packet | 199 | * #GNUNET_SYSERR on internal error handling the packet |
219 | */ | 200 | */ |
220 | int | 201 | int |
221 | GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nat, | 202 | GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nh, |
222 | const struct sockaddr *sender_addr, | 203 | const struct sockaddr *sender_addr, |
223 | const void *data, | 204 | const void *data, |
224 | size_t data_size); | 205 | size_t data_size); |
@@ -230,7 +211,7 @@ GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nat, | |||
230 | * have to explicitly track all IPs that the #GNUNET_NAT_AddressCallback | 211 | * have to explicitly track all IPs that the #GNUNET_NAT_AddressCallback |
231 | * has returned so far. | 212 | * has returned so far. |
232 | * | 213 | * |
233 | * @param h the handle returned by register | 214 | * @param nh the handle returned by register |
234 | * @param addr IP address to test (IPv4 or IPv6) | 215 | * @param addr IP address to test (IPv4 or IPv6) |
235 | * @param addrlen number of bytes in @a addr | 216 | * @param addrlen number of bytes in @a addr |
236 | * @return #GNUNET_YES if the address is plausible, | 217 | * @return #GNUNET_YES if the address is plausible, |
@@ -238,7 +219,7 @@ GNUNET_NAT_stun_handle_packet (struct GNUNET_NAT_Handle *nat, | |||
238 | * #GNUNET_SYSERR if the address is malformed | 219 | * #GNUNET_SYSERR if the address is malformed |
239 | */ | 220 | */ |
240 | int | 221 | int |
241 | GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *h, | 222 | GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *nh, |
242 | const void *addr, | 223 | const void *addr, |
243 | socklen_t addrlen); | 224 | socklen_t addrlen); |
244 | 225 | ||
@@ -248,7 +229,7 @@ GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *h, | |||
248 | * gnunet-nat-client to send dummy ICMP responses to cause | 229 | * gnunet-nat-client to send dummy ICMP responses to cause |
249 | * that peer to connect to us (connection reversal). | 230 | * that peer to connect to us (connection reversal). |
250 | * | 231 | * |
251 | * @param h handle (used for configuration) | 232 | * @param nh handle (used for configuration) |
252 | * @param local_sa our local address of the peer (IPv4-only) | 233 | * @param local_sa our local address of the peer (IPv4-only) |
253 | * @param remote_sa the remote address of the peer (IPv4-only) | 234 | * @param remote_sa the remote address of the peer (IPv4-only) |
254 | * @return #GNUNET_SYSERR on error, | 235 | * @return #GNUNET_SYSERR on error, |
@@ -256,7 +237,7 @@ GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *h, | |||
256 | * #GNUNET_OK otherwise (presumably in progress) | 237 | * #GNUNET_OK otherwise (presumably in progress) |
257 | */ | 238 | */ |
258 | int | 239 | int |
259 | GNUNET_NAT_request_reversal (struct GNUNET_NAT_Handle *h, | 240 | GNUNET_NAT_request_reversal (struct GNUNET_NAT_Handle *nh, |
260 | const struct sockaddr_in *local_sa, | 241 | const struct sockaddr_in *local_sa, |
261 | const struct sockaddr_in *remote_sa); | 242 | const struct sockaddr_in *remote_sa); |
262 | 243 | ||
@@ -266,10 +247,10 @@ GNUNET_NAT_request_reversal (struct GNUNET_NAT_Handle *h, | |||
266 | * handle. This frees the handle, after having sent the needed | 247 | * handle. This frees the handle, after having sent the needed |
267 | * commands to close open ports. | 248 | * commands to close open ports. |
268 | * | 249 | * |
269 | * @param h the handle to stop | 250 | * @param nh the handle to unregister |
270 | */ | 251 | */ |
271 | void | 252 | void |
272 | GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *h); | 253 | GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *nh); |
273 | 254 | ||
274 | 255 | ||
275 | /** | 256 | /** |
@@ -279,82 +260,6 @@ struct GNUNET_NAT_Test; | |||
279 | 260 | ||
280 | 261 | ||
281 | /** | 262 | /** |
282 | * Function called to report success or failure for | ||
283 | * NAT configuration test. | ||
284 | * | ||
285 | * @param cls closure | ||
286 | * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code | ||
287 | */ | ||
288 | typedef void | ||
289 | (*GNUNET_NAT_TestCallback) (void *cls, | ||
290 | enum GNUNET_NAT_StatusCode result); | ||
291 | |||
292 | |||
293 | /** | ||
294 | * Start testing if NAT traversal works using the given configuration | ||
295 | * (IPv4-only). The transport adapters should be down while using | ||
296 | * this function. | ||
297 | * | ||
298 | * @param cfg configuration for the NAT traversal | ||
299 | * @param proto protocol to test, i.e. IPPROTO_TCP or IPPROTO_UDP | ||
300 | * @param bnd_port port to bind to, 0 to test connection reversal | ||
301 | * @param adv_port externally advertised port to use | ||
302 | * @param report function to call with the result of the test | ||
303 | * @param report_cls closure for @a report | ||
304 | * @return handle to cancel NAT test | ||
305 | */ | ||
306 | struct GNUNET_NAT_Test * | ||
307 | GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
308 | int proto, | ||
309 | uint16_t bnd_port, | ||
310 | uint16_t adv_port, | ||
311 | GNUNET_NAT_TestCallback report, | ||
312 | void *report_cls); | ||
313 | |||
314 | |||
315 | /** | ||
316 | * Stop an active NAT test. | ||
317 | * | ||
318 | * @param tst test to stop. | ||
319 | */ | ||
320 | void | ||
321 | GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst); | ||
322 | |||
323 | |||
324 | /** | ||
325 | * Handle to auto-configuration in progress. | ||
326 | */ | ||
327 | struct GNUNET_NAT_AutoHandle; | ||
328 | |||
329 | |||
330 | /** | ||
331 | * What the situation of the NAT connectivity | ||
332 | */ | ||
333 | enum GNUNET_NAT_Type | ||
334 | { | ||
335 | /** | ||
336 | * We have a direct connection | ||
337 | */ | ||
338 | GNUNET_NAT_TYPE_NO_NAT = GNUNET_OK, | ||
339 | |||
340 | /** | ||
341 | * We are under a NAT but cannot traverse it | ||
342 | */ | ||
343 | GNUNET_NAT_TYPE_UNREACHABLE_NAT, | ||
344 | |||
345 | /** | ||
346 | * We can traverse using STUN | ||
347 | */ | ||
348 | GNUNET_NAT_TYPE_STUN_PUNCHED_NAT, | ||
349 | |||
350 | /** | ||
351 | * WE can traverse using UPNP | ||
352 | */ | ||
353 | GNUNET_NAT_TYPE_UPNP_NAT | ||
354 | |||
355 | }; | ||
356 | |||
357 | /** | ||
358 | * Error Types for the NAT subsystem (which can then later be converted/resolved to a string) | 263 | * Error Types for the NAT subsystem (which can then later be converted/resolved to a string) |
359 | */ | 264 | */ |
360 | enum GNUNET_NAT_StatusCode | 265 | enum GNUNET_NAT_StatusCode |
@@ -458,6 +363,87 @@ enum GNUNET_NAT_StatusCode | |||
458 | 363 | ||
459 | 364 | ||
460 | /** | 365 | /** |
366 | * Function called to report success or failure for | ||
367 | * NAT configuration test. | ||
368 | * | ||
369 | * @param cls closure | ||
370 | * @param result #GNUNET_NAT_ERROR_SUCCESS on success, otherwise the specific error code | ||
371 | */ | ||
372 | typedef void | ||
373 | (*GNUNET_NAT_TestCallback) (void *cls, | ||
374 | enum GNUNET_NAT_StatusCode result); | ||
375 | |||
376 | |||
377 | /** | ||
378 | * Start testing if NAT traversal works using the given configuration | ||
379 | * (IPv4-only). The transport adapters should be down while using | ||
380 | * this function. | ||
381 | * | ||
382 | * @param cfg configuration for the NAT traversal | ||
383 | * @param proto protocol to test, i.e. IPPROTO_TCP or IPPROTO_UDP | ||
384 | * @param bind_ip IPv4 address to bind to | ||
385 | * @param bnd_port port to bind to, 0 to test connection reversal | ||
386 | * @param extern_ip IPv4 address to externally advertise | ||
387 | * @param extern_port externally advertised port to use | ||
388 | * @param report function to call with the result of the test | ||
389 | * @param report_cls closure for @a report | ||
390 | * @return handle to cancel NAT test | ||
391 | */ | ||
392 | struct GNUNET_NAT_Test * | ||
393 | GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
394 | uint8_t proto, | ||
395 | struct in_addr bind_ip, | ||
396 | uint16_t bnd_port, | ||
397 | struct in_addr extern_ip, | ||
398 | uint16_t extern_port, | ||
399 | GNUNET_NAT_TestCallback report, | ||
400 | void *report_cls); | ||
401 | |||
402 | |||
403 | /** | ||
404 | * Stop an active NAT test. | ||
405 | * | ||
406 | * @param tst test to stop. | ||
407 | */ | ||
408 | void | ||
409 | GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst); | ||
410 | |||
411 | |||
412 | /** | ||
413 | * Handle to auto-configuration in progress. | ||
414 | */ | ||
415 | struct GNUNET_NAT_AutoHandle; | ||
416 | |||
417 | |||
418 | /** | ||
419 | * What the situation of the NAT connectivity | ||
420 | */ | ||
421 | enum GNUNET_NAT_Type | ||
422 | { | ||
423 | /** | ||
424 | * We have a direct connection | ||
425 | */ | ||
426 | GNUNET_NAT_TYPE_NO_NAT = GNUNET_OK, | ||
427 | |||
428 | /** | ||
429 | * We are under a NAT but cannot traverse it | ||
430 | */ | ||
431 | GNUNET_NAT_TYPE_UNREACHABLE_NAT, | ||
432 | |||
433 | /** | ||
434 | * We can traverse using STUN | ||
435 | */ | ||
436 | GNUNET_NAT_TYPE_STUN_PUNCHED_NAT, | ||
437 | |||
438 | /** | ||
439 | * WE can traverse using UPNP | ||
440 | */ | ||
441 | GNUNET_NAT_TYPE_UPNP_NAT | ||
442 | |||
443 | }; | ||
444 | |||
445 | |||
446 | /** | ||
461 | * Converts `enum GNUNET_NAT_StatusCode` to string | 447 | * Converts `enum GNUNET_NAT_StatusCode` to string |
462 | * | 448 | * |
463 | * @param err error code to resolve to a string | 449 | * @param err error code to resolve to a string |