clarify prettyprinter API and protocols, make sure implementations are consistent in their implemenation, doxygen fixes, indentation fixes, subtle semantic fixes

1 files changed, 75 insertions, 53 deletions

diff --git a/src/transport/transport_api_address_to_string.c b/src/transport/transport_api_address_to_string.c
index d881f9a08..afd0c7deb 100644
--- a/src/transport/transport_api_address_to_string.c
+++ b/src/transport/transport_api_address_to_string.c
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2009, 2010 Christian Grothoff (and other contributing authors)
+     (C) 2009-2014 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
@@ -17,6 +17,11 @@
      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
      Boston, MA 02111-1307, USA.
 */
+/**
+ * @file transport/transport_api_address_to_string.c
+ * @author Christian Grothoff
+ * @brief enable clients to convert addresses to human readable strings
+ */
 #include "platform.h"
 #include "gnunet_util_lib.h"
 #include "gnunet_arm_service.h"
@@ -36,7 +41,7 @@ struct GNUNET_TRANSPORT_AddressToStringContext
   GNUNET_TRANSPORT_AddressToStringCallback cb;
 
   /**
-   * Closure for cb.
+   * Closure for @e cb.
    */
   void *cb_cls;
 
@@ -45,10 +50,6 @@ struct GNUNET_TRANSPORT_AddressToStringContext
    */
   struct GNUNET_CLIENT_Connection *client;
 
-  /**
-   * When should this operation time out?
-   */
-  struct GNUNET_TIME_Absolute timeout;
 };
 
 
@@ -64,18 +65,17 @@ address_response_processor (void *cls,
                             const struct GNUNET_MessageHeader *msg)
 {
   struct GNUNET_TRANSPORT_AddressToStringContext *alucb = cls;
-  struct AddressToStringResultMessage *atsm;
+  const struct AddressToStringResultMessage *atsm;
   const char *address;
   uint16_t size;
-  uint32_t result;
+  int result;
   uint32_t addr_len;
-  char *empty_str = "";
 
   if (NULL == msg)
   {
     alucb->cb (alucb->cb_cls,
                NULL,
-               GNUNET_OK);
+               GNUNET_SYSERR);
     GNUNET_CLIENT_disconnect (alucb->client);
     GNUNET_free (alucb);
     return;
@@ -86,54 +86,72 @@ address_response_processor (void *cls,
   size = ntohs (msg->size);
   if (size < sizeof (struct AddressToStringResultMessage))
   {
-    alucb->cb (alucb->cb_cls, NULL, GNUNET_OK);
+    GNUNET_break (0);
+    alucb->cb (alucb->cb_cls,
+               NULL,
+               GNUNET_SYSERR);
     GNUNET_CLIENT_disconnect (alucb->client);
     GNUNET_free (alucb);
     return;
   }
-  atsm = (struct AddressToStringResultMessage *) msg;
-
-  result = ntohl (atsm->res);
+  atsm = (const struct AddressToStringResultMessage *) msg;
+  result = (int) ntohl (atsm->res);
   addr_len = ntohl (atsm->addr_len);
-
-  if (size == (sizeof (struct AddressToStringResultMessage)))
+  if (GNUNET_SYSERR == result)
   {
-    /* done, success depends on result */
-    alucb->cb (alucb->cb_cls, NULL, result);
-    GNUNET_CLIENT_disconnect (alucb->client);
-    GNUNET_free (alucb);
+    /* expect more replies; as this is not the last
+       call, we must pass the empty string for the address */
+    alucb->cb (alucb->cb_cls,
+               "",
+               GNUNET_NO);
+    GNUNET_CLIENT_receive (alucb->client,
+                           &address_response_processor,
+                           alucb,
+                           GNUNET_TIME_UNIT_FOREVER_REL);
     return;
   }
-
-  if (GNUNET_NO == result)
+  if (size == (sizeof (struct AddressToStringResultMessage)))
   {
-    GNUNET_log (GNUNET_ERROR_TYPE_INFO, "Client %p failed to resolve address \n",
-        alucb->client);
-    GNUNET_break (0);
-    alucb->cb (alucb->cb_cls, empty_str, GNUNET_SYSERR);
-
-    /* expect more replies */
-    GNUNET_CLIENT_receive (alucb->client, &address_response_processor, alucb,
-                           GNUNET_TIME_absolute_get_remaining (alucb->timeout));
+    if (GNUNET_OK != result)
+    {
+      GNUNET_break (0);
+      alucb->cb (alucb->cb_cls,
+                 NULL,
+                 GNUNET_SYSERR);
+      GNUNET_CLIENT_disconnect (alucb->client);
+      GNUNET_free (alucb);
+      return;
+    }
+    /* we are done (successfully, without communication errors) */
+    alucb->cb (alucb->cb_cls,
+               NULL,
+               GNUNET_OK);
+    GNUNET_CLIENT_disconnect (alucb->client);
+    GNUNET_free (alucb);
     return;
   }
-
   address = (const char *) &atsm[1];
   if ( (addr_len > (size - (sizeof (struct AddressToStringResultMessage)))) ||
        (address[addr_len -1] != '\0') )
   {
     /* invalid reply */
     GNUNET_break (0);
-    alucb->cb (alucb->cb_cls, NULL, GNUNET_SYSERR);
+    alucb->cb (alucb->cb_cls,
+               NULL,
+               GNUNET_SYSERR);
     GNUNET_CLIENT_disconnect (alucb->client);
     GNUNET_free (alucb);
     return;
   }
-
   /* expect more replies */
-  GNUNET_CLIENT_receive (alucb->client, &address_response_processor, alucb,
-                         GNUNET_TIME_absolute_get_remaining (alucb->timeout));
-  alucb->cb (alucb->cb_cls, address, GNUNET_OK);
+  GNUNET_CLIENT_receive (alucb->client,
+                         &address_response_processor,
+                         alucb,
+                         GNUNET_TIME_UNIT_FOREVER_REL);
+  /* return normal reply to caller */
+  alucb->cb (alucb->cb_cls,
+             address,
+             GNUNET_OK);
 }
 
 
@@ -146,17 +164,16 @@ address_response_processor (void *cls,
  *                (otherwise do reverse DNS lookup)
  * @param timeout how long is the lookup allowed to take at most
  * @param aluc function to call with the results
- * @param aluc_cls closure for aluc
+ * @param aluc_cls closure for @a aluc
  * @return handle to cancel the operation, NULL on error
  */
 struct GNUNET_TRANSPORT_AddressToStringContext *
-GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle
-                                    *cfg,
+GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle *cfg,
                                     const struct GNUNET_HELLO_Address *address,
                                     int numeric,
                                     struct GNUNET_TIME_Relative timeout,
-                                    GNUNET_TRANSPORT_AddressToStringCallback
-                                    aluc, void *aluc_cls)
+                                    GNUNET_TRANSPORT_AddressToStringCallback aluc,
+                                    void *aluc_cls)
 {
   size_t len;
   size_t alen;
@@ -166,7 +183,7 @@ GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle
   struct GNUNET_CLIENT_Connection *client;
   char *addrbuf;
 
-  GNUNET_assert (address != NULL);
+  GNUNET_assert (NULL != address);
   alen = address->address_length;
   slen = strlen (address->transport_name) + 1;
   len = sizeof (struct AddressLookupMessage) + alen + slen;
@@ -178,8 +195,11 @@ GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle
   client = GNUNET_CLIENT_connect ("transport", cfg);
   if (NULL == client)
     return NULL;
-  GNUNET_log (GNUNET_ERROR_TYPE_INFO, "Client %p tries to resolve for peer `%s'address len %u \n",
-      client, GNUNET_i2s (&address->peer), address->address_length);
+  GNUNET_log (GNUNET_ERROR_TYPE_INFO,
+              "Client %p tries to resolve for peer `%s'address len %u \n",
+              client,
+              GNUNET_i2s (&address->peer),
+              address->address_length);
 
   msg = GNUNET_malloc (len);
   msg->header.size = htons (len);
@@ -188,17 +208,21 @@ GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle
   msg->addrlen = htons ((uint16_t) alen);
   msg->timeout = GNUNET_TIME_relative_hton (timeout);
   addrbuf = (char *) &msg[1];
-  memcpy (addrbuf, address->address, alen);
-  memcpy (&addrbuf[alen], address->transport_name, slen);
-
+  memcpy (addrbuf,
+          address->address,
+          alen);
+  memcpy (&addrbuf[alen],
+          address->transport_name,
+          slen);
   alc = GNUNET_new (struct GNUNET_TRANSPORT_AddressToStringContext);
   alc->cb = aluc;
   alc->cb_cls = aluc_cls;
-  alc->timeout = GNUNET_TIME_relative_to_absolute (timeout);
   alc->client = client;
   GNUNET_assert (GNUNET_OK ==
-                 GNUNET_CLIENT_transmit_and_get_response (client, &msg->header,
-                                                          timeout, GNUNET_YES,
+                 GNUNET_CLIENT_transmit_and_get_response (client,
+                                                          &msg->header,
+                                                          GNUNET_TIME_UNIT_FOREVER_REL,
+                                                          GNUNET_YES,
                                                           &address_response_processor,
                                                           alc));
   GNUNET_free (msg);
@@ -212,9 +236,7 @@ GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle
  * @param pic the context handle
  */
 void
-GNUNET_TRANSPORT_address_to_string_cancel (struct
-                                           GNUNET_TRANSPORT_AddressToStringContext
-                                           *pic)
+GNUNET_TRANSPORT_address_to_string_cancel (struct GNUNET_TRANSPORT_AddressToStringContext *pic)
 {
   GNUNET_CLIENT_disconnect (pic->client);
   GNUNET_free (pic);