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    * Identity of the receiver or sender.
 240    */
 241   struct GNUNET_PeerIdentity peer;
 242
 243   /**
 244    * First of the ATS information blocks (we must have at least
 245    * one due to the 0-termination requirement).
 246    */
 247   struct GNUNET_TRANSPORT_ATS_Information ats;
 248
 249 };
 250
 251
 252 /**
 253  * Message sent to the core asking for configuration
 254  * information and possibly preference changes.
 255  */
 256 struct RequestInfoMessage
 257 {
 258   /**
 259    * Header with type GNUNET_MESSAGE_TYPE_CORE_REQUEST_CONFIGURE
 260    */
 261   struct GNUNET_MessageHeader header;
 262
 263   /**
 264    * Unique request ID.
 265    */
 266   uint32_t rim_id GNUNET_PACKED;
 267
 268   /**
 269    * Limit the number of bytes of outbound traffic to this
 270    * peer to at most the specified amount (naturally, the
 271    * amount is also limited by the receiving peer).
 272    */
 273   struct GNUNET_BANDWIDTH_Value32NBO limit_outbound;
 274
 275   /**
 276    * Number of bytes of inbound traffic to reserve, can
 277    * be negative (to unreserve).  NBO.
 278    */
 279   int32_t reserve_inbound GNUNET_PACKED;
 280
 281   /**
 282    * Increment the current traffic preference for the given peer by
 283    * the specified amont.  The traffic preference is used to determine
 284    * the share of bandwidth this peer will typcially be assigned.
 285    */
 286   uint64_t preference_change GNUNET_PACKED;
 287
 288   /**
 289    * Identity of the peer being configured.
 290    */
 291   struct GNUNET_PeerIdentity peer;
 292
 293 };
 294
 295
 296 /**
 297  * Response from the core to a "RequestInfoMessage"
 298  * providing traffic status information for a peer.
 299  */
 300 struct ConfigurationInfoMessage
 301 {
 302   /**
 303    * Header with type GNUNET_MESSAGE_TYPE_CORE_CONFIGURATION_INFO
 304    */
 305   struct GNUNET_MessageHeader header;
 306
 307   /**
 308    * Amount of traffic (inbound number of bytes) that was reserved in
 309    * response to the configuration change request.  Negative for
 310    * "unreserved" bytes.
 311    */
 312   int32_t reserved_amount GNUNET_PACKED;
 313
 314   /**
 315    * Unique request ID.
 316    */
 317   uint32_t rim_id GNUNET_PACKED;
 318
 319   /**
 320    * Available bandwidth out for this peer,
 321    * 0 if we have been disconnected.
 322    */
 323   struct GNUNET_BANDWIDTH_Value32NBO bw_out;
 324
 325   /**
 326    * Current traffic preference for the peer.
 327    * 0 if we have been disconnected.
 328    */
 329   uint64_t preference;
 330
 331   /**
 332    * Identity of the peer.
 333    */
 334   struct GNUNET_PeerIdentity peer;
 335
 336 };
 337
 338
 339 /**
 340  * Client notifying core about the maximum-priority
 341  * message it has in the queue for a particular target.
 342  */
 343 struct SendMessageRequest
 344 {
 345   /**
 346    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND_REQUEST
 347    */
 348   struct GNUNET_MessageHeader header;
 349
 350   /**
 351    * How important is this message?
 352    */
 353   uint32_t priority GNUNET_PACKED;
 354
 355   /**
 356    * By what time would the sender really like to see this
 357    * message transmitted?
 358    */
 359   struct GNUNET_TIME_AbsoluteNBO deadline;
 360
 361   /**
 362    * Identity of the intended target.
 363    */
 364   struct GNUNET_PeerIdentity peer;
 365
 366   /**
 367    * How large is the client's message queue for this peer?
 368    */
 369   uint32_t queue_size GNUNET_PACKED;
 370
 371   /**
 372    * How large is the message?
 373    */
 374   uint16_t size GNUNET_PACKED;
 375
 376   /**
 377    * Counter for this peer to match SMRs to replies.
 378    */
 379   uint16_t smr_id GNUNET_PACKED;
 380
 381 };
 382
 383
 384 /**
 385  * Core notifying client that it is allowed to now
 386  * transmit a message to the given target
 387  * (response to GNUNET_MESSAGE_TYPE_CORE_SEND_REQUEST).
 388  */
 389 struct SendMessageReady
 390 {
 391   /**
 392    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND_READY
 393    */
 394   struct GNUNET_MessageHeader header;
 395
 396   /**
 397    * How many bytes are allowed for transmission?
 398    * Guaranteed to be at least as big as the requested size,
 399    * or ZERO if the request is rejected (will timeout,
 400    * peer disconnected, queue full, etc.).
 401    */
 402   uint16_t size GNUNET_PACKED;
 403
 404   /**
 405    * smr_id from the request.
 406    */
 407   uint16_t smr_id GNUNET_PACKED;
 408
 409   /**
 410    * Identity of the intended target.
 411    */
 412   struct GNUNET_PeerIdentity peer;
 413
 414 };
 415
 416
 417 /**
 418  * Client asking core to transmit a particular message to a particular
 419  * target (responsde to GNUNET_MESSAGE_TYPE_CORE_SEND_READY).
 420  */
 421 struct SendMessage
 422 {
 423   /**
 424    * Header with type GNUNET_MESSAGE_TYPE_CORE_SEND
 425    */
 426   struct GNUNET_MessageHeader header;
 427
 428   /**
 429    * How important is this message?
 430    */
 431   uint32_t priority GNUNET_PACKED;
 432
 433   /**
 434    * By what time would the sender really like to see this
 435    * message transmitted?
 436    */
 437   struct GNUNET_TIME_AbsoluteNBO deadline;
 438
 439   /**
 440    * Identity of the receiver or sender.
 441    */
 442   struct GNUNET_PeerIdentity peer;
 443
 444 };
 445
 446
 447 /**
 448  * Client asking core to connect to a particular target.  There is no
 449  * response from the core to this type of request (however, if an
 450  * actual connection is created or destroyed, be it because of this
 451  * type request or not, the core generally needs to notify the
 452  * clients).
 453  */
 454 struct ConnectMessage
 455 {
 456   /**
 457    * Header with type GNUNET_MESSAGE_TYPE_REQUEST_CONNECT or
 458    * GNUNET_MESSAGE_TYPE_REQUEST_DISCONNECT.
 459    */
 460   struct GNUNET_MessageHeader header;
 461
 462   /**
 463    * For alignment.
 464    */
 465   uint32_t reserved GNUNET_PACKED;
 466
 467   /**
 468    * When to time out.
 469    */
 470   struct GNUNET_TIME_RelativeNBO timeout;
 471
 472   /**
 473    * Identity of the other peer.
 474    */
 475   struct GNUNET_PeerIdentity peer;
 476
 477 };
 478
 479 /* end of core.h */