Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
-
/**
- * @author Florian Dold
* @file set/set.h
* @brief messages used for the set api
+ * @author Florian Dold
+ * @author Christian Grothoff
*/
#ifndef SET_H
#define SET_H
#include "platform.h"
#include "gnunet_common.h"
-#define GNUNET_SET_ACK_WINDOW 10
-
-
GNUNET_NETWORK_STRUCT_BEGIN
+/**
+ * Message sent by the client to the service to ask starting
+ * a new set to perform operations with. Includes the desired
+ * set operation type.
+ */
struct GNUNET_SET_CreateMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_CREATE
+ * Type: #GNUNET_MESSAGE_TYPE_SET_CREATE
*/
struct GNUNET_MessageHeader header;
/**
- * Operation type, values of enum GNUNET_SET_OperationType
+ * Operation type, values of `enum GNUNET_SET_OperationType`
*/
- // FIXME: use 32_t for 'enum'.
- uint16_t operation GNUNET_PACKED;
+ uint32_t operation GNUNET_PACKED;
};
+/**
+ * Message sent by the client to the service to start listening for
+ * incoming requests to perform a certain type of set operation for a
+ * certain type of application.
+ */
struct GNUNET_SET_ListenMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_LISTEN
+ * Type: #GNUNET_MESSAGE_TYPE_SET_LISTEN
*/
struct GNUNET_MessageHeader header;
/**
- * Operation type, values of enum GNUNET_SET_OperationType
+ * Operation type, values of `enum GNUNET_SET_OperationType`
*/
uint32_t operation GNUNET_PACKED;
};
-struct GNUNET_SET_AcceptRejectMessage
+/**
+ * Message sent by a listening client to the service to accept
+ * performing the operation with the other peer.
+ */
+struct GNUNET_SET_AcceptMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_ACCEPT or
- * GNUNET_MESSAGE_TYPE_SET_REJECT
+ * Type: #GNUNET_MESSAGE_TYPE_SET_ACCEPT
*/
struct GNUNET_MessageHeader header;
/**
- * ID of the incoming request we want to accept / reject.
+ * ID of the incoming request we want to accept.
*/
uint32_t accept_reject_id GNUNET_PACKED;
/**
- * Request ID to identify responses,
- * must be 0 if we don't accept the request.
+ * Request ID to identify responses.
*/
uint32_t request_id GNUNET_PACKED;
+
+ /**
+ * How should results be sent to us?
+ * See `enum GNUNET_SET_ResultMode`.
+ */
+ uint32_t result_mode GNUNET_PACKED;
};
/**
- * A request for an operation with another client.
+ * Message sent by a listening client to the service to reject
+ * performing the operation with the other peer.
*/
-struct GNUNET_SET_RequestMessage
+struct GNUNET_SET_RejectMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_Request.
+ * Type: #GNUNET_MESSAGE_TYPE_SET_REJECT
*/
struct GNUNET_MessageHeader header;
/**
- * Identity of the requesting peer.
+ * ID of the incoming request we want to reject.
*/
- struct GNUNET_PeerIdentity peer_id;
+ uint32_t accept_reject_id GNUNET_PACKED;
+
+};
+
+
+/**
+ * A request for an operation with another client.
+ */
+struct GNUNET_SET_RequestMessage
+{
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_SET_REQUEST.
+ */
+ struct GNUNET_MessageHeader header;
/**
* ID of the to identify the request when accepting or
*/
uint32_t accept_id GNUNET_PACKED;
- /* rest: nested context message */
+ /**
+ * Identity of the requesting peer.
+ */
+ struct GNUNET_PeerIdentity peer_id;
+
+ /* rest: context message, that is, application-specific
+ message to convince listener to pick up */
};
+/**
+ * Message sent by client to service to initiate a set operation as a
+ * client (not as listener). A set (which determines the operation
+ * type) must already exist in association with this client.
+ */
struct GNUNET_SET_EvaluateMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_EVALUATE
+ * Type: #GNUNET_MESSAGE_TYPE_SET_EVALUATE
*/
struct GNUNET_MessageHeader header;
/**
- * id of our evaluate, chosen by the client
+ * How should results be sent to us?
+ * See `enum GNUNET_SET_ResultMode`.
*/
- uint32_t request_id GNUNET_PACKED;
+ uint32_t result_mode GNUNET_PACKED;
/**
* Peer to evaluate the operation with
struct GNUNET_HashCode app_id;
/**
- * Salt to use for the operation
+ * Id of our set to evaluate, chosen implicitly by the client when it
+ * calls #GNUNE_SET_commit().
*/
- uint16_t salt GNUNET_PACKED;
-
- /**
- * Padding
- */
- uint16_t reserved GNUNET_PACKED;
+ uint32_t request_id GNUNET_PACKED;
- /* rest: inner message */
+ /* rest: context message, that is, application-specific
+ message to convince listener to pick up */
};
struct GNUNET_SET_ResultMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_RESULT
+ * Type: #GNUNET_MESSAGE_TYPE_SET_RESULT
*/
struct GNUNET_MessageHeader header;
uint32_t request_id GNUNET_PACKED;
/**
- * Was the evaluation successful?
+ * Was the evaluation successful? Contains
+ * an `enum GNUNET_SET_Status` in NBO.
*/
uint16_t result_status GNUNET_PACKED;
};
+/**
+ * Message sent by client to the service to add or remove
+ * an element to/from the set.
+ */
struct GNUNET_SET_ElementMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_ADD or
- * GNUNET_MESSAGE_TYPE_SET_REMOVE
+ * Type: #GNUNET_MESSAGE_TYPE_SET_ADD or
+ * #GNUNET_MESSAGE_TYPE_SET_REMOVE
*/
struct GNUNET_MessageHeader header;
+ /**
+ * Type of the element to add or remove.
+ */
uint16_t element_type GNUNET_PACKED;
+ /**
+ * For alignment, always zero.
+ */
uint16_t reserved GNUNET_PACKED;
/* rest: the actual element */
struct GNUNET_SET_CancelMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_CANCEL
+ * Type: #GNUNET_MESSAGE_TYPE_SET_CANCEL
*/
struct GNUNET_MessageHeader header;
uint32_t request_id GNUNET_PACKED;
};
+
+/**
+ * Set element transmitted by service to client in response to a set
+ * iteration request.
+ */
struct GNUNET_SET_IterResponseMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_ITER_RESPONSE
+ * Type: #GNUNET_MESSAGE_TYPE_SET_ITER_RESPONSE
*/
struct GNUNET_MessageHeader header;
+ /**
+ * To which set iteration does this reponse belong to? First
+ * iteration (per client) has counter zero. Wraps around.
+ */
+ uint16_t iteration_id GNUNET_PACKED;
+
/**
* Type of the element attachted to the message,
* if any.
/* rest: element */
};
+
+/**
+ * Client acknowledges receiving element in iteration.
+ */
struct GNUNET_SET_IterAckMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_ITER_ACK
+ * Type: #GNUNET_MESSAGE_TYPE_SET_ITER_ACK
*/
struct GNUNET_MessageHeader header;