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    * Currently observed latency.
 133    */
 134   struct GNUNET_TIME_RelativeNBO latency;
 135
 136   /**
 137    * Identity of the connecting peer.
 138    */
 139   struct GNUNET_PeerIdentity peer;
 140
 141   /**
 142    * First of the ATS information blocks (we must have at least
 143    * one due to the 0-termination requirement).
 144    */
 145   struct GNUNET_TRANSPORT_ATS_Information ats;
 146
 147 };
 148
 149
 150 /**
 151  * Message sent by the service to clients to notify them
 152  * about a peer changing status.
 153  */
 154 struct PeerStatusNotifyMessage
 155 {
 156   /**
 157    * Header with type GNUNET_MESSAGE_TYPE_CORE_NOTIFY_PEER_STATUS
 158    */
 159   struct GNUNET_MessageHeader header;
 160
 161   /**
 162    * Number of ATS key-value pairs that follow this struct
 163    * (excluding the 0-terminator).
 164    */
 165   uint32_t ats_count GNUNET_PACKED;
 166
 167   /**
 168    * When the peer would time out (unless we see activity)
 169    */
 170   struct GNUNET_TIME_AbsoluteNBO timeout;
 171
 172   /**
 173    * Available bandwidth from the peer.
 174    */
 175   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 176
 177   /**
 178    * Available bandwidth to the peer.
 179    */
 180   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 181
 182   /**
 183    * Identity of the peer.
 184    */
 185   struct GNUNET_PeerIdentity peer;
 186
 187   /**
 188    * First of the ATS information blocks (we must have at least
 189    * one due to the 0-termination requirement).
 190    */
 191   struct GNUNET_TRANSPORT_ATS_Information ats;
 192
 193 };
 194
 195
 196 /**
 197  * Message sent by the service to clients to notify them
 198  * about a peer disconnecting.
 199  */
 200 struct DisconnectNotifyMessage
 201 {
 202   /**
 203    * Header with type GNUNET_MESSAGE_TYPE_CORE_NOTIFY_DISCONNECT.
 204    */
 205   struct GNUNET_MessageHeader header;
 206
 207   /**
 208    * Always zero.
 209    */
 210   uint32_t reserved GNUNET_PACKED;
 211
 212   /**
 213    * Identity of the connecting peer.
 214    */
 215   struct GNUNET_PeerIdentity peer;
 216
 217 };
 218
 219
 220 /**
 221  * Message sent by the service to clients to notify them about
 222  * messages being received or transmitted.  This overall message is
 223  * followed by the real message, or just the header of the real
 224  * message (depending on the client's preferences).  The receiver can
 225  * tell if he got the full message or only a partial message by
 226  * looking at the size field in the header of NotifyTrafficMessage and
 227  * checking it with the size field in the message that follows.
 228  */
 229 struct NotifyTrafficMessage
 230 {
 231   /**
 232    * Header with type GNUNET_MESSAGE_TYPE_CORE_NOTIFY_INBOUND
 233    * or GNUNET_MESSAGE_TYPE_CORE_NOTIFY_OUTBOUND.
 234    */
 235   struct GNUNET_MessageHeader header;
 236
 237   /**
 238    * Number of ATS key-value pairs that follow this struct
 239    * (excluding the 0-terminator).
 240    */
 241   uint32_t ats_count GNUNET_PACKED;
 242
 243   /**
 244    * Currently observed latency.
 245    */
 246   struct GNUNET_TIME_RelativeNBO latency;
 247
 248   /**
 249    * Identity of the receiver or sender.
 250    */
 251   struct GNUNET_PeerIdentity peer;
 252
 253   /**
 254    * First of the ATS information blocks (we must have at least
 255    * one due to the 0-termination requirement).
 256    */
 257   struct GNUNET_TRANSPORT_ATS_Information ats;
 258
 259 };
 260
 261
 262 /**
 263  * Message sent to the core asking for configuration
 264  * information and possibly preference changes.
 265  */
 266 struct RequestInfoMessage
 267 {
 268   /**
 269    * Header with type GNUNET_MESSAGE_TYPE_CORE_REQUEST_CONFIGURE
 270    */
 271   struct GNUNET_MessageHeader header;
 272
 273   /**
 274    * Unique request ID.
 275    */
 276   uint32_t rim_id GNUNET_PACKED;
 277
 278   /**
 279    * Limit the number of bytes of outbound traffic to this
 280    * peer to at most the specified amount (naturally, the
 281    * amount is also limited by the receiving peer).
 282    */
 283   struct GNUNET_BANDWIDTH_Value32NBO limit_outbound;
 284
 285   /**
 286    * Number of bytes of inbound traffic to reserve, can
 287    * be negative (to unreserve).  NBO.
 288    */
 289   int32_t reserve_inbound GNUNET_PACKED;
 290
 291   /**
 292    * Increment the current traffic preference for the given peer by
 293    * the specified amont.  The traffic preference is used to determine
 294    * the share of bandwidth this peer will typcially be assigned.
 295    */
 296   uint64_t preference_change GNUNET_PACKED;
 297
 298   /**
 299    * Identity of the peer being configured.
 300    */
 301   struct GNUNET_PeerIdentity peer;
 302
 303 };
 304
 305
 306 /**
 307  * Response from the core to a "RequestInfoMessage"
 308  * providing traffic status information for a peer.
 309  */
 310 struct ConfigurationInfoMessage
 311 {
 312   /**
 313    * Header with type GNUNET_MESSAGE_TYPE_CORE_CONFIGURATION_INFO
 314    */
 315   struct GNUNET_MessageHeader header;
 316
 317   /**
 318    * Amount of traffic (inbound number of bytes) that was reserved in
 319    * response to the configuration change request.  Negative for
 320    * "unreserved" bytes.
 321    */
 322   int32_t reserved_amount GNUNET_PACKED;
 323
 324   /**
 325    * Unique request ID.
 326    */
 327   uint32_t rim_id GNUNET_PACKED;
 328
 329   /**
 330    * Available bandwidth out for this peer,
 331    * 0 if we have been disconnected.
 332    */
 333   struct GNUNET_BANDWIDTH_Value32NBO bw_out;
 334
 335   /**
 336    * Current traffic preference for the peer.
 337    * 0 if we have been disconnected.
 338    */
 339   uint64_t preference;
 340
 341   /**
 342    * Identity of the peer.
 343    */
 344   struct GNUNET_PeerIdentity peer;
 345
 346 };
 347
 348
 349 /**
 350  * Client notifying core about the maximum-priority
 351  * message it has in the queue for a particular target.
 352  */
 353 struct SendMessageRequest
 354 {
 355   /**
 356    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND_REQUEST
 357    */
 358   struct GNUNET_MessageHeader header;
 359
 360   /**
 361    * How important is this message?
 362    */
 363   uint32_t priority GNUNET_PACKED;
 364
 365   /**
 366    * By what time would the sender really like to see this
 367    * message transmitted?
 368    */
 369   struct GNUNET_TIME_AbsoluteNBO deadline;
 370
 371   /**
 372    * Identity of the intended target.
 373    */
 374   struct GNUNET_PeerIdentity peer;
 375
 376   /**
 377    * How large is the client's message queue for this peer?
 378    */
 379   uint32_t queue_size GNUNET_PACKED;
 380
 381   /**
 382    * How large is the message?
 383    */
 384   uint16_t size GNUNET_PACKED;
 385
 386   /**
 387    * Counter for this peer to match SMRs to replies.
 388    */
 389   uint16_t smr_id GNUNET_PACKED;
 390
 391 };
 392
 393
 394 /**
 395  * Core notifying client that it is allowed to now
 396  * transmit a message to the given target
 397  * (response to GNUNET_MESSAGE_TYPE_CORE_SEND_REQUEST).
 398  */
 399 struct SendMessageReady
 400 {
 401   /**
 402    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND_READY
 403    */
 404   struct GNUNET_MessageHeader header;
 405
 406   /**
 407    * How many bytes are allowed for transmission?
 408    * Guaranteed to be at least as big as the requested size,
 409    * or ZERO if the request is rejected (will timeout,
 410    * peer disconnected, queue full, etc.).
 411    */
 412   uint16_t size GNUNET_PACKED;
 413
 414   /**
 415    * smr_id from the request.
 416    */
 417   uint16_t smr_id GNUNET_PACKED;
 418
 419   /**
 420    * Identity of the intended target.
 421    */
 422   struct GNUNET_PeerIdentity peer;
 423
 424 };
 425
 426
 427 /**
 428  * Client asking core to transmit a particular message to a particular
 429  * target (responsde to GNUNET_MESSAGE_TYPE_CORE_SEND_READY).
 430  */
 431 struct SendMessage
 432 {
 433   /**
 434    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND
 435    */
 436   struct GNUNET_MessageHeader header;
 437
 438   /**
 439    * How important is this message?
 440    */
 441   uint32_t priority GNUNET_PACKED;
 442
 443   /**
 444    * By what time would the sender really like to see this
 445    * message transmitted?
 446    */
 447   struct GNUNET_TIME_AbsoluteNBO deadline;
 448
 449   /**
 450    * Identity of the receiver or sender.
 451    */
 452   struct GNUNET_PeerIdentity peer;
 453
 454 };
 455
 456
 457 /**
 458  * Client asking core to connect to a particular target.  There is no
 459  * response from the core to this type of request (however, if an
 460  * actual connection is created or destroyed, be it because of this
 461  * type request or not, the core generally needs to notify the
 462  * clients).
 463  */
 464 struct ConnectMessage
 465 {
 466   /**
 467    * Header with type GNUNET_MESSAGE_TYPE_REQUEST_CONNECT or
 468    * GNUNET_MESSAGE_TYPE_REQUEST_DISCONNECT.
 469    */
 470   struct GNUNET_MessageHeader header;
 471
 472   /**
 473    * For alignment.
 474    */
 475   uint32_t reserved GNUNET_PACKED;
 476
 477   /**
 478    * When to time out.
 479    */
 480   struct GNUNET_TIME_RelativeNBO timeout;
 481
 482   /**
 483    * Identity of the other peer.
 484    */
 485   struct GNUNET_PeerIdentity peer;
 486
 487 };
 488
 489 /* end of core.h */