src/core/core.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009, 2010 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file core/core.h
  23  * @brief common internal definitions for core service
  24  * @author Christian Grothoff
  25  */
  26 #include "gnunet_bandwidth_lib.h"
  27 #include "gnunet_crypto_lib.h"
  28 #include "gnunet_time_lib.h"
  29
  30 /**
  31  * General core debugging.
  32  */
  33 #define DEBUG_CORE GNUNET_NO
  34
  35 /**
  36  * Debugging interaction core-clients.
  37  */
  38 #define DEBUG_CORE_CLIENT GNUNET_NO
  39
  40 /**
  41  * Definition of bits in the InitMessage's options field that specify
  42  * which events this client cares about.  Note that inbound messages
  43  * for handlers that were specifically registered are always
  44  * transmitted to the client.
  45  */
  46 #define GNUNET_CORE_OPTION_NOTHING             0
  47 #define GNUNET_CORE_OPTION_SEND_CONNECT        1
  48 #define GNUNET_CORE_OPTION_SEND_DISCONNECT     2
  49 #define GNUNET_CORE_OPTION_SEND_STATUS_CHANGE  4
  50 #define GNUNET_CORE_OPTION_SEND_FULL_INBOUND   8
  51 #define GNUNET_CORE_OPTION_SEND_HDR_INBOUND   16
  52 #define GNUNET_CORE_OPTION_SEND_FULL_OUTBOUND 32
  53 #define GNUNET_CORE_OPTION_SEND_HDR_OUTBOUND  64
  54
  55
  56 /**
  57  * Message transmitted core clients to gnunet-service-core
  58  * to start the interaction.  This header is followed by
  59  * uint16_t type values specifying which messages this
  60  * client is interested in.
  61  */
  62 struct InitMessage
  63 {
  64
  65   /**
  66    * Header with type GNUNET_MESSAGE_TYPE_CORE_INIT.
  67    */
  68   struct GNUNET_MessageHeader header;
  69
  70   /**
  71    * Options, see GNUNET_CORE_OPTION_ values.
  72    */
  73   uint32_t options GNUNET_PACKED;
  74
  75 };
  76
  77
  78 /**
  79  * Message transmitted by the gnunet-service-core process
  80  * to its clients in response to an INIT message.
  81  */
  82 struct InitReplyMessage
  83 {
  84
  85   /**
  86    * Header with type GNUNET_MESSAGE_TYPE_CORE_INIT_REPLY
  87    */
  88   struct GNUNET_MessageHeader header;
  89
  90   /**
  91    * Always zero.
  92    */
  93   uint32_t reserved GNUNET_PACKED;
  94
  95   /**
  96    * Public key of the local peer.
  97    */
  98   struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded publicKey;
  99
 100 };
 101
 102
 103 /**
 104  * Message sent by the service to clients to notify them
 105  * about a peer connecting.
 106  */
 107 struct ConnectNotifyMessage
 108 {
 109   /**
 110    * Header with type GNUNET_MESSAGE_TYPE_CORE_NOTIFY_CONNECT
 111    */
 112   struct GNUNET_MessageHeader header;
 113
 114   /**
 115    * Number of ATS key-value pairs that follow this struct
 116    * (excluding the 0-terminator).
 117    */
 118   uint32_t ats_count GNUNET_PACKED;
 119
 120   /**
 121    * Identity of the connecting peer.
 122    */
 123   struct GNUNET_PeerIdentity peer;
 124
 125   /**
 126    * First of the ATS information blocks (we must have at least
 127    * one due to the 0-termination requirement).
 128    */
 129   struct GNUNET_TRANSPORT_ATS_Information ats;
 130
 131 };
 132
 133
 134 /**
 135  * Message sent by the service to clients to notify them
 136  * about a peer changing status.
 137  */
 138 struct PeerStatusNotifyMessage
 139 {
 140   /**
 141    * Header with type GNUNET_MESSAGE_TYPE_CORE_NOTIFY_PEER_STATUS
 142    */
 143   struct GNUNET_MessageHeader header;
 144
 145   /**
 146    * Number of ATS key-value pairs that follow this struct
 147    * (excluding the 0-terminator).
 148    */
 149   uint32_t ats_count GNUNET_PACKED;
 150
 151   /**
 152    * When the peer would time out (unless we see activity)
 153    */
 154   struct GNUNET_TIME_AbsoluteNBO timeout;
 155
 156   /**
 157    * Available bandwidth from the peer.
 158    */
 159   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 160
 161   /**
 162    * Available bandwidth to the peer.
 163    */
 164   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 165
 166   /**
 167    * Identity of the peer.
 168    */
 169   struct GNUNET_PeerIdentity peer;
 170
 171   /**
 172    * First of the ATS information blocks (we must have at least
 173    * one due to the 0-termination requirement).
 174    */
 175   struct GNUNET_TRANSPORT_ATS_Information ats;
 176
 177 };
 178
 179
 180 /**
 181  * Message sent by the service to clients to notify them
 182  * about a peer disconnecting.
 183  */
 184 struct DisconnectNotifyMessage
 185 {
 186   /**
 187    * Header with type GNUNET_MESSAGE_TYPE_CORE_NOTIFY_DISCONNECT.
 188    */
 189   struct GNUNET_MessageHeader header;
 190
 191   /**
 192    * Always zero.
 193    */
 194   uint32_t reserved GNUNET_PACKED;
 195
 196   /**
 197    * Identity of the connecting peer.
 198    */
 199   struct GNUNET_PeerIdentity peer;
 200
 201 };
 202
 203
 204 /**
 205  * Message sent by the service to clients to notify them about
 206  * messages being received or transmitted.  This overall message is
 207  * followed by the real message, or just the header of the real
 208  * message (depending on the client's preferences).  The receiver can
 209  * tell if he got the full message or only a partial message by
 210  * looking at the size field in the header of NotifyTrafficMessage and
 211  * checking it with the size field in the message that follows.
 212  */
 213 struct NotifyTrafficMessage
 214 {
 215   /**
 216    * Header with type GNUNET_MESSAGE_TYPE_CORE_NOTIFY_INBOUND
 217    * or GNUNET_MESSAGE_TYPE_CORE_NOTIFY_OUTBOUND.
 218    */
 219   struct GNUNET_MessageHeader header;
 220
 221   /**
 222    * Number of ATS key-value pairs that follow this struct
 223    * (excluding the 0-terminator).
 224    */
 225   uint32_t ats_count GNUNET_PACKED;
 226
 227   /**
 228    * Identity of the receiver or sender.
 229    */
 230   struct GNUNET_PeerIdentity peer;
 231
 232   /**
 233    * First of the ATS information blocks (we must have at least
 234    * one due to the 0-termination requirement).
 235    */
 236   struct GNUNET_TRANSPORT_ATS_Information ats;
 237
 238 };
 239
 240
 241 /**
 242  * Message sent to the core asking for configuration
 243  * information and possibly preference changes.
 244  */
 245 struct RequestInfoMessage
 246 {
 247   /**
 248    * Header with type GNUNET_MESSAGE_TYPE_CORE_REQUEST_CONFIGURE
 249    */
 250   struct GNUNET_MessageHeader header;
 251
 252   /**
 253    * Unique request ID.
 254    */
 255   uint32_t rim_id GNUNET_PACKED;
 256
 257   /**
 258    * Limit the number of bytes of outbound traffic to this
 259    * peer to at most the specified amount (naturally, the
 260    * amount is also limited by the receiving peer).
 261    */
 262   struct GNUNET_BANDWIDTH_Value32NBO limit_outbound;
 263
 264   /**
 265    * Number of bytes of inbound traffic to reserve, can
 266    * be negative (to unreserve).  NBO.
 267    */
 268   int32_t reserve_inbound GNUNET_PACKED;
 269
 270   /**
 271    * Increment the current traffic preference for the given peer by
 272    * the specified amont.  The traffic preference is used to determine
 273    * the share of bandwidth this peer will typcially be assigned.
 274    */
 275   uint64_t preference_change GNUNET_PACKED;
 276
 277   /**
 278    * Identity of the peer being configured.
 279    */
 280   struct GNUNET_PeerIdentity peer;
 281
 282 };
 283
 284
 285 /**
 286  * Response from the core to a "RequestInfoMessage"
 287  * providing traffic status information for a peer.
 288  */
 289 struct ConfigurationInfoMessage
 290 {
 291   /**
 292    * Header with type GNUNET_MESSAGE_TYPE_CORE_CONFIGURATION_INFO
 293    */
 294   struct GNUNET_MessageHeader header;
 295
 296   /**
 297    * Amount of traffic (inbound number of bytes) that was reserved in
 298    * response to the configuration change request.  Negative for
 299    * "unreserved" bytes.
 300    */
 301   int32_t reserved_amount GNUNET_PACKED;
 302
 303   /**
 304    * If the reservation request could not be satisfied (reserved_amount
 305    * was zero), how long should the client wait until retrying? 0 if
 306    * bandwidth was reserved.
 307    */
 308   struct GNUNET_TIME_RelativeNBO reserve_delay;
 309
 310   /**
 311    * Unique request ID.
 312    */
 313   uint32_t rim_id GNUNET_PACKED;
 314
 315   /**
 316    * Available bandwidth out for this peer,
 317    * 0 if we have been disconnected.
 318    */
 319   struct GNUNET_BANDWIDTH_Value32NBO bw_out;
 320
 321   /**
 322    * Current traffic preference for the peer.
 323    * 0 if we have been disconnected.
 324    */
 325   uint64_t preference;
 326
 327   /**
 328    * Identity of the peer.
 329    */
 330   struct GNUNET_PeerIdentity peer;
 331
 332 };
 333
 334
 335 /**
 336  * Client notifying core about the maximum-priority
 337  * message it has in the queue for a particular target.
 338  */
 339 struct SendMessageRequest
 340 {
 341   /**
 342    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND_REQUEST
 343    */
 344   struct GNUNET_MessageHeader header;
 345
 346   /**
 347    * How important is this message?
 348    */
 349   uint32_t priority GNUNET_PACKED;
 350
 351   /**
 352    * By what time would the sender really like to see this
 353    * message transmitted?
 354    */
 355   struct GNUNET_TIME_AbsoluteNBO deadline;
 356
 357   /**
 358    * Identity of the intended target.
 359    */
 360   struct GNUNET_PeerIdentity peer;
 361
 362   /**
 363    * How large is the client's message queue for this peer?
 364    */
 365   uint32_t queue_size GNUNET_PACKED;
 366
 367   /**
 368    * How large is the message?
 369    */
 370   uint16_t size GNUNET_PACKED;
 371
 372   /**
 373    * Counter for this peer to match SMRs to replies.
 374    */
 375   uint16_t smr_id GNUNET_PACKED;
 376
 377 };
 378
 379
 380 /**
 381  * Core notifying client that it is allowed to now
 382  * transmit a message to the given target
 383  * (response to GNUNET_MESSAGE_TYPE_CORE_SEND_REQUEST).
 384  */
 385 struct SendMessageReady
 386 {
 387   /**
 388    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND_READY
 389    */
 390   struct GNUNET_MessageHeader header;
 391
 392   /**
 393    * How many bytes are allowed for transmission?
 394    * Guaranteed to be at least as big as the requested size,
 395    * or ZERO if the request is rejected (will timeout,
 396    * peer disconnected, queue full, etc.).
 397    */
 398   uint16_t size GNUNET_PACKED;
 399
 400   /**
 401    * smr_id from the request.
 402    */
 403   uint16_t smr_id GNUNET_PACKED;
 404
 405   /**
 406    * Identity of the intended target.
 407    */
 408   struct GNUNET_PeerIdentity peer;
 409
 410 };
 411
 412
 413 /**
 414  * Client asking core to transmit a particular message to a particular
 415  * target (responsde to GNUNET_MESSAGE_TYPE_CORE_SEND_READY).
 416  */
 417 struct SendMessage
 418 {
 419   /**
 420    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND
 421    */
 422   struct GNUNET_MessageHeader header;
 423
 424   /**
 425    * How important is this message?
 426    */
 427   uint32_t priority GNUNET_PACKED;
 428
 429   /**
 430    * By what time would the sender really like to see this
 431    * message transmitted?
 432    */
 433   struct GNUNET_TIME_AbsoluteNBO deadline;
 434
 435   /**
 436    * Identity of the receiver or sender.
 437    */
 438   struct GNUNET_PeerIdentity peer;
 439
 440   /**
 441    * GNUNET_YES if corking is allowed, GNUNET_NO if not.
 442    */
 443   uint32_t cork GNUNET_PACKED;
 444
 445   /**
 446    * Always 0.
 447    */
 448   uint64_t reserved GNUNET_PACKED;
 449
 450 };
 451
 452
 453 /**
 454  * Client asking core to connect to a particular target.  There is no
 455  * response from the core to this type of request (however, if an
 456  * actual connection is created or destroyed, be it because of this
 457  * type request or not, the core generally needs to notify the
 458  * clients).
 459  */
 460 struct ConnectMessage
 461 {
 462   /**
 463    * Header with type GNUNET_MESSAGE_TYPE_REQUEST_CONNECT or
 464    * GNUNET_MESSAGE_TYPE_REQUEST_DISCONNECT.
 465    */
 466   struct GNUNET_MessageHeader header;
 467
 468   /**
 469    * For alignment.
 470    */
 471   uint32_t reserved GNUNET_PACKED;
 472
 473   /**
 474    * When to time out.
 475    */
 476   struct GNUNET_TIME_RelativeNBO timeout;
 477
 478   /**
 479    * Identity of the other peer.
 480    */
 481   struct GNUNET_PeerIdentity peer;
 482
 483 };
 484
 485 /* end of core.h */