Merge branch 'master' of git+ssh://gnunet.org/gnunet

src/transport/test_communicator_unix.c

@@ -85,20 +85,42 @@ add_address_cb (void *cls,
 }
 
 
+/**
+ * @brief Callback that informs whether the requested queue will be
+ * established
+ *
+ * Implements #GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback.
+ *
+ * @param cls Closure - unused
+ * @param tc_h Communicator handle - unused
+ * @param will_try #GNUNET_YES if queue will be established
+ *                #GNUNET_NO if queue will not be established (bogous address)
+ */
 static void
 queue_create_reply_cb (void *cls,
                        struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
-                       int success)
+                       int will_try)
 {
-  if (GNUNET_YES == success)
+  if (GNUNET_YES == will_try)
     LOG (GNUNET_ERROR_TYPE_DEBUG,
-        "Got Queue!\n");
+        "Queue will be established!\n");
   else
-    LOG (GNUNET_ERROR_TYPE_DEBUG,
-        "Failed getting queue!\n");
+    LOG (GNUNET_ERROR_TYPE_WARNING,
+        "Queue won't be established (bougus address?)!\n");
 }
 
 
+/**
+ * @brief Handle opening of queue
+ *
+ * Issues sending of test data
+ *
+ * Implements #GNUNET_TRANSPORT_TESTING_AddQueueCallback
+ *
+ * @param cls Closure
+ * @param tc_h Communicator handle
+ * @param tc_queue Handle to newly opened queue
+ */
 static void
 add_queue_cb (void *cls,
               struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
@@ -112,6 +134,28 @@ add_queue_cb (void *cls,
 }
 
 
+/**
+ * @brief Handle an incoming message
+ *
+ * Implements #GNUNET_TRANSPORT_TESTING_IncomingMessageCallback
+
+ * @param cls Closure
+ * @param tc_h Handle to the receiving communicator
+ * @param msg Received message
+ */
+void
+incoming_message_cb (void *cls,
+    struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
+    const struct GNUNET_MessageHeader *msg)
+{
+}
+
+
+/**
+ * @brief Main function called by the scheduler
+ *
+ * @param cls Closure - Handle to configuration
+ */
 static void
 run (void *cls)
 {
@@ -125,6 +169,7 @@ run (void *cls)
       NULL,
       &queue_create_reply_cb,
       &add_queue_cb,
+      NULL,
       NULL); /* cls */
   tc_hs[1] = GNUNET_TRANSPORT_TESTING_transport_communicator_service_start (
       "transport",
@@ -134,6 +179,7 @@ run (void *cls)
       &add_address_cb,
       NULL,
       &add_queue_cb,
+      NULL,
       NULL); /* cls */
 }
 

src/transport/transport-testing2.c

@@ -38,6 +38,9 @@
 #define LOG(kind, ...) GNUNET_log_from (kind, "transport-testing2", __VA_ARGS__)
 
 
+/**
+ * @brief Handle to a transport communicator
+ */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle
 {
   /**
@@ -97,12 +100,12 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle
   char *c_address;
 
   /**
-   * @brief Head of the queues
+   * @brief Head of the DLL of queues associated with this communicator
    */
   struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *queue_head;
 
   /**
-   * @brief Tail of the queues
+   * @brief Tail of the DLL of queues associated with this communicator
    */
   struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *queue_tail;
 
@@ -128,6 +131,11 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle
    */
   GNUNET_TRANSPORT_TESTING_AddQueueCallback add_queue_cb;
 
+  /**
+   * @brief Callback called when a new communicator connects
+   */
+  GNUNET_TRANSPORT_TESTING_IncomingMessageCallback incoming_msg_cb;
+
   /**
    * @brief Closure to the callback
    */
@@ -135,6 +143,9 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle
 };
 
 
+/**
+ * @brief Queue of a communicator and some context
+ */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue
 {
   /**
@@ -143,7 +154,11 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue
   struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h;
 
   /**
-   * @brief Task to request the opening of a view
+   * @brief Envelope to a message that requests the opening of the queue.
+   *
+   * If the client already requests queue(s), but the communicator is not yet
+   * connected, we cannot send the request to open the queue. Save it until the
+   * communicator becomes available and send it then.
    */
   struct GNUNET_MQ_Envelope *open_queue_env;
 
@@ -189,6 +204,9 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue
 };
 
 
+/**
+ * @brief Handle/Context to a single transmission
+ */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission
 {
 };
@@ -221,7 +239,9 @@ check_communicator_available (
 /**
  * @brief Handle new communicator
  *
- * @param cls Closure
+ * Store characteristics of communicator, call respective client callback.
+ *
+ * @param cls Closure - communicator handle
  * @param msg Message struct
  */
 static void
@@ -272,6 +292,14 @@ check_add_address (void *cls,
 }
 
 
+/**
+ * @brief The communicator informs about an address.
+ *
+ * Store address and call client callback.
+ *
+ * @param cls Closure - communicator handle
+ * @param msg Message
+ */
 static void
 handle_add_address (void *cls,
                     const struct GNUNET_TRANSPORT_AddAddressMessage *msg)
@@ -297,6 +325,63 @@ handle_add_address (void *cls,
 }
 
 
+/**
+ * Incoming message.  Test message is well-formed.
+ *
+ * @param cls the client
+ * @param msg the send message that was sent
+ * @return #GNUNET_OK if message is well-formed
+ */
+static int
+check_incoming_msg (void *cls,
+                   const struct GNUNET_TRANSPORT_IncomingMessage *msg)
+{
+  //struct TransportClient *tc = cls;
+
+  //if (CT_COMMUNICATOR != tc->type)
+  //{
+  //  GNUNET_break (0);
+  //  return GNUNET_SYSERR;
+  //}
+  GNUNET_MQ_check_boxed_message (msg);
+  return GNUNET_OK;
+}
+
+
+/**
+ * @brief Receive an incoming message.
+ *
+ * Pass the message to the client.
+ *
+ * @param cls Closure - communicator handle
+ * @param msg Message
+ */
+static void
+handle_incoming_msg (void *cls,
+                    const struct GNUNET_TRANSPORT_IncomingMessage *msg)
+{
+  struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h = cls;
+
+  if (NULL != tc_h->incoming_msg_cb) {
+    tc_h->incoming_msg_cb (tc_h->cb_cls,
+                           tc_h,
+                           (const struct GNUNET_MessageHeader *) msg);
+  }
+  else
+  {
+    LOG (GNUNET_ERROR_TYPE_WARNING,
+        "Incoming message from communicator but no handler!\n");
+  }
+  GNUNET_SERVICE_client_continue (tc_h->client);
+}
+
+
+/**
+ * @brief Communicator informs that it tries to establish requested queue
+ *
+ * @param cls Closure - communicator handle
+ * @param msg Message
+ */
 static void
 handle_queue_create_ok (void *cls,
                         const struct GNUNET_TRANSPORT_CreateQueueResponse *msg)
@@ -311,6 +396,15 @@ handle_queue_create_ok (void *cls,
 }
 
 
+/**
+ * @brief Communicator informs that it wont try establishing requested queue.
+ *
+ * It will not do so probably because the address is bougus (see comment to
+ * #GNUNET_MESSAGE_TYPE_TRANSPORT_QUEUE_CREATE_FAIL)
+ *
+ * @param cls Closure - communicator handle
+ * @param msg Message
+ */
 static void
 handle_queue_create_fail (
   void *cls,
@@ -342,9 +436,11 @@ check_add_queue_message (void *cls,
 
 
 /**
- * @brief Handle new communicator
+ * @brief Handle new queue
  *
- * @param cls Closure
+ * Store context and call client callback.
+ *
+ * @param cls Closure - communicator handle
  * @param msg Message struct
  */
 static void
@@ -409,10 +505,13 @@ connect_cb (void *cls,
 
   if (NULL == tc_h->queue_head)
     return tc_h;
+  /* Iterate over queues. They are yet to be opened. Request opening. */
   while (NULL != (tc_queue_iter = tc_h->queue_head))
   {
     if (NULL == tc_queue_iter->open_queue_env)
       continue;
+    /* Send the previously created mq envelope to request the creation of the
+     * queue. */
     GNUNET_MQ_send (tc_h->c_mq, tc_queue_iter->open_queue_env);
     tc_queue_iter->open_queue_env = NULL;
   }
@@ -467,10 +566,10 @@ transport_communicator_start (
     //                         GNUNET_MESSAGE_TYPE_TRANSPORT_DEL_ADDRESS,
     //                         struct GNUNET_TRANSPORT_DelAddressMessage,
     //                         NULL),
-    //GNUNET_MQ_hd_var_size (incoming_msg,
-    //    GNUNET_MESSAGE_TYPE_TRANSPORT_INCOMING_MSG,
-    //    struct GNUNET_TRANSPORT_IncomingMessage,
-    //    NULL),
+    GNUNET_MQ_hd_var_size (incoming_msg,
+        GNUNET_MESSAGE_TYPE_TRANSPORT_INCOMING_MSG,
+        struct GNUNET_TRANSPORT_IncomingMessage,
+        NULL),
     GNUNET_MQ_hd_fixed_size (queue_create_ok,
                              GNUNET_MESSAGE_TYPE_TRANSPORT_QUEUE_CREATE_OK,
                              struct GNUNET_TRANSPORT_CreateQueueResponse,
@@ -592,6 +691,7 @@ GNUNET_TRANSPORT_TESTING_transport_communicator_service_start (
    GNUNET_TRANSPORT_TESTING_AddAddressCallback add_address_cb,
    GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback queue_create_reply_cb,
    GNUNET_TRANSPORT_TESTING_AddQueueCallback add_queue_cb,
+   GNUNET_TRANSPORT_TESTING_IncomingMessageCallback incoming_message_cb,
    void *cb_cls)
 {
   struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h;
@@ -614,6 +714,7 @@ GNUNET_TRANSPORT_TESTING_transport_communicator_service_start (
   tc_h->add_address_cb = add_address_cb;
   tc_h->queue_create_reply_cb = queue_create_reply_cb;
   tc_h->add_queue_cb = add_queue_cb;
+  tc_h->incoming_msg_cb = incoming_message_cb;
   tc_h->cb_cls = cb_cls;
 
   /* Start communicator part of service */
@@ -626,6 +727,13 @@ GNUNET_TRANSPORT_TESTING_transport_communicator_service_start (
 }
 
 
+/**
+ * @brief Instruct communicator to open a queue
+ *
+ * @param tc_h Handle to communicator which shall open queue
+ * @param peer_id Towards which peer
+ * @param address For which address
+ */
 void
 GNUNET_TRANSPORT_TESTING_transport_communicator_open_queue (
   struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
@@ -670,6 +778,15 @@ GNUNET_TRANSPORT_TESTING_transport_communicator_open_queue (
 }
 
 
+/**
+ * @brief Instruct communicator to send data
+ *
+ * @param tc_queue The queue to use for sending
+ * @param payload Data to send
+ * @param payload_size Size of the payload
+ *
+ * @return Handle to the transmission
+ */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission *
 GNUNET_TRANSPORT_TESTING_transport_communicator_send
   (struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *tc_queue,

src/transport/transport-testing2.h

@@ -20,7 +20,7 @@
 
 /**
  * @file transport/transport-testing2.h
- * @brief functions related to testing-tng
+ * @brief functions and structures related to testing-tng
  * @author Christian Grothoff
  * @author Julius Bünger
  */
@@ -30,17 +30,32 @@
 #include "transport.h"
 
 
+/**
+ * @brief Handle to a transport communicator
+ */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle;
 
+
+/**
+ * @brief Queue of a communicator and some context
+ */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue;
 
+
+/**
+ * @brief Handle/Context to a single transmission
+ */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission;
 
+
 /**
- * @brief Function signature for callbacks that are called when new communicators become available
+ * @brief Function signature for callbacks that are called when new
+ * communicators become available
  *
- * @param Closure
- * @param msg Message
+ * @param cls Closure
+ * @param tc_h Communicator handle
+ * @param cc Characteristics of communicator
+ * @param address_prefix Prefix of the address
  */
 typedef void
 (*GNUNET_TRANSPORT_TESTING_CommunicatorAvailableCallback)(void *cls,
@@ -49,6 +64,16 @@ typedef void
       char *address_prefix);
 
 
+/**
+ * @brief Receive information about the address of a communicator.
+ *
+ * @param cls Closure
+ * @param tc_h Communicator handle
+ * @param address Address represented as string
+ * @param expiration Expiration
+ * @param aid Aid
+ * @param nt Network Type
+ */
 typedef void
 (*GNUNET_TRANSPORT_TESTING_AddAddressCallback)(void *cls,
       struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
@@ -58,18 +83,45 @@ typedef void
       enum GNUNET_NetworkType nt);
 
 
+/**
+ * @brief Get informed about the success of a queue request.
+ *
+ * @param cls Closure
+ * @param tc_h Communicator handle
+ * @param will_try #GNUNET_YES if communicator will try to create queue
+ */
 typedef void
 (*GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback)(void *cls,
     struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
     int will_try);
 
 
+/**
+ * @brief Handle opening of queue
+ *
+ * @param cls Closure
+ * @param tc_h Communicator handle
+ * @param tc_queue Handle to newly opened queue
+ */
 typedef void
 (*GNUNET_TRANSPORT_TESTING_AddQueueCallback)(void *cls,
     struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
     struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *tc_queue);
 
 
+/**
+ * @brief Handle an incoming message
+ *
+ * @param cls Closure
+ * @param tc_h Handle to the receiving communicator
+ * @param msg Received message
+ */
+typedef void
+(*GNUNET_TRANSPORT_TESTING_IncomingMessageCallback)(void *cls,
+    struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
+    const struct GNUNET_MessageHeader *msg);
+
+
 /**
  * @brief Start communicator part of transport service and communicator
  *
@@ -77,27 +129,50 @@ typedef void
  * @param cfg Configuration handle
  * @param communicator_available Callback that is called when a new
  * communicator becomes available
+ * @param add_address_cb Callback handling new addresses
+ * @param queue_create_reply_cb Callback handling success of queue requests
+ * @param add_queue_cb Callback handling freshly created queues
+ * @param incoming_message_cb Callback handling incoming messages
  * @param cb_cls Closure to @p communicator_available
  *
  * @return Handle to the communicator duo
  */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *
-GNUNET_TRANSPORT_TESTING_transport_communicator_service_start
-  (const char *service_name,
+GNUNET_TRANSPORT_TESTING_transport_communicator_service_start (
+   const char *service_name,
    const char *binary_name,
    const char *cfg_filename,
    GNUNET_TRANSPORT_TESTING_CommunicatorAvailableCallback communicator_available_cb,
    GNUNET_TRANSPORT_TESTING_AddAddressCallback add_address_cb,
    GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback queue_create_reply_cb,
    GNUNET_TRANSPORT_TESTING_AddQueueCallback add_queue_cb,
+   GNUNET_TRANSPORT_TESTING_IncomingMessageCallback incoming_message_cb,
    void *cb_cls);
 
+
+/**
+ * @brief Instruct communicator to open a queue
+ *
+ * @param tc_h Handle to communicator which shall open queue
+ * @param peer_id Towards which peer
+ * @param address For which address
+ */
 void
 GNUNET_TRANSPORT_TESTING_transport_communicator_open_queue
   (struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
    const struct GNUNET_PeerIdentity *peer_id,
    const char *address);
 
+
+/**
+ * @brief Instruct communicator to send data
+ *
+ * @param tc_queue The queue to use for sending
+ * @param payload Data to send
+ * @param payload_size Size of the payload
+ *
+ * @return Handle to the transmission
+ */
 struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission *
 GNUNET_TRANSPORT_TESTING_transport_communicator_send
   (struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *tc_queue,