- Remove printf, use GNUNET_log INFO

[oweals/gnunet.git] / src / include / gnunet_nat_lib.h

diff --git a/src/include/gnunet_nat_lib.h b/src/include/gnunet_nat_lib.h
index e9b458df9efa385f1d9efd6b0af415dab5fd2dbd..93b441849b886abbcd513d2b305bbb86969795a7 100644 (file)
--- a/src/include/gnunet_nat_lib.h
+++ b/src/include/gnunet_nat_lib.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet.
 /*
      This file is part of GNUnet.

-     (C) 2007, 2008, 2009 Christian Grothoff (and other contributing authors)
+     (C) 2007, 2008, 2009, 2010, 2011, 2012 Christian Grothoff (and other contributing authors)

 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published

-     by the Free Software Foundation; either version 2, or (at your
+     by the Free Software Foundation; either version 3, or (at your

      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but


@@ -27,31 +27,13 @@
  */
 
 #ifndef GNUNET_NAT_LIB_H
  */
 
 #ifndef GNUNET_NAT_LIB_H

-#define GNUNET_NAT_LIB_H 1
+#define GNUNET_NAT_LIB_H

 
 

-#include "platform.h"

 #include "gnunet_util_lib.h"
 #include "gnunet_util_lib.h"

-#include "upnp.h"
-#include "natpmp.h"
-
-#include <inttypes.h>
-
-/**
- * Used to communicate with the UPnP and NAT-PMP plugins 
- * FIXME: move to src/nat/common.h
- */
-enum GNUNET_NAT_port_forwarding
-  {
-    GNUNET_NAT_PORT_ERROR,
-    GNUNET_NAT_PORT_UNMAPPED,
-    GNUNET_NAT_PORT_UNMAPPING,
-    GNUNET_NAT_PORT_MAPPING,
-    GNUNET_NAT_PORT_MAPPED
-  };
-

 
 /**
 
 /**

- * Signature of the callback passed to GNUNET_NAT_register.
+ * Signature of the callback passed to GNUNET_NAT_register for
+ * a function to call whenever our set of 'valid' addresses changes.

  *
  * @param cls closure
  * @param add_remove GNUNET_YES to mean the new public IP address, GNUNET_NO to mean
  *
  * @param cls closure
  * @param add_remove GNUNET_YES to mean the new public IP address, GNUNET_NO to mean


@@ -63,30 +45,87 @@ typedef void (*GNUNET_NAT_AddressCallback) (void *cls, int add_remove,
                                             const struct sockaddr * addr,
                                             socklen_t addrlen);
 
                                             const struct sockaddr * addr,
                                             socklen_t addrlen);
 

+
+/**
+ * Signature of the callback passed to GNUNET_NAT_register
+ * for a function to call whenever someone asks us to do connection
+ * reversal.
+ *
+ * @param cls closure
+ * @param addr public IP address of the other peer
+ * @param addrlen actual lenght of the address
+ */
+typedef void (*GNUNET_NAT_ReversalCallback) (void *cls,
+                                             const struct sockaddr * addr,
+                                             socklen_t addrlen);
+
+

 /**
  * Handle for active NAT registrations.
  */
 struct GNUNET_NAT_Handle;
 
 /**
  * Handle for active NAT registrations.
  */
 struct GNUNET_NAT_Handle;
 

+

 /**
  * Attempt to enable port redirection and detect public IP address contacting
  * UPnP or NAT-PMP routers on the local network. Use addr to specify to which
  * of the local host's addresses should the external port be mapped. The port
 /**
  * Attempt to enable port redirection and detect public IP address contacting
  * UPnP or NAT-PMP routers on the local network. Use addr to specify to which
  * of the local host's addresses should the external port be mapped. The port

- * is taken from the corresponding sockaddr_in[6] field.
+ * is taken from the corresponding sockaddr_in[6] field.  The NAT module
+ * should call the given callback for any 'plausible' external address.

  *
  *

- * @param sched the sheduler used in the program
- * @param addr the local address packets should be redirected to
- * @param addrlen actual lenght of the address
- * @param callback function to call everytime the public IP address changes
+ * @param cfg configuration to use
+ * @param is_tcp GNUNET_YES for TCP, GNUNET_NO for UDP
+ * @param adv_port advertised port (port we are either bound to or that our OS
+ *                 locally performs redirection from to our bound port).
+ * @param num_addrs number of addresses in 'addrs'
+ * @param addrs list of local addresses packets should be redirected to
+ * @param addrlens actual lengths of the addresses
+ * @param address_callback function to call everytime the public IP address changes
+ * @param reversal_callback function to call if someone wants connection reversal from us,
+ *        NULL if connection reversal is not supported

  * @param callback_cls closure for callback
  * @param callback_cls closure for callback

- * @return NULL on error, otherwise handle that can be used to unregister 
+ * @return NULL on error, otherwise handle that can be used to unregister
+ */
+struct GNUNET_NAT_Handle *
+GNUNET_NAT_register (const struct GNUNET_CONFIGURATION_Handle *cfg, int is_tcp,
+                     uint16_t adv_port, unsigned int num_addrs,
+                     const struct sockaddr **addrs, const socklen_t * addrlens,
+                     GNUNET_NAT_AddressCallback address_callback,
+                     GNUNET_NAT_ReversalCallback reversal_callback,
+                     void *callback_cls);
+
+
+/**
+ * Test if the given address is (currently) a plausible IP address for this peer.
+ *
+ * @param h the handle returned by register
+ * @param addr IP address to test (IPv4 or IPv6)
+ * @param addrlen number of bytes in addr
+ * @return GNUNET_YES if the address is plausible,
+ *         GNUNET_NO if the address is not plausible,
+ *         GNUNET_SYSERR if the address is malformed
+ */
+int
+GNUNET_NAT_test_address (struct GNUNET_NAT_Handle *h, const void *addr,
+                         socklen_t addrlen);
+
+
+/**
+ * We learned about a peer (possibly behind NAT) so run the
+ * gnunet-nat-client to send dummy ICMP responses to cause
+ * that peer to connect to us (connection reversal).
+ *
+ * @param h handle (used for configuration)
+ * @param sa the address of the peer (IPv4-only)
+ *
+ * @return GNUNET_SYSERR on error, GNUNET_NO if nat client is disabled,
+ *         GNUNET_OK otherwise

  */
  */

-struct GNUNET_NAT_Handle *GNUNET_NAT_register (struct GNUNET_SCHEDULER_Handle
-                                               *sched,
-                                               const struct sockaddr *addr,
-                                               socklen_t addrlen,
-                                               GNUNET_NAT_AddressCallback
-                                               callback, void *callback_cls);
+int
+GNUNET_NAT_run_client (struct GNUNET_NAT_Handle *h,
+                       const struct sockaddr_in *sa);
+
+

 
 /**
  * Stop port redirection and public IP address detection for the given handle.
 
 /**
  * Stop port redirection and public IP address detection for the given handle.


@@ -94,20 +133,167 @@ struct GNUNET_NAT_Handle *GNUNET_NAT_register (struct GNUNET_SCHEDULER_Handle
  *
  * @param h the handle to stop
  */
  *
  * @param h the handle to stop
  */

-void GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *h);
+void
+GNUNET_NAT_unregister (struct GNUNET_NAT_Handle *h);
+
+
+/**
+ * Handle to a NAT test.
+ */
+struct GNUNET_NAT_Test;
+
+/**
+ * Function called to report success or failure for
+ * NAT configuration test.
+ *
+ * @param cls closure
+ * @param success GNUNET_OK on success, GNUNET_NO on failure,
+ *                GNUNET_SYSERR if the test could not be
+ *                properly started (internal failure)
+ */
+typedef void (*GNUNET_NAT_TestCallback) (void *cls, int success);
+
+/**
+ * Start testing if NAT traversal works using the
+ * given configuration (IPv4-only).
+ *
+ * @param cfg configuration for the NAT traversal
+ * @param is_tcp GNUNET_YES to test TCP, GNUNET_NO to test UDP
+ * @param bnd_port port to bind to, 0 for connection reversal
+ * @param adv_port externally advertised port to use
+ * @param report function to call with the result of the test
+ * @param report_cls closure for report
+ * @return handle to cancel NAT test
+ */
+struct GNUNET_NAT_Test *
+GNUNET_NAT_test_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                       int is_tcp, uint16_t bnd_port, uint16_t adv_port,
+                       GNUNET_NAT_TestCallback report, void *report_cls);
+
+
+/**
+ * Stop an active NAT test.
+ *
+ * @param tst test to stop.
+ */
+void
+GNUNET_NAT_test_stop (struct GNUNET_NAT_Test *tst);
+
+
+/**
+ * Signature of a callback that is given an IP address.
+ *
+ * @param cls closure
+ * @param addr the address, NULL on errors
+ */
+typedef void (*GNUNET_NAT_IPCallback) (void *cls, const struct in_addr * addr);
+
+
+
+/**
+ * Opaque handle to cancel "GNUNET_NAT_mini_get_external_ipv4" operation.
+ */
+struct GNUNET_NAT_ExternalHandle;
+
+
+/**
+ * Try to get the external IPv4 address of this peer.
+ *
+ * @param timeout when to fail
+ * @param cb function to call with result
+ * @param cb_cls closure for 'cb'
+ * @return handle for cancellation (can only be used until 'cb' is called), NULL on error
+ */
+struct GNUNET_NAT_ExternalHandle *
+GNUNET_NAT_mini_get_external_ipv4 (struct GNUNET_TIME_Relative timeout,
+                                   GNUNET_NAT_IPCallback cb, void *cb_cls);
+
+
+/**
+ * Cancel operation.
+ *
+ * @param eh operation to cancel
+ */
+void
+GNUNET_NAT_mini_get_external_ipv4_cancel (struct GNUNET_NAT_ExternalHandle *eh);
+
+
+/**
+ * Handle to a mapping created with upnpc.
+ */
+struct GNUNET_NAT_MiniHandle;
+
+
+/**
+ * Start mapping the given port using (mini)upnpc.  This function
+ * should typically not be used directly (it is used within the
+ * general-purpose 'GNUNET_NAT_register' code).  However, it can be
+ * used if specifically UPnP-based NAT traversal is to be used or
+ * tested.
+ *
+ * @param port port to map
+ * @param is_tcp GNUNET_YES to map TCP, GNUNET_NO for UDP
+ * @param ac function to call with mapping result
+ * @param ac_cls closure for 'ac'
+ * @return NULL on error
+ */
+struct GNUNET_NAT_MiniHandle *
+GNUNET_NAT_mini_map_start (uint16_t port, int is_tcp,
+                           GNUNET_NAT_AddressCallback ac, void *ac_cls);
+
+
+/**
+ * Remove a mapping created with (mini)upnpc.  Calling
+ * this function will give 'upnpc' 1s to remove tha mapping,
+ * so while this function is non-blocking, a task will be
+ * left with the scheduler for up to 1s past this call.
+ *
+ * @param mini the handle
+ */
+void
+GNUNET_NAT_mini_map_stop (struct GNUNET_NAT_MiniHandle *mini);
+
+
+/**
+ * Handle to auto-configuration in progress.
+ */
+struct GNUNET_NAT_AutoHandle;
+
+
+/**
+ * Function called with the result from the autoconfiguration.
+ *
+ * @param cls closure
+ * @param diff minimal suggested changes to the original configuration
+ *             to make it work (as best as we can)
+ */
+typedef void (*GNUNET_NAT_AutoResultCallback)(void *cls,
+                                             const struct GNUNET_CONFIGURATION_Handle *diff);
+

 
 /**
 
 /**

- * Compare the sin(6)_addr fields of AF_INET or AF_INET(6) sockaddr.
- * FIXME: move to src/nat/common.h or so.
- * 
- * @param a first sockaddr
- * @param b second sockaddr
- * @return 0 if addresses are equal, non-null value otherwise 
+ * Start auto-configuration routine.  The resolver service should
+ * be available when this function is called.
+ *
+ * @param cfg initial configuration
+ * @param cb function to call with autoconfiguration result
+ * @param cb_cls closure for cb
+ * @return handle to cancel operation

  */
  */

-int GNUNET_NAT_cmp_addr (const struct sockaddr *a, 
-                        const struct sockaddr *b);
+struct GNUNET_NAT_AutoHandle *
+GNUNET_NAT_autoconfig_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                            GNUNET_NAT_AutoResultCallback cb,
+                            void *cb_cls);
+                            

 
 

+/**
+ * Abort autoconfiguration.
+ *
+ * @param ah handle for operation to abort
+ */
+void
+GNUNET_NAT_autoconfig_cancel (struct GNUNET_NAT_AutoHandle *ah);

 
 

-#endif 
+#endif

 
 /* end of gnunet_nat_lib.h */
 
 /* end of gnunet_nat_lib.h */