src/include/gnunet_core_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009-2013 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 include/gnunet_core_service.h
  23  * @brief core service; this is the main API for encrypted P2P
  24  *        communications
  25  * @author Christian Grothoff
  26  * @defgroup core encrypted direct communication between peers
  27  * @{
  28  */
  29
  30 #ifndef GNUNET_CORE_SERVICE_H
  31 #define GNUNET_CORE_SERVICE_H
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41 #include "gnunet_util_lib.h"
  42 #include "gnunet_transport_service.h"
  43
  44 /**
  45  * Version number of GNUnet-core API.
  46  */
  47 #define GNUNET_CORE_VERSION 0x00000001
  48
  49 /**
  50  * Traffic priorities.
  51  */
  52 enum GNUNET_CORE_Priority
  53 {
  54
  55   /**
  56    * Lowest priority, i.e. background traffic (i.e. fs)
  57    */
  58   GNUNET_CORE_PRIO_BACKGROUND = 0,
  59
  60   /**
  61    * Normal traffic (i.e. mesh/dv relay, DHT)
  62    */
  63   GNUNET_CORE_PRIO_BEST_EFFORT = 1,
  64
  65   /**
  66    * Urgent traffic (local peer, i.e. conversation).
  67    */
  68   GNUNET_CORE_PRIO_URGENT = 2,
  69
  70   /**
  71    * Highest priority, control traffic (i.e. NSE, Core/Mesh KX).
  72    */
  73   GNUNET_CORE_PRIO_CRITICAL_CONTROL = 3
  74
  75
  76 };
  77
  78
  79 /**
  80  * Opaque handle to the service.
  81  */
  82 struct GNUNET_CORE_Handle;
  83
  84
  85 /**
  86  * Method called whenever a given peer connects.
  87  *
  88  * @param cls closure
  89  * @param peer peer identity this notification is about
  90  */
  91 typedef void
  92 (*GNUNET_CORE_ConnectEventHandler) (void *cls,
  93                                     const struct GNUNET_PeerIdentity *peer);
  94
  95
  96 /**
  97  * Method called whenever a peer disconnects.
  98  *
  99  * @param cls closure
 100  * @param peer peer identity this notification is about
 101  */
 102 typedef void
 103 (*GNUNET_CORE_DisconnectEventHandler) (void *cls,
 104                                        const struct GNUNET_PeerIdentity *peer);
 105
 106
 107 /**
 108  * Functions with this signature are called whenever a message is
 109  * received or transmitted.
 110  *
 111  * @param cls closure (set from #GNUNET_CORE_connect)
 112  * @param peer the other peer involved (sender or receiver, NULL
 113  *        for loopback messages where we are both sender and receiver)
 114  * @param message the actual message
 115  * @return #GNUNET_OK to keep the connection open,
 116  *         #GNUNET_SYSERR to close connection to the peer (signal serious error)
 117  */
 118 typedef int
 119 (*GNUNET_CORE_MessageCallback) (void *cls,
 120                                 const struct GNUNET_PeerIdentity *other,
 121                                 const struct GNUNET_MessageHeader *message);
 122
 123
 124 /**
 125  * Message handler.  Each struct specifies how to handle on particular
 126  * type of message received.
 127  */
 128 struct GNUNET_CORE_MessageHandler
 129 {
 130   /**
 131    * Function to call for messages of @e type.
 132    */
 133   GNUNET_CORE_MessageCallback callback;
 134
 135   /**
 136    * Type of the message this handler covers.
 137    */
 138   uint16_t type;
 139
 140   /**
 141    * Expected size of messages of this type.  Use 0 for variable-size.
 142    * If non-zero, messages of the given type will be discarded if they
 143    * do not have the right size.
 144    */
 145   uint16_t expected_size;
 146
 147 };
 148
 149
 150 /**
 151  * Function called after #GNUNET_CORE_connect has succeeded (or failed
 152  * for good).  Note that the private key of the peer is intentionally
 153  * not exposed here; if you need it, your process should try to read
 154  * the private key file directly (which should work if you are
 155  * authorized...).  Implementations of this function must not call
 156  * #GNUNET_CORE_disconnect (other than by scheduling a new task to
 157  * do this later).
 158  *
 159  * @param cls closure
 160  * @param my_identity ID of this peer, NULL if we failed
 161  */
 162 typedef void
 163 (*GNUNET_CORE_StartupCallback) (void *cls,
 164                                 const struct GNUNET_PeerIdentity *my_identity);
 165
 166
 167 /**
 168  * Connect to the core service.  Note that the connection may complete
 169  * (or fail) asynchronously.  This function primarily causes the given
 170  * callback notification functions to be invoked whenever the
 171  * specified event happens.  The maximum number of queued
 172  * notifications (queue length) is per client; the queue is shared
 173  * across all types of notifications.  So a slow client that registers
 174  * for @a outbound_notify also risks missing @a inbound_notify messages.
 175  * Certain events (such as connect/disconnect notifications) are not
 176  * subject to queue size limitations.
 177  *
 178  * @param cfg configuration to use
 179  * @param cls closure for the various callbacks that follow (including handlers in the handlers array)
 180  * @param init callback to call once we have successfully
 181  *        connected to the core service
 182  * @param connects function to call on peer connect, can be NULL
 183  * @param disconnects function to call on peer disconnect / timeout, can be NULL
 184  * @param inbound_notify function to call for all inbound messages, can be NULL
 185  *                note that the core is allowed to drop notifications about inbound
 186  *                messages if the client does not process them fast enough (for this
 187  *                notification type, a bounded queue is used)
 188  * @param inbound_hdr_only set to #GNUNET_YES if @a inbound_notify will only read the
 189  *                `struct GNUNET_MessageHeader` and hence we do not need to give it the full message;
 190  *                can be used to improve efficiency, ignored if inbound_notify is NULL
 191  *                note that the core is allowed to drop notifications about inbound
 192  *                messages if the client does not process them fast enough (for this
 193  *                notification type, a bounded queue is used)
 194  * @param outbound_notify function to call for all outbound messages, can be NULL;
 195  *                note that the core is allowed to drop notifications about outbound
 196  *                messages if the client does not process them fast enough (for this
 197  *                notification type, a bounded queue is used)
 198  * @param outbound_hdr_only set to #GNUNET_YES if @a outbound_notify will only read the
 199  *                `struct GNUNET_MessageHeader` and hence we do not need to give it the full message
 200  *                can be used to improve efficiency, ignored if outbound_notify is NULL
 201  *                note that the core is allowed to drop notifications about outbound
 202  *                messages if the client does not process them fast enough (for this
 203  *                notification type, a bounded queue is used)
 204  * @param handlers callbacks for messages we care about, NULL-terminated
 205  *                note that the core is allowed to drop notifications about inbound
 206  *                messages if the client does not process them fast enough (for this
 207  *                notification type, a bounded queue is used)
 208  * @return handle to the core service (only useful for disconnect until @a init is called),
 209  *           NULL on error (in this case, init is never called)
 210  */
 211 struct GNUNET_CORE_Handle *
 212 GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 213                      void *cls,
 214                      GNUNET_CORE_StartupCallback init,
 215                      GNUNET_CORE_ConnectEventHandler connects,
 216                      GNUNET_CORE_DisconnectEventHandler disconnects,
 217                      GNUNET_CORE_MessageCallback inbound_notify,
 218                      int inbound_hdr_only,
 219                      GNUNET_CORE_MessageCallback outbound_notify,
 220                      int outbound_hdr_only,
 221                      const struct GNUNET_CORE_MessageHandler *handlers);
 222
 223
 224 /**
 225  * Disconnect from the core service.    This function can only
 226  * be called *after* all pending #GNUNET_CORE_notify_transmit_ready
 227  * requests have been explicitly cancelled.
 228  *
 229  * @param handle connection to core to disconnect
 230  */
 231 void
 232 GNUNET_CORE_disconnect (struct GNUNET_CORE_Handle *handle);
 233
 234
 235 /**
 236  * Handle for a transmission request.
 237  */
 238 struct GNUNET_CORE_TransmitHandle;
 239
 240
 241 /**
 242  * Ask the core to call @a notify once it is ready to transmit the
 243  * given number of bytes to the specified @a target.  Must only be
 244  * called after a connection to the respective peer has been
 245  * established (and the client has been informed about this).  You may
 246  * have one request of this type pending for each connected peer at
 247  * any time.  If a peer disconnects, the application MUST call
 248  * #GNUNET_CORE_notify_transmit_ready_cancel on the respective
 249  * transmission request, if one such request is pending.
 250  *
 251  * @param handle connection to core service
 252  * @param cork is corking allowed for this transmission?
 253  * @param priority how important is the message?
 254  * @param maxdelay how long can the message wait? Only effective if @a cork is #GNUNET_YES
 255  * @param target who should receive the message, never NULL (can be this peer's identity for loopback)
 256  * @param notify_size how many bytes of buffer space does notify want?
 257  * @param notify function to call when buffer space is available;
 258  *        will be called with NULL on timeout; clients MUST cancel
 259  *        all pending transmission requests DURING the disconnect
 260  *        handler
 261  * @param notify_cls closure for @a notify
 262  * @return non-NULL if the notify callback was queued,
 263  *         NULL if we can not even queue the request (request already pending);
 264  *         if NULL is returned, "notify" will NOT be called.
 265  */
 266 struct GNUNET_CORE_TransmitHandle *
 267 GNUNET_CORE_notify_transmit_ready (struct GNUNET_CORE_Handle *handle,
 268                                    int cork,
 269                                    enum GNUNET_CORE_Priority priority,
 270                                    struct GNUNET_TIME_Relative maxdelay,
 271                                    const struct GNUNET_PeerIdentity *target,
 272                                    size_t notify_size,
 273                                    GNUNET_CONNECTION_TransmitReadyNotify notify,
 274                                    void *notify_cls);
 275
 276
 277 /**
 278  * Cancel the specified transmission-ready notification.
 279  *
 280  * @param th handle that was returned by "notify_transmit_ready".
 281  */
 282 void
 283 GNUNET_CORE_notify_transmit_ready_cancel (struct GNUNET_CORE_TransmitHandle
 284                                           *th);
 285
 286
 287 /**
 288  * Iterate over all connected peers.  Calls @a peer_cb with each
 289  * connected peer, and then once with NULL to indicate that all peers
 290  * have been handled.  Normal users of the CORE API are not expected
 291  * to use this function.  It is different in that it truly lists
 292  * all connections, not just those relevant to the application.  This
 293  * function is used by special applications for diagnostics.  This
 294  * function is NOT part of the 'versioned', 'official' API.
 295  *
 296  * FIXME: we should probably make it possible to 'cancel' the
 297  * operation...
 298  *
 299  * @param cfg configuration handle
 300  * @param peer_cb function to call with the peer information
 301  * @param cb_cls closure for @a peer_cb
 302  * @return #GNUNET_OK on success, #GNUNET_SYSERR on errors
 303  */
 304 int
 305 GNUNET_CORE_iterate_peers (const struct GNUNET_CONFIGURATION_Handle *cfg,
 306                            GNUNET_CORE_ConnectEventHandler peer_cb,
 307                            void *cb_cls);
 308
 309
 310 /**
 311  * Check if the given peer is currently connected. This function is for special
 312  * cirumstances (GNUNET_TESTBED uses it), normal users of the CORE API are
 313  * expected to track which peers are connected based on the connect/disconnect
 314  * callbacks from #GNUNET_CORE_connect.  This function is NOT part of the
 315  * 'versioned', 'official' API.  This function returns
 316  * synchronously after looking in the CORE API cache.
 317  *
 318  * @param h the core handle
 319  * @param pid the identity of the peer to check if it has been connected to us
 320  * @return #GNUNET_YES if the peer is connected to us; #GNUNET_NO if not
 321  */
 322 int
 323 GNUNET_CORE_is_peer_connected_sync (const struct GNUNET_CORE_Handle *h,
 324                                     const struct GNUNET_PeerIdentity *pid);
 325
 326
 327 /**
 328  * Create a message queue for sending messages to a peer with CORE.
 329  * Messages may only be queued with #GNUNET_MQ_send once the init callback has
 330  * been called for the given handle.
 331  * There must only be one queue per peer for each core handle.
 332  * The message queue can only be used to transmit messages,
 333  * not to receive them.
 334  *
 335  * @param h the core handle
 336  * @param target the target peer for this queue, may not be NULL
 337  * @return a message queue for sending messages over the core handle
 338  *         to the target peer
 339  */
 340 struct GNUNET_MQ_Handle *
 341 GNUNET_CORE_mq_create (struct GNUNET_CORE_Handle *h,
 342                        const struct GNUNET_PeerIdentity *target);
 343
 344
 345 #if 0                           /* keep Emacsens' auto-indent happy */
 346 {
 347 #endif
 348 #ifdef __cplusplus
 349 }
 350 #endif
 351
 352 /** @} */ /* end of group core */
 353
 354 /* ifndef GNUNET_CORE_SERVICE_H */
 355 #endif
 356 /* end of gnunet_core_service.h */