/*
This file is part of GNUnet.
- (C) 2012 Christian Grothoff (and other contributing authors)
+ (C) 2012, 2013 Christian Grothoff (and other contributing authors)
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
- by the Free Software Foundation; either version 2, or (at your
+ by the Free Software Foundation; either version 3, or (at your
option) any later version.
GNUnet is distributed in the hope that it will be useful, but
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"
+GNUNET_NETWORK_STRUCT_BEGIN
/**
- * The service sends up to GNUNET_SET_ACK_WINDOW messages per client handle,
- * the client should send an ack every GNUNET_SET_ACK_WINDOW/2 messages.
+ * Message sent by the client to the service to ask starting
+ * a new set to perform operations with. Includes the desired
+ * set operation type.
*/
-#define GNUNET_SET_ACK_WINDOW 8
-
-
-GNUNET_NETWORK_STRUCT_BEGIN
-
-struct SetCreateMessage
+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`
*/
- uint16_t operation GNUNET_PACKED;
+ uint32_t operation GNUNET_PACKED;
};
-struct ListenMessage
+/**
+ * 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;
/**
- * application id
+ * Operation type, values of `enum GNUNET_SET_OperationType`
*/
- struct GNUNET_HashCode app_id;
+ uint32_t operation GNUNET_PACKED;
/**
- * Operation type, values of enum GNUNET_SET_OperationType
+ * application id
*/
- uint16_t operation GNUNET_PACKED;
+ struct GNUNET_HashCode app_id;
+
};
-struct AcceptMessage
+/**
+ * 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
+ * Type: #GNUNET_MESSAGE_TYPE_SET_ACCEPT
*/
struct GNUNET_MessageHeader header;
/**
- * request id of the request we want to accept
+ * ID of the incoming request we want to accept.
+ */
+ uint32_t accept_reject_id GNUNET_PACKED;
+
+ /**
+ * Request ID to identify responses.
*/
uint32_t request_id GNUNET_PACKED;
/**
- * Zero if the client has rejected the request,
- * non-zero if it has accepted it
+ * How should results be sent to us?
+ * See `enum GNUNET_SET_ResultMode`.
*/
- uint32_t accepted GNUNET_PACKED;
+ uint32_t result_mode GNUNET_PACKED;
};
-struct RequestMessage
+/**
+ * Message sent by a listening client to the service to reject
+ * performing the operation with the other peer.
+ */
+struct GNUNET_SET_RejectMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_Request
+ * Type: #GNUNET_MESSAGE_TYPE_SET_REJECT
*/
struct GNUNET_MessageHeader header;
/**
- * 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
+{
/**
- * request id of the request we want to accept
+ * Type: #GNUNET_MESSAGE_TYPE_SET_REQUEST.
*/
- uint32_t request_id GNUNET_PACKED;
+ struct GNUNET_MessageHeader header;
- /* rest: inner message */
+ /**
+ * ID of the to identify the request when accepting or
+ * rejecting it.
+ */
+ uint32_t accept_id GNUNET_PACKED;
+
+ /**
+ * Identity of the requesting peer.
+ */
+ struct GNUNET_PeerIdentity peer_id;
+
+ /* rest: context message, that is, application-specific
+ message to convince listener to pick up */
};
-struct EvaluateMessage
+/**
+ * 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;
+ /**
+ * How should results be sent to us?
+ * See `enum GNUNET_SET_ResultMode`.
+ */
+ uint32_t result_mode GNUNET_PACKED;
+
/**
* Peer to evaluate the operation with
*/
- struct GNUNET_PeerIdentity peer;
+ struct GNUNET_PeerIdentity target_peer;
/**
* Application id
struct GNUNET_HashCode app_id;
/**
- * id of our evaluate
+ * Id of our set to evaluate, chosen implicitly by the client when it
+ * calls #GNUNE_SET_commit().
*/
uint32_t request_id GNUNET_PACKED;
- /* rest: inner message */
+ /* rest: context message, that is, application-specific
+ message to convince listener to pick up */
};
-struct ResultMessage
+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;
};
-struct ElementMessage
+/**
+ * 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 CancelMessage
+/**
+ * Sent to the service by the client
+ * in order to cancel a set operation.
+ */
+struct GNUNET_SET_CancelMessage
{
/**
- * Type: GNUNET_MESSAGE_TYPE_SET_CANCEL
+ * Type: #GNUNET_MESSAGE_TYPE_SET_CANCEL
*/
struct GNUNET_MessageHeader header;
/**
- * id we want to cancel result belongs to
+ * ID of the request we want to cancel.
*/
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
+ */
+ 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.
+ */
+ uint16_t element_type GNUNET_PACKED;
+
+ /* rest: element */
+};
+
+
+/**
+ * Client acknowledges receiving element in iteration.
+ */
+struct GNUNET_SET_IterAckMessage
+{
+ /**
+ * Type: #GNUNET_MESSAGE_TYPE_SET_ITER_ACK
+ */
+ struct GNUNET_MessageHeader header;
+
+ /**
+ * Non-zero if the service should continue sending elements.
+ */
+ uint32_t send_more;
+};
+
GNUNET_NETWORK_STRUCT_END
#endif