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