src/include/gnunet_core_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009 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 2, 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 include/gnunet_core_service.h
  23  * @brief core service; this is the main API for encrypted P2P
  24  *        communications
  25  * @author Christian Grothoff
  26  */
  27
  28 #ifndef GNUNET_CORE_SERVICE_H
  29 #define GNUNET_CORE_SERVICE_H
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #if 0                           /* keep Emacsens' auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39 #include "gnunet_util_lib.h"
  40
  41 /**
  42  * Version number of GNUnet-core API.
  43  */
  44 #define GNUNET_CORE_VERSION 0x00000000
  45
  46
  47 /**
  48  * Opaque handle to the service.
  49  */
  50 struct GNUNET_CORE_Handle;
  51
  52
  53 /**
  54  * Method called whenever a given peer either connects or
  55  * disconnects (or list of connections was requested).
  56  *
  57  * @param cls closure
  58  * @param peer peer identity this notification is about
  59  * @param bpm how much bandwidth is available
  60  *            (for sending) to this peer
  61  * @param last_activity when did we last
  62  *            receive anything from this peer?
  63  */
  64 typedef void (*GNUNET_CORE_ClientEventHandler) (void *cls,
  65                                                 const struct
  66                                                 GNUNET_PeerIdentity * peer,
  67                                                 unsigned int bpm,
  68                                                 struct GNUNET_TIME_Absolute
  69                                                 last_activity);
  70
  71
  72 /**
  73  * Type of a send callback to fill up buffers.
  74  *
  75  * @param receiver the receiver of the message
  76  * @param position is the reference to the
  77  *        first unused position in the buffer where GNUnet is building
  78  *        the message
  79  * @param padding is the number of bytes left in that buffer.
  80  * @return the number of bytes written to
  81  *   that buffer (must be a positive number).
  82  */
  83 typedef unsigned int
  84   (*GNUNET_CORE_BufferFillCallback) (void *cls,
  85                                      const struct GNUNET_PeerIdentity *
  86                                      receiver,
  87                                      void *position, unsigned int padding);
  88
  89
  90 /**
  91  * Functions with this signature are called whenever a message is
  92  * received or transmitted.
  93  *
  94  * @param cls closure
  95  * @param peer the other peer involved (sender or receiver, NULL
  96  *        for loopback messages where we are both sender and receiver)
  97  * @param message the actual message
  98  * @return GNUNET_OK to keep the connection open,
  99  *         GNUNET_SYSERR to close it (signal serious error)
 100  */
 101 typedef int
 102   (*GNUNET_CORE_MessageCallback) (void *cls,
 103                                   const struct GNUNET_PeerIdentity * other,
 104                                   const struct GNUNET_MessageHeader *
 105                                   message);
 106
 107
 108 /**
 109  * Message handler.  Each struct specifies how to handle on particular
 110  * type of message received.
 111  */
 112 struct GNUNET_CORE_MessageHandler
 113 {
 114   /**
 115    * Function to call for messages of "type".
 116    */
 117   GNUNET_CORE_MessageCallback callback;
 118
 119   /**
 120    * Type of the message this handler covers.
 121    */
 122   uint16_t type;
 123
 124   /**
 125    * Expected size of messages of this type.  Use 0 for variable-size.
 126    * If non-zero, messages of the given type will be discarded if they
 127    * do not have the right size.
 128    */
 129   uint16_t expected_size;
 130
 131 };
 132
 133
 134 /**
 135  * Function called after GNUNET_CORE_connect has succeeded
 136  * (or failed for good).  Note that the private key of the
 137  * peer is intentionally not exposed here; if you need it,
 138  * your process should try to read the private key file
 139  * directly (which should work if you are authorized...).
 140  *
 141  * @param cls closure
 142  * @param server handle to the server, NULL if we failed
 143  * @param my_identity ID of this peer, NULL if we failed
 144  * @param publicKey public key of this peer, NULL if we failed
 145  */
 146 typedef void
 147   (*GNUNET_CORE_StartupCallback) (void *cls,
 148                                   struct GNUNET_CORE_Handle * server,
 149                                   const struct GNUNET_PeerIdentity *
 150                                   my_identity,
 151                                   const struct
 152                                   GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *
 153                                   publicKey);
 154
 155
 156 /**
 157  * Connect to the core service.  Note that the connection may
 158  * complete (or fail) asynchronously.
 159  *
 160  * @param sched scheduler to use
 161  * @param cfg configuration to use
 162  * @param timeout after how long should we give up trying to connect to the core service?
 163  * @param cls closure for the various callbacks that follow (including handlers in the handlers array)
 164  * @param init callback to call on timeout or once we have successfully
 165  *        connected to the core service
 166  * @param connects function to call on peer connect, can be NULL
 167  * @param disconnects function to call on peer disconnect / timeout, can be NULL
 168  * @param bfc function to call to fill up spare bandwidth, can be NULL
 169  * @param inbound_notify function to call for all inbound messages, can be NULL
 170  * @param inbound_hdr_only set to GNUNET_YES if inbound_notify will only read the
 171  *                GNUNET_MessageHeader and hence we do not need to give it the full message;
 172  *                can be used to improve efficiency, ignored if inbound_notify is NULLL
 173  * @param outbound_notify function to call for all outbound messages, can be NULL
 174  * @param outbound_hdr_only set to GNUNET_YES if outbound_notify will only read the
 175  *                GNUNET_MessageHeader and hence we do not need to give it the full message
 176  *                can be used to improve efficiency, ignored if outbound_notify is NULLL
 177  * @param handlers callbacks for messages we care about, NULL-terminated
 178  */
 179 void
 180 GNUNET_CORE_connect (struct GNUNET_SCHEDULER_Handle *sched,
 181                      struct GNUNET_CONFIGURATION_Handle *cfg,
 182                      struct GNUNET_TIME_Relative timeout,
 183                      void *cls,
 184                      GNUNET_CORE_StartupCallback init,
 185                      GNUNET_CORE_ClientEventHandler connects,
 186                      GNUNET_CORE_ClientEventHandler disconnects,
 187                      GNUNET_CORE_BufferFillCallback bfc,
 188                      GNUNET_CORE_MessageCallback inbound_notify,
 189                      int inbound_hdr_only,
 190                      GNUNET_CORE_MessageCallback outbound_notify,
 191                      int outbound_hdr_only,
 192                      const struct GNUNET_CORE_MessageHandler *handlers);
 193
 194
 195 /**
 196  * Disconnect from the core service.
 197  *
 198  * @param handle connection to core to disconnect
 199  */
 200 void GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
 201
 202
 203 /**
 204  * Function called with statistics about the given peer.
 205  *
 206  * @param peer identifies the peer
 207  * @param latency current latency estimate, "FOREVER" if we have been
 208  *                disconnected
 209  * @param bpm_in set to the current bandwidth limit (receiving) for this peer
 210  * @param bpm_out set to the current bandwidth limit (sending) for this peer
 211  * @param amount set to the amount that was actually reserved or unreserved
 212  * @param preference current traffic preference for the given peer
 213  */
 214 typedef void
 215   (*GNUNET_CORE_PeerConfigurationInfoCallback) (void *cls,
 216                                                 const struct
 217                                                 GNUNET_PeerIdentity * peer,
 218                                                 unsigned int bpm_in,
 219                                                 unsigned int bpm_out,
 220                                                 struct GNUNET_TIME_Relative
 221                                                 latency, int amount,
 222                                                 double preference);
 223
 224
 225 /**
 226  * Obtain statistics and/or change preferences for the given peer.
 227  *
 228  * @param handle connection to core to use
 229  * @param peer identifies the peer
 230  * @param timeout after how long should we give up (and call "info" with NULL
 231  *                for "peer" to signal an error)?
 232  * @param bpm_out set to the current bandwidth limit (sending) for this peer,
 233  *                caller should set "bpm_out" to "-1" to avoid changing
 234  *                the current value; otherwise "bpm_out" will be lowered to
 235  *                the specified value; passing a pointer to "0" can be used to force
 236  *                us to disconnect from the peer; "bpm_out" might not increase
 237  *                as specified since the upper bound is generally
 238  *                determined by the other peer!
 239  * @param amount reserve N bytes for receiving, negative
 240  *                amounts can be used to undo a (recent) reservation;
 241  * @param preference increase incoming traffic share preference by this amount;
 242  *                in the absence of "amount" reservations, we use this
 243  *                preference value to assign proportional bandwidth shares
 244  *                to all connected peers
 245  * @param info function to call with the resulting configuration information
 246  * @param info_cls closure for info
 247  */
 248 void
 249 GNUNET_CORE_peer_configure (struct GNUNET_CORE_Handle *handle,
 250                             const struct GNUNET_PeerIdentity *peer,
 251                             struct GNUNET_TIME_Relative timeout,
 252                             unsigned int bpm_out,
 253                             int amount,
 254                             double preference,
 255                             GNUNET_CORE_PeerConfigurationInfoCallback info,
 256                             void *info_cls);
 257
 258
 259 /**
 260  * Handle for a transmission request.
 261  */
 262 struct GNUNET_CORE_TransmitHandle;
 263
 264
 265 /**
 266  * Ask the core to call "notify" once it is ready to transmit the
 267  * given number of bytes to the specified "target".  If we are not yet
 268  * connected to the specified peer, a call to this function will cause
 269  * us to try to establish a connection.
 270  *
 271  * @param handle connection to core service
 272  * @param priority how important is the message?
 273  * @param maxdelay how long can the message wait?
 274  * @param target who should receive the message,
 275  *        use NULL for this peer (loopback)
 276  * @param notify_size how many bytes of buffer space does notify want?
 277  * @param notify function to call when buffer space is available
 278  * @param notify_cls closure for notify
 279  * @return non-NULL if the notify callback was queued,
 280  *         NULL if we can not even queue the request (insufficient
 281  *         memory); if NULL is returned, "notify" will NOT be called.
 282  */
 283 struct GNUNET_CORE_TransmitHandle *GNUNET_CORE_notify_transmit_ready (struct
 284                                                                       GNUNET_CORE_Handle
 285                                                                       *handle,
 286                                                                       unsigned
 287                                                                       int
 288                                                                       priority,
 289                                                                       struct
 290                                                                       GNUNET_TIME_Relative
 291                                                                       maxdelay,
 292                                                                       const
 293                                                                       struct
 294                                                                       GNUNET_PeerIdentity
 295                                                                       *target,
 296                                                                       size_t
 297                                                                       notify_size,
 298                                                                       GNUNET_NETWORK_TransmitReadyNotify
 299                                                                       notify,
 300                                                                       void
 301                                                                       *notify_cls);
 302
 303
 304 /**
 305  * Cancel the specified transmission-ready notification.
 306  *
 307  * @param h handle that was returned by "notify_transmit_ready".
 308  */
 309 void
 310 GNUNET_CORE_notify_transmit_ready_cancel (struct GNUNET_CORE_TransmitHandle
 311                                           *h);
 312
 313
 314 #if 0                           /* keep Emacsens' auto-indent happy */
 315 {
 316 #endif
 317 #ifdef __cplusplus
 318 }
 319 #endif
 320
 321 /* ifndef GNUNET_CORE_SERVICE_H */
 322 #endif
 323 /* end of gnunet_core_service.h */