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      SPDX-License-Identifier: AGPL3.0-or-later
  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  * Message sent by a listening client to the service to accept
  80  * performing the operation with the other peer.
  81  */
  82 struct GNUNET_SET_AcceptMessage
  83 {
  84   /**
  85    * Type: #GNUNET_MESSAGE_TYPE_SET_ACCEPT
  86    */
  87   struct GNUNET_MessageHeader header;
  88
  89   /**
  90    * ID of the incoming request we want to accept.
  91    */
  92   uint32_t accept_reject_id GNUNET_PACKED;
  93
  94   /**
  95    * Request ID to identify responses.
  96    */
  97   uint32_t request_id GNUNET_PACKED;
  98
  99   /**
 100    * How should results be sent to us?
 101    * See `enum GNUNET_SET_ResultMode`.
 102    */
 103   uint32_t result_mode GNUNET_PACKED;
 104
 105   /**
 106    * Always use delta operation instead of sending full sets,
 107    * even it it's less efficient.
 108    */
 109   uint8_t force_delta;
 110
 111   /**
 112    * Always send full sets, even if delta operations would
 113    * be more efficient.
 114    */
 115   uint8_t force_full;
 116
 117   /**
 118    * #GNUNET_YES to fail operations where Byzantine faults
 119    * are suspected
 120    */
 121   uint8_t byzantine;
 122
 123   /**
 124    * Lower bound for the set size, used only when
 125    * byzantine mode is enabled.
 126    */
 127   uint8_t byzantine_lower_bound;
 128 };
 129
 130
 131 /**
 132  * Message sent by a listening client to the service to reject
 133  * performing the operation with the other peer.
 134  */
 135 struct GNUNET_SET_RejectMessage
 136 {
 137   /**
 138    * Type: #GNUNET_MESSAGE_TYPE_SET_REJECT
 139    */
 140   struct GNUNET_MessageHeader header;
 141
 142   /**
 143    * ID of the incoming request we want to reject.
 144    */
 145   uint32_t accept_reject_id GNUNET_PACKED;
 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