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