commit 49fb1901d18e1e42c41b7cd8817e5778ed473470
parent d309f70641efc038d4b23558030b0551c3101256
Author: Gabor X Toth <*@tg-x.net>
Date: Thu, 13 Mar 2014 18:49:13 +0000
PSYC: message types, documentation
Diffstat:
5 files changed, 255 insertions(+), 103 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
+ */
};
