9 files changed, 652 insertions, 14 deletions

diff --git a/src/transport/Makefile.am b/src/transport/Makefile.am
index e004d9c00..5c8a997a9 100644
--- a/src/transport/Makefile.am
+++ b/src/transport/Makefile.am
@@ -150,10 +150,10 @@ gnunet_service_transport_LDADD = \
 gnunet_service_transport_new_SOURCES = \
  gnunet-service-transport-new.c gnunet-service-transport.h \
  gnunet-service-transport_blacklist.h \
- gnunet-service-transport_clients.h \
- gnunet-service-transport_hello.h \
+ gnunet-service-transport_clients.h gnunet-service-transport_clients.c \
+ gnunet-service-transport_hello.h gnunet-service-transport_hello.c \
  gnunet-service-transport_neighbours.h \
- gnunet-service-transport_plugins.h \
+ gnunet-service-transport_plugins.h gnunet-service-transport_plugins.c \
  gnunet-service-transport_validation.h 
 gnunet_service_transport_new_LDADD = \
   $(top_builddir)/src/hello/libgnunethello.la \
diff --git a/src/transport/gnunet-service-transport-new.c b/src/transport/gnunet-service-transport-new.c
index c039d5963..bade1cf5a 100644
--- a/src/transport/gnunet-service-transport-new.c
+++ b/src/transport/gnunet-service-transport-new.c
@@ -27,6 +27,7 @@
 #include "gnunet_util_lib.h"
 #include "gnunet_statistics_service.h"
 #include "gnunet_transport_service.h"
+#include "gnunet_peerinfo_service.h"
 #include "gnunet-service-transport.h"
 #include "gnunet-service-transport_blacklist.h"
 #include "gnunet-service-transport_clients.h"
@@ -53,14 +54,39 @@ const struct GNUNET_CONFIGURATION_Handle *GST_cfg;
 struct GNUNET_PeerIdentity GST_my_identity;
 
 /**
+ * Handle to peerinfo service.
+ */
+struct GNUNET_PEERINFO_Handle *GST_peerinfo;
+
+/**
+ * Our public key.
+ */
+struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded GST_my_public_key;
+
+/**
  * Our private key.
  */
 static struct GNUNET_CRYPTO_RsaPrivateKey *my_private_key;
 
+
 /**
- * Our public key.
+ * My HELLO has changed. Tell everyone who should know.
+ *
+ * @param cls unused
+ * @param hello new HELLO
  */
-static struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded my_public_key;
+static void
+process_hello_update (void *cls,
+                      const struct GNUNET_MessageHeader *hello)
+{
+  GST_clients_broadcast (hello);
+#if 0
+  GNUNET_CONTAINER_multihashmap_iterate (neighbours,
+                                         &transmit_our_hello_if_pong,
+                                         NULL);
+#endif
+}
+
 
 /**
  * Function called when the service shuts down.  Unloads our plugins
@@ -73,6 +99,13 @@ static void
 shutdown_task (void *cls, 
                const struct GNUNET_SCHEDULER_TaskContext *tc)
 {
+  GST_hello_stop ();
+
+  if (GST_peerinfo != NULL)
+    {
+      GNUNET_PEERINFO_disconnect (GST_peerinfo);
+      GST_peerinfo = NULL;
+    }
   if (GST_stats != NULL)
     {
       GNUNET_STATISTICS_destroy (GST_stats, GNUNET_NO);
@@ -128,11 +161,20 @@ run (void *cls,
       return;
     }
   GST_stats = GNUNET_STATISTICS_create ("transport", c);
-  GNUNET_CRYPTO_rsa_key_get_public (my_private_key, &my_public_key);
-  GNUNET_CRYPTO_hash (&my_public_key,
-                      sizeof (my_public_key), &GST_my_identity.hashPubKey);
+  GST_peerinfo = GNUNET_PEERINFO_connect (c);
+  GNUNET_CRYPTO_rsa_key_get_public (my_private_key, &GST_my_public_key);
+  GNUNET_CRYPTO_hash (&GST_my_public_key,
+                      sizeof (GST_my_public_key), &GST_my_identity.hashPubKey);
   GNUNET_SCHEDULER_add_delayed (GNUNET_TIME_UNIT_FOREVER_REL,
                                 &shutdown_task, NULL);
+  if (GST_peerinfo == NULL)
+    {
+      GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
+                  _("Could not access PEERINFO service.  Exiting.\n"));
+      GNUNET_SCHEDULER_shutdown ();
+      return;
+    }
+  GST_hello_start (&process_hello_update, NULL);
 }
 
 
diff --git a/src/transport/gnunet-service-transport.h b/src/transport/gnunet-service-transport.h
index 8db60d707..d6eda464a 100644
--- a/src/transport/gnunet-service-transport.h
+++ b/src/transport/gnunet-service-transport.h
@@ -45,6 +45,15 @@ extern const struct GNUNET_CONFIGURATION_Handle *GST_cfg;
  */
 extern struct GNUNET_PeerIdentity GST_my_identity;
 
+/**
+ * Handle to peerinfo service.
+ */
+extern struct GNUNET_PEERINFO_Handle *GST_peerinfo;
+
+/**
+ * Our public key.
+ */
+extern struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded GST_my_public_key;
 
 #endif
 /* end of file gnunet-service-transport_plugins.h */
diff --git a/src/transport/gnunet-service-transport_clients.c b/src/transport/gnunet-service-transport_clients.c
new file mode 100644
index 000000000..9fe367c16
--- /dev/null
+++ b/src/transport/gnunet-service-transport_clients.c
@@ -0,0 +1,62 @@
+/*
+     This file is part of GNUnet.
+     (C) 2010,2011 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
+     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
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     General Public License for more details.
+
+     You should have received a copy of the GNU General Public License
+     along with GNUnet; see the file COPYING.  If not, write to the
+     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+     Boston, MA 02111-1307, USA.
+*/
+
+/**
+ * @file transport/gnunet-service-transport_clients.c
+ * @brief plugin management API
+ * @author Christian Grothoff
+ */
+#include "platform.h"
+#include "gnunet-service-transport_clients.h"
+
+
+/**
+ * Start handling requests from clients.
+ *
+ * @param server server used to accept clients from.
+ */
+void 
+GST_clients_start (struct GNUNET_SERVER_Handle *server)
+{
+}
+
+
+/**
+ * Stop processing clients.
+ */
+void
+GST_clients_stop ()
+{
+}
+
+
+/**
+ * Broadcast the given message to all of our clients.
+ *
+ * @param msg message to broadcast
+ */
+void
+GST_clients_broadcast (const struct GNUNET_MessageHeader *msg)
+{
+  
+}
+
+
+/* end of file gnunet-service-transport_clients.c */
diff --git a/src/transport/gnunet-service-transport_clients.h b/src/transport/gnunet-service-transport_clients.h
index 1884ece5d..aa696b1ab 100644
--- a/src/transport/gnunet-service-transport_clients.h
+++ b/src/transport/gnunet-service-transport_clients.h
@@ -31,19 +31,29 @@
 
 
 /**
+ * Start handling requests from clients.
  *
+ * @param server server used to accept clients from.
  */
 void 
 GST_clients_start (struct GNUNET_SERVER_Handle *server);
 
 
 /**
- *
+ * Stop processing clients.
  */
 void
 GST_clients_stop (void);
 
 
+/**
+ * Broadcast the given message to all of our clients.
+ *
+ * @param msg message to broadcast
+ */
+void
+GST_clients_broadcast (const struct GNUNET_MessageHeader *msg);
+
 
 
 #endif
diff --git a/src/transport/gnunet-service-transport_hello.c b/src/transport/gnunet-service-transport_hello.c
new file mode 100644
index 000000000..cf7459769
--- /dev/null
+++ b/src/transport/gnunet-service-transport_hello.c
@@ -0,0 +1,358 @@
+/*
+     This file is part of GNUnet.
+     (C) 2010,2011 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
+     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
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     General Public License for more details.
+
+     You should have received a copy of the GNU General Public License
+     along with GNUnet; see the file COPYING.  If not, write to the
+     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+     Boston, MA 02111-1307, USA.
+*/
+
+/**
+ * @file transport/gnunet-service-transport_hello.c
+ * @brief hello management implementation
+ * @author Christian Grothoff
+ */
+#include "platform.h"
+#include "gnunet_hello_lib.h"
+#include "gnunet_peerinfo_service.h"
+#include "gnunet_statistics_service.h"
+#include "gnunet-service-transport_hello.h"
+#include "gnunet-service-transport.h"
+#include "gnunet-service-transport_plugins.h"
+
+/**
+ * After how long do we expire an address in a HELLO that we just
+ * validated?  This value is also used for our own addresses when we
+ * create a HELLO.
+ */
+#define HELLO_ADDRESS_EXPIRATION GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_HOURS, 12)
+
+/**
+ * How often do we refresh our HELLO (due to expiration concerns)?
+ */
+#define HELLO_REFRESH_PERIOD GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_HOURS, 6)
+
+
+/**
+ * Entry in linked list of network addresses for ourselves.  Also
+ * includes a cached signature for 'struct TransportPongMessage's.
+ */
+struct OwnAddressList
+{
+  /**
+   * This is a doubly-linked list.
+   */
+  struct OwnAddressList *next;
+
+  /**
+   * This is a doubly-linked list.
+   */
+  struct OwnAddressList *prev;
+
+  /**
+   * Name of the plugin.
+   */
+  char *plugin_name;
+
+  /**
+   * How long until the current signature expires? (ZERO if the
+   * signature was never created).
+   */
+  struct GNUNET_TIME_Absolute pong_sig_expires;
+
+  /**
+   * Signature for a 'struct TransportPongMessage' for this address.
+   */
+  struct GNUNET_CRYPTO_RsaSignature pong_signature;
+
+  /**
+   * Length of addr.
+   */
+  size_t addrlen;
+
+};
+
+
+/**
+ * Our HELLO message.
+ */
+static struct GNUNET_HELLO_Message *our_hello;
+
+/**
+ * Function to call on HELLO changes.
+ */
+static GST_HelloCallback hello_cb;
+
+/**
+ * Closure for 'hello_cb'.
+ */ 
+static void *hello_cb_cls;
+
+/**
+ * Head of my addresses.
+ */
+struct OwnAddressList *oal_head;
+
+/**
+ * Tail of my addresses.
+ */
+struct OwnAddressList *oal_tail;
+
+/**
+ * Identifier of 'refresh_hello' task.
+ */
+static GNUNET_SCHEDULER_TaskIdentifier hello_task;
+
+
+/**
+ * Closure for 'address_generator'.
+ */
+struct GeneratorContext
+{
+  /**
+   * Where are we in the DLL?
+   */
+  struct OwnAddressList *addr_pos;
+  
+  /**
+   * When do addresses expire?
+   */
+  struct GNUNET_TIME_Absolute expiration;
+};
+
+
+/**
+ * Add an address from the 'OwnAddressList' to the buffer.
+ * 
+ * @param cls the 'struct GeneratorContext'
+ * @param max maximum number of bytes left
+ * @param buf where to write the address
+ */
+static size_t
+address_generator (void *cls, size_t max, void *buf)
+{
+  struct GeneratorContext *gc = cls;
+  size_t ret;
+
+  if (NULL == gc->addr_pos)
+      return 0;    
+  ret = GNUNET_HELLO_add_address (gc->addr_pos->plugin_name,
+                                  gc->expiration,
+                                  &gc->addr_pos[1],
+                                  gc->addr_pos->addrlen,
+                                  buf, max);
+  gc->addr_pos = gc->addr_pos->next;
+  return ret;
+}
+
+
+/**
+ * Construct our HELLO message from all of the addresses of
+ * all of the transports.
+ *
+ * @param cls unused
+ * @param tc scheduler context
+ */
+static void
+refresh_hello_task (void *cls,
+                    const struct GNUNET_SCHEDULER_TaskContext *tc)
+{
+  struct GeneratorContext gc;
+
+  hello_task = GNUNET_SCHEDULER_NO_TASK;
+  gc.addr_pos = oal_head;
+  gc.expiration = GNUNET_TIME_relative_to_absolute (HELLO_ADDRESS_EXPIRATION);
+  GNUNET_free (our_hello);
+  our_hello = GNUNET_HELLO_create (&GST_my_public_key, 
+                                   &address_generator, 
+                                   &gc);
+#if DEBUG_TRANSPORT
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG | GNUNET_ERROR_TYPE_BULK,
+              "Refreshed my `%s', new size is %d\n", "HELLO", 
+              GNUNET_HELLO_size(our_hello));
+#endif
+  GNUNET_STATISTICS_update (GST_stats,
+                            gettext_noop ("# refreshed my HELLO"),
+                            1,
+                            GNUNET_NO);
+  if (NULL != hello_cb)
+    hello_cb (hello_cb_cls, GST_hello_get());
+  GNUNET_PEERINFO_add_peer (GST_peerinfo, our_hello);
+  hello_task
+    = GNUNET_SCHEDULER_add_delayed (HELLO_REFRESH_PERIOD,
+                                    &refresh_hello_task,
+                                    NULL);
+
+}
+
+
+/**
+ * Schedule task to refresh hello (unless such a
+ * task exists already).
+ */
+static void
+refresh_hello ()
+{
+  if (hello_task != GNUNET_SCHEDULER_NO_TASK)
+    GNUNET_SCHEDULER_cancel (hello_task);
+  hello_task
+    = GNUNET_SCHEDULER_add_now (&refresh_hello_task,
+                                NULL);  
+}
+
+
+/**
+ * Initialize the HELLO module.
+ *
+ * @param cb function to call whenever our HELLO changes
+ * @param cb_cls closure for cb
+ */
+void 
+GST_hello_start (GST_HelloCallback cb,
+                 void *cb_cls)
+{
+  hello_cb = cb;
+  hello_cb_cls = cb_cls;
+  our_hello = GNUNET_HELLO_create (&GST_my_public_key, 
+                                   NULL, NULL);
+  refresh_hello ();
+}
+
+
+/**
+ * Shutdown the HELLO module.
+ */
+void
+GST_hello_stop ()
+{
+  hello_cb = NULL;
+  hello_cb_cls = NULL;
+  if (GNUNET_SCHEDULER_NO_TASK != hello_task)
+    {
+      GNUNET_SCHEDULER_cancel (hello_task);
+      hello_task = GNUNET_SCHEDULER_NO_TASK;
+    }
+  if (NULL != our_hello)
+    {
+      GNUNET_free (our_hello);
+      our_hello = NULL;
+    }
+}
+
+
+/**
+ * Obtain this peers HELLO message.
+ *
+ * @return our HELLO message
+ */
+const struct GNUNET_MessageHeader *
+GST_hello_get ()
+{
+  return (struct GNUNET_MessageHeader*) our_hello;
+}
+
+
+/**
+ * Add or remove an address from this peer's HELLO message.
+ *
+ * @param addremove GNUNET_YES to add, GNUNET_NO to remove
+ * @param plugin_name name of the plugin for which this is an address
+ * @param plugin_address address in a plugin-specific format
+ * @param plugin_address_len number of bytes in plugin_address
+ */
+void
+GST_hello_modify_addresses (int addremove,
+                            const char *plugin_name,
+                            const void *plugin_address,
+                            size_t plugin_address_len)
+{
+  struct OwnAddressList *al;
+
+#if DEBUG_TRANSPORT
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
+              (add_remove == GNUNET_YES)
+              ? "Adding `%s':%s to the set of our addresses\n"
+              : "Removing `%s':%s from the set of our addresses\n",
+              GST_plugins_a2s (plugin_name,
+                               addr, addrlen),
+              p->short_name);
+#endif
+  GNUNET_assert (plugin_address != NULL);
+  if (GNUNET_NO == addremove)
+    {
+      for (al = oal_head; al != NULL; al = al->next)
+        if ( (plugin_address_len == al->addrlen) &&
+             (0 == strcmp (al->plugin_name, plugin_name)) &&
+             (0 == memcmp (plugin_address, &al[1], plugin_address_len)) )
+          {
+            GNUNET_CONTAINER_DLL_remove (oal_head,
+                                         oal_tail,
+                                         al);
+            GNUNET_free (al->plugin_name);
+            GNUNET_free (al);
+            refresh_hello ();
+            return;         
+          }
+      /* address to be removed not found!? */
+      GNUNET_break (0);
+      return;
+    }
+  al = GNUNET_malloc (sizeof (struct OwnAddressList) + plugin_address_len);
+  GNUNET_CONTAINER_DLL_insert (oal_head,
+                               oal_tail,
+                               al);
+  al->plugin_name = GNUNET_strdup (plugin_name);
+  al->addrlen = plugin_address_len;
+  memcpy (&al[1], plugin_address, plugin_address_len);
+  refresh_hello ();
+}
+
+
+/**
+ * Test if a particular address is one of ours.
+ *
+ * @param plugin_name name of the plugin for which this is an address
+ * @param plugin_address address in a plugin-specific format
+ * @param plugin_address_len number of bytes in plugin_address
+ * @param sig location where to cache PONG signatures for this address [set]
+ * @param sig_expiration how long until the current 'sig' expires?
+ *            (ZERO if sig was never created) [set]
+ * @return GNUNET_YES if this is one of our addresses,
+ *         GNUNET_NO if not
+ */
+int
+GST_hello_test_address (const char *plugin_name,
+                        const void *plugin_address,
+                        size_t plugin_address_len,
+                        struct GNUNET_CRYPTO_RsaSignature **sig,
+                        struct GNUNET_TIME_Absolute **sig_expiration)
+{
+  struct OwnAddressList *al;
+
+  for (al = oal_head; al != NULL; al = al->next)
+    if ( (plugin_address_len == al->addrlen) &&
+         (0 == strcmp (al->plugin_name, plugin_name)) &&
+         (0 == memcmp (plugin_address, &al[1], plugin_address_len)) )
+      {
+        *sig = &al->pong_signature;
+        *sig_expiration = &al->pong_sig_expires;
+        return GNUNET_YES;
+      }
+  *sig = NULL;
+  *sig_expiration = NULL;
+  return GNUNET_NO;
+}
+
+
+/* end of file gnunet-service-transport_hello.c */
diff --git a/src/transport/gnunet-service-transport_hello.h b/src/transport/gnunet-service-transport_hello.h
index 75fef07ae..d34162841 100644
--- a/src/transport/gnunet-service-transport_hello.h
+++ b/src/transport/gnunet-service-transport_hello.h
@@ -32,25 +32,49 @@
 
 
 /**
+ * Signature of a function to call whenever our hello changes.
  *
+ * @param cls closure
+ * @param hello updated HELLO
  */
-void 
-GST_hello_start (void);
+typedef void (*GST_HelloCallback)(void *cls,
+                                  const struct GNUNET_MessageHeader *hello);
+
 
 /**
+ * Initialize the HELLO module.
  *
+ * @param cb function to call whenever our HELLO changes
+ * @param cb_cls closure for cb
+ */
+void 
+GST_hello_start (GST_HelloCallback cb,
+                 void *cb_cls);
+
+
+/**
+ * Shutdown the HELLO module.
  */
 void
 GST_hello_stop (void);
 
+
 /**
+ * Obtain this peers HELLO message.
  *
+ * @return our HELLO message
  */
 const struct GNUNET_MessageHeader *
 GST_hello_get (void);
 
+
 /**
+ * Add or remove an address from this peer's HELLO message.
  *
+ * @param addremove GNUNET_YES to add, GNUNET_NO to remove
+ * @param plugin_name name of the plugin for which this is an address
+ * @param plugin_address address in a plugin-specific format
+ * @param plugin_address_len number of bytes in plugin_address
  */
 void
 GST_hello_modify_addresses (int addremove,
@@ -58,13 +82,25 @@ GST_hello_modify_addresses (int addremove,
                             const void *plugin_address,
                             size_t plugin_address_len);
 
+
 /**
+ * Test if a particular address is one of ours.
  *
+ * @param plugin_name name of the plugin for which this is an address
+ * @param plugin_address address in a plugin-specific format
+ * @param plugin_address_len number of bytes in plugin_address
+ * @param sig location where to cache PONG signatures for this address [set]
+ * @param sig_expiration how long until the current 'sig' expires?
+ *            (ZERO if sig was never created) [set]
+ * @return GNUNET_YES if this is one of our addresses,
+ *         GNUNET_NO if not
  */
 int
 GST_hello_test_address (const char *plugin_name,
                         const void *plugin_address,
-                        size_t plugin_address_len);
+                        size_t plugin_address_len,
+                        struct GNUNET_CRYPTO_RsaSignature **sig,
+                        struct GNUNET_TIME_Absolute **sig_expiration);
 
 
 #endif
diff --git a/src/transport/gnunet-service-transport_plugins.c b/src/transport/gnunet-service-transport_plugins.c
new file mode 100644
index 000000000..0db7120fd
--- /dev/null
+++ b/src/transport/gnunet-service-transport_plugins.c
@@ -0,0 +1,94 @@
+/*
+     This file is part of GNUnet.
+     (C) 2010,2011 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
+     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
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     General Public License for more details.
+
+     You should have received a copy of the GNU General Public License
+     along with GNUnet; see the file COPYING.  If not, write to the
+     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+     Boston, MA 02111-1307, USA.
+*/
+
+/**
+ * @file transport/gnunet-service-transport_plugins.c
+ * @brief plugin management
+ * @author Christian Grothoff
+ */
+#include "platform.h"
+#include "gnunet-service-transport_plugins.h"
+
+
+/**
+ * Load and initialize all plugins.  The respective functions will be
+ * invoked by the plugins when the respective events happen.  The
+ * closure will be set to a 'const char*' containing the name of the
+ * plugin that caused the call.
+ *
+ * @param recv_cb function to call when data is received
+ * @param address_cb function to call when our public addresses changed
+ * @param traffic_cb function to call for flow control
+ * @param session_end_cb function to call when a session was terminated
+ * @param cost_cb function to call about ATS cost changes
+ * @return GNUNET_OK on success
+ */
+int 
+GST_plugins_load (GNUNET_TRANSPORT_PluginReceiveCallback recv_cb,
+                  GNUNET_TRANSPORT_AddressNotification address_cb,
+                  GNUNET_TRANSPORT_TrafficReport traffic_cb,
+                  GNUNET_TRANSPORT_SessionEnd session_end_cb,
+                  GNUNET_TRANSPORT_CostReport cost_cb)
+{
+  return GNUNET_SYSERR;
+}
+
+
+/**
+ * Unload all plugins
+ */
+void
+GST_plugins_unload ()
+{
+}
+
+
+/**
+ * Obtain the plugin API based on a plugin name.
+ *
+ * @param name name of the plugin
+ * @return the plugin's API, NULL if the plugin is not loaded
+ */
+struct GNUNET_TRANSPORT_PluginFunctions *
+GST_plugins_find (const char *name)
+{
+  return NULL;
+}
+
+
+/**
+ * Convert a given address to a human-readable format.  Note that the
+ * return value will be overwritten on the next call to this function.
+ * 
+ * @param name plugin name
+ * @param addr binary address in plugin-specific format
+ * @param addrlen number of bytes in 'addr'
+ * @return statically allocated (!) human-readable address
+ */
+const char *
+GST_plugins_a2s (const char *name,
+                 const void *addr,
+                 size_t addrlen)
+{
+  return "FIXME";
+}
+
+
+/* end of file gnunet-service-transport_plugins.c */
diff --git a/src/transport/gnunet-service-transport_plugins.h b/src/transport/gnunet-service-transport_plugins.h
index 0d62bbf79..3ad09b7f6 100644
--- a/src/transport/gnunet-service-transport_plugins.h
+++ b/src/transport/gnunet-service-transport_plugins.h
@@ -33,7 +33,17 @@
 
 
 /**
+ * Load and initialize all plugins.  The respective functions will be
+ * invoked by the plugins when the respective events happen.  The
+ * closure will be set to a 'const char*' containing the name of the
+ * plugin that caused the call.
  *
+ * @param recv_cb function to call when data is received
+ * @param address_cb function to call when our public addresses changed
+ * @param traffic_cb function to call for flow control
+ * @param session_end_cb function to call when a session was terminated
+ * @param cost_cb function to call about ATS cost changes
+ * @return GNUNET_OK on success
  */
 int 
 GST_plugins_load (GNUNET_TRANSPORT_PluginReceiveCallback recv_cb,
@@ -44,19 +54,36 @@ GST_plugins_load (GNUNET_TRANSPORT_PluginReceiveCallback recv_cb,
 
 
 /**
- *
+ * Unload all plugins
  */
-int 
+void
 GST_plugins_unload (void);
 
 
 /**
+ * Obtain the plugin API based on a plugin name.
  *
+ * @param name name of the plugin
+ * @return the plugin's API, NULL if the plugin is not loaded
  */
 struct GNUNET_TRANSPORT_PluginFunctions *
 GST_plugins_find (const char *name);
 
 
+/**
+ * Convert a given address to a human-readable format.  Note that the
+ * return value will be overwritten on the next call to this function.
+ * 
+ * @param name plugin name
+ * @param addr binary address in plugin-specific format
+ * @param addrlen number of bytes in 'addr'
+ * @return statically allocated (!) human-readable address
+ */
+const char *
+GST_plugins_a2s (const char *name,
+                 const void *addr,
+                 size_t addrlen);
+
 
 #endif
 /* end of file gnunet-service-transport_plugins.h */