src/set/set.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2012-2014 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20 /**
  21  * @file set/set.h
  22  * @brief messages used for the set api
  23  * @author Florian Dold
  24  * @author Christian Grothoff
  25  */
  26 #ifndef SET_H
  27 #define SET_H
  28
  29 #include "platform.h"
  30 #include "gnunet_common.h"
  31 #include "gnunet_set_service.h"
  32
  33 GNUNET_NETWORK_STRUCT_BEGIN
  34
  35 /**
  36  * Message sent by the client to the service to ask starting
  37  * a new set to perform operations with.  Includes the desired
  38  * set operation type.
  39  */
  40 struct GNUNET_SET_CreateMessage
  41 {
  42   /**
  43    * Type: #GNUNET_MESSAGE_TYPE_SET_CREATE
  44    */
  45   struct GNUNET_MessageHeader header;
  46
  47   /**
  48    * Operation type, values of `enum GNUNET_SET_OperationType`
  49    */
  50   uint32_t operation GNUNET_PACKED;
  51 };
  52
  53
  54 /**
  55  * Message sent by the client to the service to start listening for
  56  * incoming requests to perform a certain type of set operation for a
  57  * certain type of application.
  58  */
  59 struct GNUNET_SET_ListenMessage
  60 {
  61   /**
  62    * Type: #GNUNET_MESSAGE_TYPE_SET_LISTEN
  63    */
  64   struct GNUNET_MessageHeader header;
  65
  66   /**
  67    * Operation type, values of `enum GNUNET_SET_OperationType`
  68    */
  69   uint32_t operation GNUNET_PACKED;
  70
  71   /**
  72    * application id
  73    */
  74   struct GNUNET_HashCode app_id;
  75
  76 };
  77
  78
  79 /**
  80  * Message sent by a listening client to the service to accept
  81  * performing the operation with the other peer.
  82  */
  83 struct GNUNET_SET_AcceptMessage
  84 {
  85   /**
  86    * Type: #GNUNET_MESSAGE_TYPE_SET_ACCEPT
  87    */
  88   struct GNUNET_MessageHeader header;
  89
  90   /**
  91    * ID of the incoming request we want to accept.
  92    */
  93   uint32_t accept_reject_id GNUNET_PACKED;
  94
  95   /**
  96    * Request ID to identify responses.
  97    */
  98   uint32_t request_id GNUNET_PACKED;
  99
 100   /**
 101    * How should results be sent to us?
 102    * See `enum GNUNET_SET_ResultMode`.
 103    */
 104   uint32_t result_mode GNUNET_PACKED;
 105
 106   /**
 107    * Always use delta operation instead of sending full sets,
 108    * even it it's less efficient.
 109    */
 110   uint8_t force_delta;
 111
 112   /**
 113    * Always send full sets, even if delta operations would
 114    * be more efficient.
 115    */
 116   uint8_t force_full;
 117
 118   /**
 119    * #GNUNET_YES to fail operations where Byzantine faults
 120    * are suspected
 121    */
 122   uint8_t byzantine;
 123
 124   /**
 125    * Lower bound for the set size, used only when
 126    * byzantine mode is enabled.
 127    */
 128   uint8_t byzantine_lower_bound;
 129 };
 130
 131
 132 /**
 133  * Message sent by a listening client to the service to reject
 134  * performing the operation with the other peer.
 135  */
 136 struct GNUNET_SET_RejectMessage
 137 {
 138   /**
 139    * Type: #GNUNET_MESSAGE_TYPE_SET_REJECT
 140    */
 141   struct GNUNET_MessageHeader header;
 142
 143   /**
 144    * ID of the incoming request we want to reject.
 145    */
 146   uint32_t accept_reject_id GNUNET_PACKED;
 147
 148 };
 149
 150
 151 /**
 152  * A request for an operation with another client.
 153  */
 154 struct GNUNET_SET_RequestMessage
 155 {
 156   /**
 157    * Type: #GNUNET_MESSAGE_TYPE_SET_REQUEST.
 158    */
 159   struct GNUNET_MessageHeader header;
 160
 161   /**
 162    * ID of the to identify the request when accepting or
 163    * rejecting it.
 164    */
 165   uint32_t accept_id GNUNET_PACKED;
 166
 167   /**
 168    * Identity of the requesting peer.
 169    */
 170   struct GNUNET_PeerIdentity peer_id;
 171
 172   /* rest: context message, that is, application-specific
 173      message to convince listener to pick up */
 174 };
 175
 176
 177 /**
 178  * Message sent by client to service to initiate a set operation as a
 179  * client (not as listener).  A set (which determines the operation
 180  * type) must already exist in association with this client.
 181  */
 182 struct GNUNET_SET_EvaluateMessage
 183 {
 184   /**
 185    * Type: #GNUNET_MESSAGE_TYPE_SET_EVALUATE
 186    */
 187   struct GNUNET_MessageHeader header;
 188
 189   /**
 190    * How should results be sent to us?
 191    * See `enum GNUNET_SET_ResultMode`.
 192    */
 193   uint32_t result_mode GNUNET_PACKED;
 194
 195   /**
 196    * Peer to evaluate the operation with
 197    */
 198   struct GNUNET_PeerIdentity target_peer;
 199
 200   /**
 201    * Application id
 202    */
 203   struct GNUNET_HashCode app_id;
 204
 205   /**
 206    * Id of our set to evaluate, chosen implicitly by the client when it
 207    * calls #GNUNET_SET_commit().
 208    */
 209   uint32_t request_id GNUNET_PACKED;
 210
 211   /**
 212    * Always use delta operation instead of sending full sets,
 213    * even it it's less efficient.
 214    */
 215   uint8_t force_delta;
 216
 217   /**
 218    * Always send full sets, even if delta operations would
 219    * be more efficient.
 220    */
 221   uint8_t force_full;
 222
 223   /**
 224    * #GNUNET_YES to fail operations where Byzantine faults
 225    * are suspected
 226    */
 227   uint8_t byzantine;
 228
 229   /**
 230    * Lower bound for the set size, used only when
 231    * byzantine mode is enabled.
 232    */
 233   uint8_t byzantine_lower_bound;
 234
 235   /* rest: context message, that is, application-specific
 236      message to convince listener to pick up */
 237 };
 238
 239
 240 /**
 241  * Message sent by the service to the client to indicate an
 242  * element that is removed (set intersection) or added
 243  * (set union) or part of the final result, depending on
 244  * options specified for the operation.
 245  */
 246 struct GNUNET_SET_ResultMessage
 247 {
 248   /**
 249    * Type: #GNUNET_MESSAGE_TYPE_SET_RESULT
 250    */
 251   struct GNUNET_MessageHeader header;
 252
 253   /**
 254    * Current set size.
 255    */
 256   uint64_t current_size;
 257
 258   /**
 259    * id the result belongs to
 260    */
 261   uint32_t request_id GNUNET_PACKED;
 262
 263   /**
 264    * Was the evaluation successful? Contains
 265    * an `enum GNUNET_SET_Status` in NBO.
 266    */
 267   uint16_t result_status GNUNET_PACKED;
 268
 269   /**
 270    * Type of the element attachted to the message, if any.
 271    */
 272   uint16_t element_type GNUNET_PACKED;
 273
 274   /* rest: the actual element */
 275 };
 276
 277
 278 /**
 279  * Message sent by client to the service to add or remove
 280  * an element to/from the set.
 281  */
 282 struct GNUNET_SET_ElementMessage
 283 {
 284   /**
 285    * Type: #GNUNET_MESSAGE_TYPE_SET_ADD or
 286    *       #GNUNET_MESSAGE_TYPE_SET_REMOVE
 287    */
 288   struct GNUNET_MessageHeader header;
 289
 290   /**
 291    * Type of the element to add or remove.
 292    */
 293   uint16_t element_type GNUNET_PACKED;
 294
 295   /**
 296    * For alignment, always zero.
 297    */
 298   uint16_t reserved GNUNET_PACKED;
 299
 300   /* rest: the actual element */
 301 };
 302
 303
 304 /**
 305  * Sent to the service by the client
 306  * in order to cancel a set operation.
 307  */
 308 struct GNUNET_SET_CancelMessage
 309 {
 310   /**
 311    * Type: #GNUNET_MESSAGE_TYPE_SET_CANCEL
 312    */
 313   struct GNUNET_MessageHeader header;
 314
 315   /**
 316    * ID of the request we want to cancel.
 317    */
 318   uint32_t request_id GNUNET_PACKED;
 319 };
 320
 321
 322 /**
 323  * Set element transmitted by service to client in response to a set
 324  * iteration request.
 325  */
 326 struct GNUNET_SET_IterResponseMessage
 327 {
 328   /**
 329    * Type: #GNUNET_MESSAGE_TYPE_SET_ITER_ELEMENT
 330    */
 331   struct GNUNET_MessageHeader header;
 332
 333   /**
 334    * To which set iteration does this reponse belong to?  First
 335    * iteration (per client) has counter zero. Wraps around.
 336    */
 337   uint16_t iteration_id GNUNET_PACKED;
 338
 339   /**
 340    * Type of the element attachted to the message,
 341    * if any.
 342    */
 343   uint16_t element_type GNUNET_PACKED;
 344
 345   /* rest: element */
 346 };
 347
 348
 349 /**
 350  * Client acknowledges receiving element in iteration.
 351  */
 352 struct GNUNET_SET_IterAckMessage
 353 {
 354   /**
 355    * Type: #GNUNET_MESSAGE_TYPE_SET_ITER_ACK
 356    */
 357   struct GNUNET_MessageHeader header;
 358
 359   /**
 360    * Non-zero if the service should continue sending elements.
 361    */
 362   uint32_t send_more;
 363 };
 364
 365
 366 /**
 367  * Server responds to a lazy copy request.
 368  */
 369 struct GNUNET_SET_CopyLazyResponseMessage
 370 {
 371   /**
 372    * Type: #GNUNET_MESSAGE_TYPE_SET_COPY_LAZY_RESPONSE
 373    */
 374   struct GNUNET_MessageHeader header;
 375
 376   /**
 377    * Temporary name for the copied set.
 378    */
 379   uint32_t cookie;
 380 };
 381
 382
 383 /**
 384  * Client connects to a lazily copied set.
 385  */
 386 struct GNUNET_SET_CopyLazyConnectMessage
 387 {
 388   /**
 389    * Type: #GNUNET_MESSAGE_TYPE_SET_COPY_LAZY_CONNECT
 390    */
 391   struct GNUNET_MessageHeader header;
 392
 393   /**
 394    * Temporary name for the copied set.
 395    */
 396   uint32_t cookie;
 397 };
 398
 399
 400 GNUNET_NETWORK_STRUCT_END
 401
 402 #endif