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    * id the result belongs to
 255    */
 256   uint32_t request_id GNUNET_PACKED;
 257
 258   /**
 259    * Was the evaluation successful? Contains
 260    * an `enum GNUNET_SET_Status` in NBO.
 261    */
 262   uint16_t result_status GNUNET_PACKED;
 263
 264   /**
 265    * Type of the element attachted to the message, if any.
 266    */
 267   uint16_t element_type GNUNET_PACKED;
 268
 269   /* rest: the actual element */
 270 };
 271
 272
 273 /**
 274  * Message sent by client to the service to add or remove
 275  * an element to/from the set.
 276  */
 277 struct GNUNET_SET_ElementMessage
 278 {
 279   /**
 280    * Type: #GNUNET_MESSAGE_TYPE_SET_ADD or
 281    *       #GNUNET_MESSAGE_TYPE_SET_REMOVE
 282    */
 283   struct GNUNET_MessageHeader header;
 284
 285   /**
 286    * Type of the element to add or remove.
 287    */
 288   uint16_t element_type GNUNET_PACKED;
 289
 290   /**
 291    * For alignment, always zero.
 292    */
 293   uint16_t reserved GNUNET_PACKED;
 294
 295   /* rest: the actual element */
 296 };
 297
 298
 299 /**
 300  * Sent to the service by the client
 301  * in order to cancel a set operation.
 302  */
 303 struct GNUNET_SET_CancelMessage
 304 {
 305   /**
 306    * Type: #GNUNET_MESSAGE_TYPE_SET_CANCEL
 307    */
 308   struct GNUNET_MessageHeader header;
 309
 310   /**
 311    * ID of the request we want to cancel.
 312    */
 313   uint32_t request_id GNUNET_PACKED;
 314 };
 315
 316
 317 /**
 318  * Set element transmitted by service to client in response to a set
 319  * iteration request.
 320  */
 321 struct GNUNET_SET_IterResponseMessage
 322 {
 323   /**
 324    * Type: #GNUNET_MESSAGE_TYPE_SET_ITER_ELEMENT
 325    */
 326   struct GNUNET_MessageHeader header;
 327
 328   /**
 329    * To which set iteration does this reponse belong to?  First
 330    * iteration (per client) has counter zero. Wraps around.
 331    */
 332   uint16_t iteration_id GNUNET_PACKED;
 333
 334   /**
 335    * Type of the element attachted to the message,
 336    * if any.
 337    */
 338   uint16_t element_type GNUNET_PACKED;
 339
 340   /* rest: element */
 341 };
 342
 343
 344 /**
 345  * Client acknowledges receiving element in iteration.
 346  */
 347 struct GNUNET_SET_IterAckMessage
 348 {
 349   /**
 350    * Type: #GNUNET_MESSAGE_TYPE_SET_ITER_ACK
 351    */
 352   struct GNUNET_MessageHeader header;
 353
 354   /**
 355    * Non-zero if the service should continue sending elements.
 356    */
 357   uint32_t send_more;
 358 };
 359
 360
 361 /**
 362  * Server responds to a lazy copy request.
 363  */
 364 struct GNUNET_SET_CopyLazyResponseMessage
 365 {
 366   /**
 367    * Type: #GNUNET_MESSAGE_TYPE_SET_COPY_LAZY_RESPONSE
 368    */
 369   struct GNUNET_MessageHeader header;
 370
 371   /**
 372    * Temporary name for the copied set.
 373    */
 374   uint32_t cookie;
 375 };
 376
 377
 378 /**
 379  * Client connects to a lazily copied set.
 380  */
 381 struct GNUNET_SET_CopyLazyConnectMessage
 382 {
 383   /**
 384    * Type: #GNUNET_MESSAGE_TYPE_SET_COPY_LAZY_CONNECT
 385    */
 386   struct GNUNET_MessageHeader header;
 387
 388   /**
 389    * Temporary name for the copied set.
 390    */
 391   uint32_t cookie;
 392 };
 393
 394
 395 GNUNET_NETWORK_STRUCT_END
 396
 397 #endif