Adaped to new API, documented

1 files changed, 108 insertions, 61 deletions

diff --git a/src/mesh/mesh.h b/src/mesh/mesh.h
index a29c63f88..32d9c4ee5 100644
--- a/src/mesh/mesh.h
+++ b/src/mesh/mesh.h
@@ -27,34 +27,60 @@
 #define MESH_H_
 #include <stdint.h>
 
-#include <gnunet_mesh_service.h>
+#include <gnunet_mesh_service_new.h>
 #include "gnunet_common.h"
 
 /******************************************************************************/
-/********************      MESH NETWORK MESSAGES     **************************/
+/********************        MESH LOCAL MESSAGES      *************************/
 /******************************************************************************/
-/* API CALL                         MESSAGE USED
- * --------                         ------------
- * connect                          GNUNET_MESH_Connect
- * disconnect                       None (network level disconnect)
+/*  Any API call should be documented in the folowing table under API CALL.
+ *  Also, any message type should be documented in the following table, with the
+ * associated event.
+ * 
+ * API CALL (GNUNET_MESH_*)             MESSAGE USED
+ * ------------------------             ------------
+ * connect                              GNUNET_MESH_Connect
+ * disconnect                           None (network level disconnect)
  *
- * tunnel_create                    GNUNET_MESH_TunnelMessage
- * tunnel_destroy                   GNUNET_MESH_TunnelMessage
+ * tunnel_create                        GNUNET_MESH_TunnelMessage
+ * tunnel_destroy                       GNUNET_MESH_TunnelMessage
  *
- * peer_request_connect_add         GNUNET_MESH_ConnectPeer
- * peer_request_connect_del         GNUNET_MESH_ConnectPeer
- * peer_request_connect_by_type     GNUNET_MESH_ConnectPeerByType
+ * peer_request_connect_add             GNUNET_MESH_PeerControl
+ * peer_request_connect_del             GNUNET_MESH_PeerControl
+ * peer_request_connect_by_type         GNUNET_MESH_ConnectPeerByType
  *
- * notify_transmit_ready            GNUNET_MESH_Control
- * notify_transmit_ready_cancel     None
+ * notify_transmit_ready                GNUNET_MESH_RequestTransmitReady
+ * notify_transmit_ready_cancel         None (clear of internal data structures)
+ * 
+ * 
+ * 
+ * EVENT                                MESSAGE USED
+ * -----                                ------------
+ * notify_transmit_ready reply          GNUNET_MESH_NotifyTransmitReady
+ * notify_transmit_ready data           GNUNET_MESH_Data or
+ *                                      GNUNET_MESH_DataBroadcast
+ * new incoming tunnel                  GNUNET_MESH_PeerControl
+ * peer connects to a tunnel            GNUNET_MESH_PeerControl
+ * peer disconnects from a tunnel       GNUNET_MESH_PeerControl
  */
 
+/**
+ * Type for tunnel numbering.
+ * - Local tunnel numbers are >= 0x80000000
+ * - Global tunnel numbers are < 0x80000000
+ */
+typedef uint32_t MESH_TunnelID;
 
+
+/**
+ * Message for connecting to the msh service. Specifies the messages the client
+ * is interested in.
+ */
 struct GNUNET_MESH_Connect {
     /**
      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_CONNECT
-     *
-     * Size: sizeof(struct GNUNET_MESH_Connect) + messages_subscribed * sizeof (message_type)
+     * Size: sizeof(struct GNUNET_MESH_Connect) +
+     *       messages_subscribed * sizeof (message_type)
      */
     struct GNUNET_MessageHeader header;
 
@@ -63,7 +89,7 @@ struct GNUNET_MESH_Connect {
 
 
 /**
- *
+ * Message for a client to create and destroy tunnels.
  */
 struct GNUNET_MESH_TunnelMessage {
     /**
@@ -71,37 +97,47 @@ struct GNUNET_MESH_TunnelMessage {
      */
     struct GNUNET_MessageHeader header;
 
-  /**
-   * ID of a tunnel controlled by this client.
-   */
-    uint32_t tunnel_id GNUNET_PACKED;
+    /**
+     * ID of a tunnel controlled by this client.
+     */
+    MESH_TunnelID               tunnel_id GNUNET_PACKED;
 };
 
-
+/**
+ * Message for:
+ * - request adding and deleting peers from a tunnel
+ * - notify the client that peers have connected:
+ *   -- requested
+ *   -- unrequested (new incoming tunnels)
+ * - notify the client that peers have disconnected
+ */
 struct GNUNET_MESH_PeerControl {
 
   /**
-   * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_CONNECT_PEER_[ADD|DEL] (client to service, client created tunnel)
-   * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_TUNNEL_NOTIFY[CONNECT|DISCONNECT] (service to client)
+   * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_CONNECT_PEER_[ADD|DEL]
+   *       (client to service, client created tunnel)
+   *       GNUNET_MESSAGE_TYPE_MESH_LOCAL_TUNNEL_NOTIFY[CONNECT|DISCONNECT]
+   *       (service to client)
    * 
    * Size: sizeof(struct GNUNET_MESH_PeerControl) 
    */
-  struct GNUNET_MessageHeader header;
+  struct GNUNET_MessageHeader   header;
 
   /**
    * ID of a tunnel controlled by this client.
    */
-    uint32_t tunnel_id GNUNET_PACKED;
+   MESH_TunnelID                tunnel_id GNUNET_PACKED;
   
   /**
    * Peer to connect/disconnect.
    */
-  struct GNUNET_PeerIdentity peer;
+  struct GNUNET_PeerIdentity    peer;
 };
 
 
-
-
+/**
+ * Message for connecting to peers offering a certain service.
+ */
 struct GNUNET_MESH_ConnectPeerByType {
     /**
      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_CONNECT_PEER_BY_TYPE
@@ -111,84 +147,95 @@ struct GNUNET_MESH_ConnectPeerByType {
   /**
    * ID of a tunnel controlled by this client.
    */
-    uint32_t tunnel_id GNUNET_PACKED;
+   MESH_TunnelID                tunnel_id GNUNET_PACKED;
  
   /**
    * Type specification 
    */
-    GNUNET_MESH_ApplicationType type;
+    GNUNET_MESH_ApplicationType type GNUNET_PACKED;
 };
 
 
+/**
+ * Message for notifying the service that the client wants to send data.
+ */
 struct GNUNET_MESH_RequestTransmitReady {
     /**
      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_REQUEST_TRANSMIT_READY
      */
     struct GNUNET_MessageHeader header;
 
-  /**
-   * ID of a tunnel controlled by this client.
-   */
-    uint32_t tunnel_id GNUNET_PACKED;
+    /**
+     * ID of a tunnel controlled by this client.
+     */
+    MESH_TunnelID               tunnel_id GNUNET_PACKED;
 
-  /**
-   * Size of message we would like to transmit to this tunnel
-   */
-    uint32_t msg_size GNUNET_PACKED; 
+    /**
+     * Size of message we would like to transmit to this tunnel
+     */
+    uint32_t                    msg_size GNUNET_PACKED; 
 };
 
+
+/**
+ * Message for letting a client know that the service is ready to accept data
+ * for transmission.
+ */
 struct GNUNET_MESH_NotifyTransmitReady {
     /**
      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_NOTIFY_TRANSMIT_READY
      */
     struct GNUNET_MessageHeader header;
 
-  /**
-   * ID of a tunnel controlled by this client.
-   */
-    uint32_t tunnel_id GNUNET_PACKED;
+    /**
+     * ID of a tunnel controlled by this client.
+     */
+    MESH_TunnelID               tunnel_id GNUNET_PACKED;
 
-  /**
-   * Size of message we can now transmit to this tunnel
-   */
-    uint32_t msg_size GNUNET_PACKED; 
+    /**
+     * Size of message we can now transmit to this tunnel
+     */
+    uint32_t                    msg_size GNUNET_PACKED; 
 };
 
 
+/**
+ * Message to encapsulate data transmitted to/from the service
+ */
 struct GNUNET_MESH_Data {
     /**
      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_DATA (client to service, or service to client)
-     *
      * Size: sizeof(struct GNUNET_MESH_Data) + sizeof (data)
      */
     struct GNUNET_MessageHeader header;
 
-  /**
-   * ID of a tunnel controlled by this client.
-   */
-    uint32_t tunnel_id GNUNET_PACKED;
+    /**
+     * ID of a tunnel controlled by this client.
+     */
+    MESH_TunnelID               tunnel_id GNUNET_PACKED;
 
-  /**
-   * Source or destination of the message (depending on direction).
-   */
-    struct GNUNET_PeerIdentity destination;
+    /**
+     * Source or destination of the message (depending on direction).
+     */
+    struct GNUNET_PeerIdentity  peer_id;
 
     /* uint8_t data[] */
 };
 
-
+/**
+ * Message to encapsulate broadcast data transmitted to the service
+ */
 struct GNUNET_MESH_DataBroadcast {
     /**
      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_DATA_BROADCAST (client to service only, client created tunnel)
-     *
      * Size: sizeof(struct GNUNET_MESH_DataBroadcast) + sizeof (data)
      */
     struct GNUNET_MessageHeader header;
 
-  /**
-   * ID of a tunnel controlled by this client.
-   */
-    uint32_t tunnel_id GNUNET_PACKED;
+    /**
+     * ID of a tunnel controlled by this client.
+     */
+    MESH_TunnelID               tunnel_id GNUNET_PACKED;
 
     /* uint8_t data[] */
 };