PSYC: message types, documentation

5 files changed, 255 insertions, 103 deletions

diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h
index aa5597fd3..50dcf7aef 100644
--- a/src/include/gnunet_multicast_service.h
+++ b/src/include/gnunet_multicast_service.h
@@ -189,7 +189,8 @@ struct GNUNET_MULTICAST_RequestHeader
   struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
 
   /**
-   * Number of the request fragment, monotonically increasing.
+   * Number of the request fragment.
+   * Monotonically increasing from 1.
    */
   uint64_t fragment_id GNUNET_PACKED;
 
diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h
index 88cf5a024..b67e3bdcb 100644
--- a/src/include/gnunet_protocols.h
+++ b/src/include/gnunet_protocols.h
@@ -2126,64 +2126,84 @@ extern "C"
  * PSYC message types
  ******************************************************************************/
 
-#define GNUNET_MESSAGE_TYPE_PSYC_RESULT_CODE 680
+/**
+ * C: client
+ * S: service
+ * M: muticast
+ */
 
+/** S->C: result of an operation */
+#define GNUNET_MESSAGE_TYPE_PSYC_RESULT_CODE 680
 
+/** C->S: request to start a master */
 #define GNUNET_MESSAGE_TYPE_PSYC_MASTER_START 681
 
+/** S->C: master start acknowledgement */
 #define GNUNET_MESSAGE_TYPE_PSYC_MASTER_START_ACK 682
 
-#define GNUNET_MESSAGE_TYPE_PSYC_MASTER_STOP 683
-
+/** C->S: request to start a master */
+#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN 683
 
-#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN 684
-
-#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN_ACK 685
-
-#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_PART 686
+/** S->C: slave join acknowledgement */
+#define GNUNET_MESSAGE_TYPE_PSYC_SLAVE_JOIN_ACK 684
 
+/* 685-686 */
 
+/** M->S->C: incoming join request from multicast */
 #define GNUNET_MESSAGE_TYPE_PSYC_JOIN_REQUEST 687
 
+/** C->S->M: decision about a join request */
 #define GNUNET_MESSAGE_TYPE_PSYC_JOIN_DECISION 688
 
 
+/** C->S: request to remove channel slave from the membership database. */
 #define GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_SLAVE_ADD 689
 
+/** C->S: request to add channel slave to the membership database */
 #define GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_SLAVE_RM 690
 
 
+/** M<->S<->C: PSYC message which contains one or more message parts. */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE 691
 
+/** Message part: method */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_METHOD 692
 
+/** Message part: modifier */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER 693
 
+/** Message part: modifier continuation */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MOD_CONT 694
 
+/** Message part: data */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_DATA 695
 
+/** Message part: end of message */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_END 696
 
+/** Message part: message cancelled */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_CANCEL 697
 
+/** S->C: message acknowledgment */
 #define GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_ACK 698
 
+/* 699-700 */
 
+/** C->S: client requests channel history from PSYCstore. */
 #define GNUNET_MESSAGE_TYPE_PSYC_STORY_REQUEST 701
 
-#define GNUNET_MESSAGE_TYPE_PSYC_STORY_RESPONSE 702
+/** S->C: result for a channel history request */
+#define GNUNET_MESSAGE_TYPE_PSYC_STORY_RESULT 702
 
 
+/** C->S: request best matching state variable from PSYCstore. */
 #define GNUNET_MESSAGE_TYPE_PSYC_STATE_GET 703
 
+/** C->S: request state variables with a given prefix from PSYCstore. */
 #define GNUNET_MESSAGE_TYPE_PSYC_STATE_GET_PREFIX 704
 
-#define GNUNET_MESSAGE_TYPE_PSYC_STATE_RESPONSE 705
-
-#define GNUNET_MESSAGE_TYPE_PSYC_STATE_MODIFIER 706
-
-#define GNUNET_MESSAGE_TYPE_PSYC_STATE_MOD_CONT 707
+/** S->C: result for a state request. */
+#define GNUNET_MESSAGE_TYPE_PSYC_STATE_RESULT 705
 
 
 /*******************************************************************************
@@ -2196,7 +2216,7 @@ extern "C"
 #define GNUNET_MESSAGE_TYPE_CONVERSATION_AUDIO 730
 
 /**
- * Client -> Server message register a phone.
+ * Client -> Server message to register a phone.
  */
 #define GNUNET_MESSAGE_TYPE_CONVERSATION_CS_PHONE_REGISTER 731
 
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h
index 3a0c713d5..018f012f4 100644
--- a/src/include/gnunet_psyc_service.h
+++ b/src/include/gnunet_psyc_service.h
@@ -113,6 +113,7 @@ enum GNUNET_PSYC_ChannelFlags
   GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY = 1 << 1
 };
 
+
 /**
  * PSYC channel policies.
  */
@@ -169,6 +170,7 @@ enum GNUNET_PSYC_MessageFlags
   GNUNET_PSYC_MESSAGE_REQUEST = 1 << 1
 };
 
+
 GNUNET_NETWORK_STRUCT_BEGIN
 
 /**
@@ -190,6 +192,7 @@ struct GNUNET_PSYC_MessageHeader
 
   /**
    * Number of the message this message part belongs to.
+   * Monotonically increasing from 1.
    */
   uint64_t message_id GNUNET_PACKED;
 
@@ -254,6 +257,7 @@ struct GNUNET_PSYC_MessageModifier
 
 GNUNET_NETWORK_STRUCT_END
 
+
 #define GNUNET_PSYC_MODIFIER_MAX_PAYLOAD        \
   GNUNET_MULTICAST_FRAGMENT_MAX_PAYLOAD         \
   - sizeof (struct GNUNET_PSYC_MessageModifier)
@@ -266,6 +270,7 @@ GNUNET_NETWORK_STRUCT_END
   GNUNET_MULTICAST_FRAGMENT_MAX_PAYLOAD         \
   - sizeof (struct GNUNET_MessageHeader)
 
+
 /**
  * Handle that identifies a join request.
  *
@@ -362,7 +367,7 @@ struct GNUNET_PSYC_Master;
  * Function called after the channel master started.
  *
  * @param cls Closure.
- * @param last_message_id Last message ID sent to the channel.
+ * @param max_message_id Last message ID sent to the channel.
  */
 typedef void
 (*GNUNET_PSYC_MasterStartCallback) (void *cls, uint64_t max_message_id);
diff --git a/src/psyc/gnunet-service-psyc.c b/src/psyc/gnunet-service-psyc.c
index 4cdb490a1..1b1f4b1db 100644
--- a/src/psyc/gnunet-service-psyc.c
+++ b/src/psyc/gnunet-service-psyc.c
@@ -63,6 +63,7 @@ static struct GNUNET_PSYCSTORE_Handle *store;
  */
 static struct GNUNET_CONTAINER_MultiHashMap *clients;
 
+
 /**
  * Message in the transmission queue.
  */
@@ -71,10 +72,18 @@ struct TransmitMessage
   struct TransmitMessage *prev;
   struct TransmitMessage *next;
 
+  /**
+   * Buffer with message to be transmitted.
+   */
   char *buf;
-  uint16_t size;
+
   /**
-   * enum MessageState
+   * Size of @a buf
+   */
+  uint16_t size
+;
+  /**
+   * @see enum MessageState
    */
   uint8_t state;
 };
@@ -147,34 +156,57 @@ struct Channel
   uint32_t tmit_mod_value_size;
 
   /**
-   * enum MessageState
+   * @see enum MessageState
    */
   uint8_t tmit_state;
 
   uint8_t in_transmit;
+
+  /**
+   * Is this a channel master (#GNUNET_YES), or slave (#GNUNET_NO)?
+   */
   uint8_t is_master;
 
   /**
-   * Ready to receive messages from client.
+   * Ready to receive messages from client? #GNUNET_YES or #GNUNET_NO
    */
   uint8_t ready;
 
   /**
-   * Client disconnected.
+   * Is the client disconnected? #GNUNET_YES or #GNUNET_NO
    */
   uint8_t disconnected;
 };
 
+
 /**
  * Client context for a channel master.
  */
 struct Master
 {
+  /**
+   * Channel struct common for Master and Slave
+   */
   struct Channel channel;
+
+  /**
+   * Private key of the channel.
+   */
   struct GNUNET_CRYPTO_EddsaPrivateKey priv_key;
+
+  /**
+   * Public key of the channel.
+   */
   struct GNUNET_CRYPTO_EddsaPublicKey pub_key;
 
+  /**
+   * Handle for the multicast origin.
+   */
   struct GNUNET_MULTICAST_Origin *origin;
+
+  /**
+   * Transmit handle for multicast.
+   */
   struct GNUNET_MULTICAST_OriginMessageHandle *tmit_handle;
 
   /**
@@ -201,6 +233,9 @@ struct Master
    */
   uint32_t policy;
 
+  /**
+   * Hash of @a pub_key
+   */
   struct GNUNET_HashCode pub_key_hash;
 };
 
@@ -210,23 +245,64 @@ struct Master
  */
 struct Slave
 {
+  /**
+   * Channel struct common for Master and Slave
+   */
   struct Channel channel;
+
+  /**
+   * Private key of the slave.
+   */
   struct GNUNET_CRYPTO_EddsaPrivateKey slave_key;
+
+  /**
+   * Public key of the channel.
+   */
   struct GNUNET_CRYPTO_EddsaPublicKey chan_key;
 
+  /**
+   * Handle for the multicast member.
+   */
   struct GNUNET_MULTICAST_Member *member;
+
+  /**
+   * Transmit handle for multicast.
+   */
   struct GNUNET_MULTICAST_MemberRequestHandle *tmit_handle;
 
+  /**
+   * Peer identity of the origin.
+   */
   struct GNUNET_PeerIdentity origin;
 
+  /**
+   * Number of items in @a relays.
+   */
   uint32_t relay_count;
+
+  /**
+   * Relays that multicast can use to connect.
+   */
   struct GNUNET_PeerIdentity *relays;
 
+  /**
+   * Join request to be transmitted to the master on join.
+   */
   struct GNUNET_MessageHeader *join_req;
 
+  /**
+   * Maximum message ID for this channel.
+   */
   uint64_t max_message_id;
+
+  /**
+   * Maximum request ID for this channel.
+   */
   uint64_t max_request_id;
 
+  /**
+   * Hash of @a chan_key.
+   */
   struct GNUNET_HashCode chan_key_hash;
 };
 
@@ -323,8 +399,11 @@ client_disconnect (void *cls, struct GNUNET_SERVER_Client *client)
 }
 
 
+/**
+ * Master receives a join request from a slave.
+ */
 static void
-join_cb (void *cls, const struct GNUNET_CRYPTO_EddsaPublicKey *member_key,
+join_cb (void *cls, const struct GNUNET_CRYPTO_EddsaPublicKey *slave_key,
          const struct GNUNET_MessageHeader *join_req,
          struct GNUNET_MULTICAST_JoinHandle *jh)
 {
@@ -334,7 +413,7 @@ join_cb (void *cls, const struct GNUNET_CRYPTO_EddsaPublicKey *member_key,
 
 static void
 membership_test_cb (void *cls,
-                    const struct GNUNET_CRYPTO_EddsaPublicKey *member_key,
+                    const struct GNUNET_CRYPTO_EddsaPublicKey *slave_key,
                     uint64_t message_id, uint64_t group_generation,
                     struct GNUNET_MULTICAST_MembershipTestHandle *mth)
 {
@@ -344,7 +423,7 @@ membership_test_cb (void *cls,
 
 static void
 replay_fragment_cb (void *cls,
-                    const struct GNUNET_CRYPTO_EddsaPublicKey *member_key,
+                    const struct GNUNET_CRYPTO_EddsaPublicKey *slave_key,
                     uint64_t fragment_id, uint64_t flags,
                     struct GNUNET_MULTICAST_ReplayHandle *rh)
 
@@ -354,7 +433,7 @@ replay_fragment_cb (void *cls,
 
 static void
 replay_message_cb (void *cls,
-                   const struct GNUNET_CRYPTO_EddsaPublicKey *member_key,
+                   const struct GNUNET_CRYPTO_EddsaPublicKey *slave_key,
                    uint64_t message_id,
                    uint64_t fragment_offset,
                    uint64_t flags,
@@ -702,12 +781,12 @@ slave_message_cb (void *cls, const struct GNUNET_MessageHeader *msg)
  * Incoming request fragment from multicast for a master.
  *
  * @param cls           Master.
- * @param member_key    Sending member's public key.
+ * @param slave_key     Sending slave's public key.
  * @param msg           The message.
  * @param flags         Request flags.
  */
 static void
-request_cb (void *cls, const struct GNUNET_CRYPTO_EddsaPublicKey *member_key,
+request_cb (void *cls, const struct GNUNET_CRYPTO_EddsaPublicKey *slave_key,
             const struct GNUNET_MessageHeader *msg,
             enum GNUNET_MULTICAST_MessageFlags flags)
 {
@@ -1159,6 +1238,61 @@ handle_psyc_message (void *cls, struct GNUNET_SERVER_Client *client,
 
 
 /**
+ * Client requests to add a slave to the membership database.
+ */
+static void
+handle_slave_add (void *cls, struct GNUNET_SERVER_Client *client,
+                  const struct GNUNET_MessageHeader *msg)
+{
+
+}
+
+
+/**
+ * Client requests to remove a slave from the membership database.
+ */
+static void
+handle_slave_remove (void *cls, struct GNUNET_SERVER_Client *client,
+                     const struct GNUNET_MessageHeader *msg)
+{
+
+}
+
+
+/**
+ * Client requests channel history from PSYCstore.
+ */
+static void
+handle_story_request (void *cls, struct GNUNET_SERVER_Client *client,
+                      const struct GNUNET_MessageHeader *msg)
+{
+
+}
+
+
+/**
+ * Client requests best matching state variable from PSYCstore.
+ */
+static void
+handle_state_get (void *cls, struct GNUNET_SERVER_Client *client,
+                  const struct GNUNET_MessageHeader *msg)
+{
+
+}
+
+
+/**
+ * Client requests state variables with a given prefix from PSYCstore.
+ */
+static void
+handle_state_get_prefix (void *cls, struct GNUNET_SERVER_Client *client,
+                         const struct GNUNET_MessageHeader *msg)
+{
+
+}
+
+
+/**
  * Initialize the PSYC service.
  *
  * @param cls Closure.
@@ -1178,6 +1312,21 @@ run (void *cls, struct GNUNET_SERVER_Handle *server,
 
     { &handle_psyc_message, NULL,
       GNUNET_MESSAGE_TYPE_PSYC_MESSAGE, 0 },
+
+    { &handle_slave_add, NULL,
+      GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_SLAVE_ADD, 0 },
+
+    { &handle_slave_remove, NULL,
+      GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_SLAVE_RM, 0 },
+
+    { &handle_story_request, NULL,
+      GNUNET_MESSAGE_TYPE_PSYC_STORY_REQUEST, 0 },
+
+    { &handle_state_get, NULL,
+      GNUNET_MESSAGE_TYPE_PSYC_STATE_GET, 0 },
+
+    { &handle_state_get_prefix, NULL,
+      GNUNET_MESSAGE_TYPE_PSYC_STATE_GET_PREFIX, 0 }
   };
 
   cfg = c;
diff --git a/src/psyc/psyc.h b/src/psyc/psyc.h
index 940412a32..582a8e168 100644
--- a/src/psyc/psyc.h
+++ b/src/psyc/psyc.h
@@ -54,72 +54,6 @@ enum MessageState
 
 GNUNET_NETWORK_STRUCT_BEGIN
 
-/**** service -> library ****/
-
-/**
- * Answer from service to client about last operation.
- */
-struct OperationResult
-{
-  /**
-   * Type: GNUNET_MESSAGE_TYPE_PSYCSTORE_RESULT_CODE
-   */
-  struct GNUNET_MessageHeader header;
-
-  /**
-   * Operation ID.
-   */
-  uint32_t op_id GNUNET_PACKED;
-
-  /**
-   * Status code for the operation.
-   */
-  int64_t result_code GNUNET_PACKED;
-
-  /* followed by NUL-terminated error message (on error) */
-};
-
-
-struct CountersResult
-{
-  /**
-   * Type: GNUNET_MESSAGE_TYPE_PSYC_RESULT_COUNTERS
-   */
-  struct GNUNET_MessageHeader header;
-
-  /**
-   * Status code for the operation.
-   */
-  int32_t result_code GNUNET_PACKED;
-
-  uint64_t max_message_id;
-};
-
-
-#if REMOVE
-/**
- * Transmit acknowledgment.
- *
- * Sent after the last GNUNET_PSYC_MessageModifier and after each
- * GNUNET_PSYC_MessageData.
- *
- * This message acknowledges previously received messages and asks for the next
- * fragment of data.
- */
-struct TransmitAck
-{
-  /**
-   * Type: GNUNET_MESSAGE_TYPE_PSYC_TRANSMIT_ACK
-   */
-  struct GNUNET_MessageHeader header;
-
-  /**
-   * Buffer space available for the next data fragment.
-   */
-  uint16_t buf_avail;
-};
-#endif
-
 
 /**** library -> service ****/
 
@@ -203,37 +137,80 @@ struct StoryRequest
 };
 
 
-struct StateQuery
+struct StateRequest
 {
   /**
-   * Type: GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_QUERY
+   * Types:
+   * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_GET
+   * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_GET_PREFIX
    */
   struct GNUNET_MessageHeader header;
 
+  /**
+   * ID for this operation.
+   */
   uint64_t op_id;
 
   /* Followed by NUL-terminated name. */
 };
 
 
-struct StateResult
+/**** service -> library ****/
+
+
+struct CountersResult
+{
+  /**
+   * Type: GNUNET_MESSAGE_TYPE_PSYC_RESULT_COUNTERS
+   */
+  struct GNUNET_MessageHeader header;
+
+  /**
+   * Status code for the operation.
+   */
+  int32_t result_code GNUNET_PACKED;
+
+  /**
+   * Last message ID sent to the channel.
+   */
+  uint64_t max_message_id;
+};
+
+/**
+ * Answer from service to client about last operation.
+ */
+struct OperationResult
 {
   /**
-   * Type: GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_RESULT
+   * Types:
+   * - GNUNET_MESSAGE_TYPE_PSYC_RESULT_CODE
+   * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STORY_RESULT
+   * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_RESULT
    */
   struct GNUNET_MessageHeader header;
 
   /**
-   * Size of name, including NUL terminator.
+   * Operation ID.
    */
-  uint16_t name_size GNUNET_PACKED;
+  uint32_t op_id GNUNET_PACKED;
 
   /**
-   * OR'd StateOpFlags
+   * Status code for the operation.
    */
-  uint8_t flags;
+  int64_t result_code GNUNET_PACKED;
 
-  /* Followed by NUL-terminated name, then the value. */
+  /* Followed by:
+   * - on error: NUL-terminated error message
+   * - on success: one of the following message types
+   *
+   *   For a STORY_RESULT:
+   *   - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE
+   *
+   *   For a STATE_RESULT, one of:
+   *   - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER
+   *   - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MOD_CONT
+   *   - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_END
+   */
 };