src/include/gnunet_cadet_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2014 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  * @file include/gnunet_cadet_service.h
  22  * @brief cadet service; establish channels to distant peers
  23  * @author Christian Grothoff
  24  * @author Bart Polot
  25  */
  26 #ifndef GNUNET_CADET_SERVICE_H
  27 #define GNUNET_CADET_SERVICE_H
  28
  29 #ifdef __cplusplus
  30 extern "C"
  31 {
  32 #if 0                           /* keep Emacsens' auto-indent happy */
  33 }
  34 #endif
  35 #endif
  36
  37 #include "gnunet_util_lib.h"
  38 #include "gnunet_transport_service.h"
  39
  40 /**
  41  * Version number of GNUnet-cadet API.
  42  */
  43 #define GNUNET_CADET_VERSION 0x00000003
  44
  45
  46 /**
  47  * Opaque handle to the service.
  48  */
  49 struct GNUNET_CADET_Handle;
  50
  51 /**
  52  * Opaque handle to a channel.
  53  */
  54 struct GNUNET_CADET_Channel;
  55
  56 /**
  57  * Hash to be used in Cadet communication. Only 256 bits needed,
  58  * instead of the 512 from `struct GNUNET_HashCode`.
  59  */
  60 struct GNUNET_CADET_Hash
  61 {
  62   unsigned char bits[256 / 8];
  63 };
  64
  65
  66 /**
  67  * Channel options.  Second line indicates filed in the
  68  * CadetChannelInfo union carrying the answer.
  69  */
  70 enum GNUNET_CADET_ChannelOption
  71 {
  72   /**
  73    * Default options: unreliable, default buffering, not out of order.
  74    */
  75   GNUNET_CADET_OPTION_DEFAULT    = 0x0,
  76
  77   /**
  78    * Disable buffering on intermediate nodes (for minimum latency).
  79    * Yes/No.
  80    */
  81   GNUNET_CADET_OPTION_NOBUFFER   = 0x1,
  82
  83   /**
  84    * Enable channel reliability, lost messages will be retransmitted.
  85    * Yes/No.
  86    */
  87   GNUNET_CADET_OPTION_RELIABLE   = 0x2,
  88
  89   /**
  90    * Enable out of order delivery of messages.
  91    * Yes/No.
  92    */
  93   GNUNET_CADET_OPTION_OOORDER    = 0x4,
  94
  95   /**
  96    * Who is the peer at the other end of the channel.
  97    * Only for use in @c GNUNET_CADET_channel_get_info
  98    * struct GNUNET_PeerIdentity *peer
  99    */
 100   GNUNET_CADET_OPTION_PEER       = 0x8
 101
 102 };
 103
 104
 105 /**
 106  * Functions with this signature are called whenever a message is
 107  * received.
 108  *
 109  * Each time the function must call #GNUNET_CADET_receive_done on the channel
 110  * in order to receive the next message. This doesn't need to be immediate:
 111  * can be delayed if some processing is done on the message.
 112  *
 113  * @param cls Closure (set from #GNUNET_CADET_connect).
 114  * @param channel Connection to the other end.
 115  * @param channel_ctx Place to store local state associated with the channel.
 116  * @param message The actual message.
 117  * @return #GNUNET_OK to keep the channel open,
 118  *         #GNUNET_SYSERR to close it (signal serious error).
 119  */
 120 typedef int
 121 (*GNUNET_CADET_MessageCallback) (void *cls,
 122                                  struct GNUNET_CADET_Channel *channel,
 123                                  void **channel_ctx,
 124                                  const struct GNUNET_MessageHeader *message);
 125
 126
 127 /**
 128  * Message handler.  Each struct specifies how to handle on particular
 129  * type of message received.
 130  */
 131 struct GNUNET_CADET_MessageHandler
 132 {
 133   /**
 134    * Function to call for messages of type @e type.
 135    */
 136   GNUNET_CADET_MessageCallback callback;
 137
 138   /**
 139    * Type of the message this handler covers.
 140    */
 141   uint16_t type;
 142
 143   /**
 144    * Expected size of messages of this type.  Use 0 for variable-size.
 145    * If non-zero, messages of the given type will be discarded if they
 146    * do not have the right size.
 147    */
 148   uint16_t expected_size;
 149 };
 150
 151
 152 /**
 153  * Method called whenever another peer has added us to a channel
 154  * the other peer initiated.
 155  * Only called (once) upon reception of data with a message type which was
 156  * subscribed to in #GNUNET_CADET_connect.
 157  *
 158  * A call to #GNUNET_CADET_channel_destroy causes te channel to be ignored. In
 159  * this case the handler MUST return NULL.
 160  *
 161  * @param cls closure
 162  * @param channel new handle to the channel
 163  * @param initiator peer that started the channel
 164  * @param port Port this channel is for.
 165  * @param options CadetOption flag field, with all active option bits set to 1.
 166  *
 167  * @return initial channel context for the channel
 168  *         (can be NULL -- that's not an error)
 169  */
 170 typedef void *
 171 (GNUNET_CADET_InboundChannelNotificationHandler) (void *cls,
 172                                                   struct GNUNET_CADET_Channel *channel,
 173                                                   const struct GNUNET_PeerIdentity *initiator,
 174                                                   uint32_t port,
 175                                                   enum GNUNET_CADET_ChannelOption options);
 176
 177
 178 /**
 179  * Function called whenever a channel is destroyed.  Should clean up
 180  * any associated state, including cancelling any pending transmission on this
 181  * channel.
 182  *
 183  * It must NOT call #GNUNET_CADET_channel_destroy on the channel.
 184  *
 185  * @param cls closure (set from #GNUNET_CADET_connect)
 186  * @param channel connection to the other end (henceforth invalid)
 187  * @param channel_ctx place where local state associated
 188  *                   with the channel is stored
 189  */
 190 typedef void
 191 (GNUNET_CADET_ChannelEndHandler) (void *cls,
 192                                   const struct GNUNET_CADET_Channel *channel,
 193                                   void *channel_ctx);
 194
 195
 196 /**
 197  * Connect to the cadet service.
 198  *
 199  * @param cfg Configuration to use.
 200  * @param cls Closure for the various callbacks that follow (including
 201  *            handlers in the handlers array).
 202  * @param new_channel Function called when an *incoming* channel is created.
 203  *                    Can be NULL if no inbound channels are desired.
 204  *                    See @a ports.
 205  * @param cleaner Function called when a channel is destroyed.
 206  *                It is called immediately if #GNUNET_CADET_channel_destroy
 207  *                is called on the channel.
 208  * @param handlers Callbacks for messages we care about, NULL-terminated. Each
 209  *                 one must call #GNUNET_CADET_receive_done on the channel to
 210  *                 receive the next message.  Messages of a type that is not
 211  *                 in the handlers array are ignored if received.
 212  * @param ports NULL or 0-terminated array of port numbers for incoming channels.
 213  *              See @a new_channel.
 214  *
 215  * @return handle to the cadet service NULL on error
 216  *         (in this case, init is never called)
 217  */
 218 struct GNUNET_CADET_Handle *
 219 GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 220                       void *cls,
 221                       GNUNET_CADET_InboundChannelNotificationHandler new_channel,
 222                       GNUNET_CADET_ChannelEndHandler cleaner,
 223                       const struct GNUNET_CADET_MessageHandler *handlers,
 224                       const uint32_t *ports);
 225
 226
 227 /**
 228  * Disconnect from the cadet service. All channels will be destroyed. All channel
 229  * disconnect callbacks will be called on any still connected peers, notifying
 230  * about their disconnection. The registered inbound channel cleaner will be
 231  * called should any inbound channels still exist.
 232  *
 233  * @param handle connection to cadet to disconnect
 234  */
 235 void
 236 GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle);
 237
 238
 239 /**
 240  * Create a new channel towards a remote peer.
 241  *
 242  * If the destination port is not open by any peer or the destination peer
 243  * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called
 244  * for this channel.
 245  *
 246  * @param h cadet handle
 247  * @param channel_ctx client's channel context to associate with the channel
 248  * @param peer peer identity the channel should go to
 249  * @param port Port number.
 250  * @param options CadetOption flag field, with all desired option bits set to 1.
 251  *
 252  * @return handle to the channel
 253  */
 254 struct GNUNET_CADET_Channel *
 255 GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h,
 256                              void *channel_ctx,
 257                              const struct GNUNET_PeerIdentity *peer,
 258                              uint32_t port,
 259                              enum GNUNET_CADET_ChannelOption options);
 260
 261
 262 /**
 263  * Destroy an existing channel.
 264  *
 265  * The existing end callback for the channel will be called immediately.
 266  * Any pending outgoing messages will be sent but no incoming messages will be
 267  * accepted and no data callbacks will be called.
 268  *
 269  * @param channel Channel handle, becomes invalid after this call.
 270  */
 271 void
 272 GNUNET_CADET_channel_destroy (struct GNUNET_CADET_Channel *channel);
 273
 274
 275 /**
 276  * Struct to retrieve info about a channel.
 277  */
 278 union GNUNET_CADET_ChannelInfo
 279 {
 280
 281   /**
 282    * #GNUNET_YES / #GNUNET_NO, for binary flags.
 283    */
 284   int yes_no;
 285
 286   /**
 287    * Peer on the other side of the channel
 288    */
 289   const struct GNUNET_PeerIdentity peer;
 290 };
 291
 292
 293 /**
 294  * Get information about a channel.
 295  *
 296  * @param channel Channel handle.
 297  * @param option Query type GNUNET_CADET_OPTION_*
 298  * @param ... dependant on option, currently not used
 299  * @return Union with an answer to the query.
 300  */
 301 const union GNUNET_CADET_ChannelInfo *
 302 GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel,
 303                               enum GNUNET_CADET_ChannelOption option, ...);
 304
 305
 306 /**
 307  * Handle for a transmission request.
 308  */
 309 struct GNUNET_CADET_TransmitHandle;
 310
 311
 312 /**
 313  * Ask the cadet to call @a notify once it is ready to transmit the
 314  * given number of bytes to the specified channel.
 315  * Only one call can be active at any time, to issue another request,
 316  * wait for the callback or cancel the current request.
 317  *
 318  * @param channel channel to use for transmission
 319  * @param cork is corking allowed for this transmission?
 320  * @param maxdelay how long can the message wait?
 321  * @param notify_size how many bytes of buffer space does notify want?
 322  * @param notify function to call when buffer space is available;
 323  *        will be called with NULL on timeout or if the overall queue
 324  *        for this peer is larger than queue_size and this is currently
 325  *        the message with the lowest priority
 326  * @param notify_cls closure for @a notify
 327  * @return non-NULL if the notify callback was queued,
 328  *         NULL if we can not even queue the request (insufficient
 329  *         memory); if NULL is returned, @a notify will NOT be called.
 330  */
 331 struct GNUNET_CADET_TransmitHandle *
 332 GNUNET_CADET_notify_transmit_ready (struct GNUNET_CADET_Channel *channel,
 333                                    int cork,
 334                                    struct GNUNET_TIME_Relative maxdelay,
 335                                    size_t notify_size,
 336                                    GNUNET_CONNECTION_TransmitReadyNotify notify,
 337                                    void *notify_cls);
 338
 339
 340 /**
 341  * Cancel the specified transmission-ready notification.
 342  *
 343  * @param th handle that was returned by "notify_transmit_ready".
 344  */
 345 void
 346 GNUNET_CADET_notify_transmit_ready_cancel (struct GNUNET_CADET_TransmitHandle *th);
 347
 348
 349 /**
 350  * Indicate readiness to receive the next message on a channel.
 351  *
 352  * Should only be called once per handler called.
 353  *
 354  * @param channel Channel that will be allowed to call another handler.
 355  */
 356 void
 357 GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel);
 358
 359
 360
 361 /******************************************************************************/
 362 /********************       MONITORING /DEBUG API     *************************/
 363 /******************************************************************************/
 364 /* The following calls are not useful for normal CADET operation, but for      */
 365 /* debug and monitoring of the cadet state. They can be safely ignored.        */
 366 /* The API can change at any point without notice.                            */
 367 /* Please contact the developer if you consider any of this calls useful for  */
 368 /* normal cadet applications.                                                  */
 369 /******************************************************************************/
 370
 371
 372 /**
 373  * Method called to retrieve information about a specific channel the cadet peer
 374  * is aware of, including all transit nodes.
 375  *
 376  * @param cls Closure.
 377  * @param root Root of the channel.
 378  * @param dest Destination of the channel.
 379  * @param port Destination port of the channel.
 380  * @param root_channel_number Local number for root, if known.
 381  * @param dest_channel_number Local number for dest, if known.
 382  * @param public_channel_numbe Number for P2P, always known.
 383  */
 384 typedef void
 385 (*GNUNET_CADET_ChannelCB) (void *cls,
 386                            const struct GNUNET_PeerIdentity *root,
 387                            const struct GNUNET_PeerIdentity *dest,
 388                            uint32_t port,
 389                            uint32_t root_channel_number,
 390                            uint32_t dest_channel_number,
 391                            uint32_t public_channel_number);
 392
 393 /**
 394  * Method called to retrieve information about all peers in CADET, called
 395  * once per peer.
 396  *
 397  * After last peer has been reported, an additional call with NULL is done.
 398  *
 399  * @param cls Closure.
 400  * @param peer Peer, or NULL on "EOF".
 401  * @param tunnel Do we have a tunnel towards this peer?
 402  * @param n_paths Number of known paths towards this peer.
 403  * @param best_path How long is the best path?
 404  *                  (0 = unknown, 1 = ourselves, 2 = neighbor)
 405  */
 406 typedef void
 407 (*GNUNET_CADET_PeersCB) (void *cls,
 408                          const struct GNUNET_PeerIdentity *peer,
 409                          int tunnel,
 410                          unsigned int n_paths,
 411                          unsigned int best_path);
 412
 413 /**
 414  * Method called to retrieve information about a specific peer
 415  * known to the service.
 416  *
 417  * @param cls Closure.
 418  * @param peer Peer ID.
 419  * @param tunnel Do we have a tunnel towards this peer? #GNUNET_YES/#GNUNET_NO
 420  * @param neighbor Is this a direct neighbor? #GNUNET_YES/#GNUNET_NO
 421  * @param n_paths Number of paths known towards peer.
 422  * @param paths Array of PEER_IDs representing all paths to reach the peer.
 423  *              Each path starts with the local peer.
 424  *              Each path ends with the destination peer (given in @c peer).
 425  */
 426 typedef void
 427 (*GNUNET_CADET_PeerCB) (void *cls,
 428                         const struct GNUNET_PeerIdentity *peer,
 429                         int tunnel,
 430                         int neighbor,
 431                         unsigned int n_paths,
 432                         struct GNUNET_PeerIdentity *paths);
 433
 434
 435 /**
 436  * Method called to retrieve information about all tunnels in CADET, called
 437  * once per tunnel.
 438  *
 439  * After last tunnel has been reported, an additional call with NULL is done.
 440  *
 441  * @param cls Closure.
 442  * @param peer Destination peer, or NULL on "EOF".
 443  * @param channels Number of channels.
 444  * @param connections Number of connections.
 445  * @param estate Encryption state.
 446  * @param cstate Connectivity state.
 447  */
 448 typedef void
 449 (*GNUNET_CADET_TunnelsCB) (void *cls,
 450                            const struct GNUNET_PeerIdentity *peer,
 451                            unsigned int channels,
 452                            unsigned int connections,
 453                            uint16_t estate,
 454                            uint16_t cstate);
 455
 456
 457 /**
 458  * Method called to retrieve information about a specific tunnel the cadet peer
 459  * has established, o`r is trying to establish.
 460  *
 461  * @param cls Closure.
 462  * @param peer Peer towards whom the tunnel is directed.
 463  * @param n_channels Number of channels.
 464  * @param n_connections Number of connections.
 465  * @param channels Channels.
 466  * @param connections Connections.
 467  * @param estate Encryption state.
 468  * @param cstate Connectivity state.
 469  */
 470 typedef void
 471 (*GNUNET_CADET_TunnelCB) (void *cls,
 472                           const struct GNUNET_PeerIdentity *peer,
 473                           unsigned int n_channels,
 474                           unsigned int n_connections,
 475                           uint32_t *channels,
 476                           struct GNUNET_CADET_Hash *connections,
 477                           unsigned int estate,
 478                           unsigned int cstate);
 479
 480
 481 /**
 482  * Request information about a specific channel of the running cadet peer.
 483  *
 484  * WARNING: unstable API, likely to change in the future!
 485  *
 486  * @param h Handle to the cadet peer.
 487  * @param peer ID of the other end of the channel.
 488  * @param channel_number Channel number.
 489  * @param callback Function to call with the requested data.
 490  * @param callback_cls Closure for @c callback.
 491  */
 492 void
 493 GNUNET_CADET_get_channel (struct GNUNET_CADET_Handle *h,
 494                           struct GNUNET_PeerIdentity *peer,
 495                           uint32_t channel_number,
 496                           GNUNET_CADET_ChannelCB callback,
 497                           void *callback_cls);
 498
 499
 500 /**
 501  * Request a debug dump on the service's STDERR.
 502  *
 503  * WARNING: unstable API, likely to change in the future!
 504  *
 505  * @param h cadet handle
 506  */
 507 void
 508 GNUNET_CADET_request_dump (struct GNUNET_CADET_Handle *h);
 509
 510
 511 /**
 512  * Request information about peers known to the running cadet service.
 513  * The callback will be called for every peer known to the service.
 514  * Only one info request (of any kind) can be active at once.
 515  *
 516  *
 517  * WARNING: unstable API, likely to change in the future!
 518  *
 519  * @param h Handle to the cadet peer.
 520  * @param callback Function to call with the requested data.
 521  * @param callback_cls Closure for @c callback.
 522  *
 523  * @return #GNUNET_OK / #GNUNET_SYSERR
 524  */
 525 int
 526 GNUNET_CADET_get_peers (struct GNUNET_CADET_Handle *h,
 527                         GNUNET_CADET_PeersCB callback,
 528                         void *callback_cls);
 529
 530
 531 /**
 532  * Cancel a peer info request. The callback will not be called (anymore).
 533  *
 534  * WARNING: unstable API, likely to change in the future!
 535  *
 536  * @param h Cadet handle.
 537  *
 538  * @return Closure that was given to #GNUNET_CADET_get_peers().
 539  */
 540 void *
 541 GNUNET_CADET_get_peers_cancel (struct GNUNET_CADET_Handle *h);
 542
 543
 544 /**
 545  * Request information about a peer known to the running cadet peer.
 546  * The callback will be called for the tunnel once.
 547  * Only one info request (of any kind) can be active at once.
 548  *
 549  * WARNING: unstable API, likely to change in the future!
 550  *
 551  * @param h Handle to the cadet peer.
 552  * @param id Peer whose tunnel to examine.
 553  * @param callback Function to call with the requested data.
 554  * @param callback_cls Closure for @c callback.
 555  *
 556  * @return #GNUNET_OK / #GNUNET_SYSERR
 557  */
 558 int
 559 GNUNET_CADET_get_peer (struct GNUNET_CADET_Handle *h,
 560                       const struct GNUNET_PeerIdentity *id,
 561                       GNUNET_CADET_PeerCB callback,
 562                       void *callback_cls);
 563
 564
 565 /**
 566  * Request information about tunnels of the running cadet peer.
 567  * The callback will be called for every tunnel of the service.
 568  * Only one info request (of any kind) can be active at once.
 569  *
 570  * WARNING: unstable API, likely to change in the future!
 571  *
 572  * @param h Handle to the cadet peer.
 573  * @param callback Function to call with the requested data.
 574  * @param callback_cls Closure for @c callback.
 575  *
 576  * @return #GNUNET_OK / #GNUNET_SYSERR
 577  */
 578 int
 579 GNUNET_CADET_get_tunnels (struct GNUNET_CADET_Handle *h,
 580                           GNUNET_CADET_TunnelsCB callback,
 581                           void *callback_cls);
 582
 583
 584 /**
 585  * Cancel a monitor request. The monitor callback will not be called.
 586  *
 587  * @param h Cadet handle.
 588  *
 589  * @return Closure given to #GNUNET_CADET_get_tunnels(), if any.
 590  */
 591 void *
 592 GNUNET_CADET_get_tunnels_cancel (struct GNUNET_CADET_Handle *h);
 593
 594
 595 /**
 596  * Request information about a tunnel of the running cadet peer.
 597  * The callback will be called for the tunnel once.
 598  * Only one info request (of any kind) can be active at once.
 599  *
 600  * WARNING: unstable API, likely to change in the future!
 601  *
 602  * @param h Handle to the cadet peer.
 603  * @param id Peer whose tunnel to examine.
 604  * @param callback Function to call with the requested data.
 605  * @param callback_cls Closure for @c callback.
 606  *
 607  * @return #GNUNET_OK / #GNUNET_SYSERR
 608  */
 609 int
 610 GNUNET_CADET_get_tunnel (struct GNUNET_CADET_Handle *h,
 611                          const struct GNUNET_PeerIdentity *id,
 612                          GNUNET_CADET_TunnelCB callback,
 613                          void *callback_cls);
 614
 615
 616 /**
 617  * Create a message queue for a cadet channel.
 618  * The message queue can only be used to transmit messages,
 619  * not to receive them.
 620  *
 621  * @param channel the channel to create the message qeue for
 622  * @return a message queue to messages over the channel
 623  */
 624 struct GNUNET_MQ_Handle *
 625 GNUNET_CADET_mq_create (struct GNUNET_CADET_Channel *channel);
 626
 627
 628 #if 0                           /* keep Emacsens' auto-indent happy */
 629 {
 630 #endif
 631 #ifdef __cplusplus
 632 }
 633 #endif
 634
 635 /* ifndef GNUNET_CADET_SERVICE_H */
 636 #endif
 637 /* end of gnunet_cadet_service.h */