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