src/include/gnunet_cadet_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2014 GNUnet e.V.
   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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20 /**
  21  * @author Christian Grothoff
  22  * @author Bart Polot
  23  *
  24  * @file
  25  * CADET service; establish channels to distant peers
  26  *
  27  * @defgroup cadet  CADET service
  28  * Confidential Ad-hoc Decentralized End-to-End Transport
  29  *
  30  * @see [Documentation](https://gnunet.org/cadet-subsystem)
  31  * @see [Paper](https://gnunet.org/cadet)
  32  *
  33  * @{
  34  */
  35 #ifndef GNUNET_CADET_SERVICE_H
  36 #define GNUNET_CADET_SERVICE_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 #include "gnunet_util_lib.h"
  47 #include "gnunet_transport_service.h"
  48
  49 /**
  50  * Version number of GNUnet-cadet API.
  51  */
  52 #define GNUNET_CADET_VERSION 0x00000004
  53
  54
  55 /**
  56  * Opaque handle to the service.
  57  */
  58 struct GNUNET_CADET_Handle;
  59
  60 /**
  61  * Opaque handle to a channel.
  62  */
  63 struct GNUNET_CADET_Channel;
  64
  65 /**
  66  * Opaque handle to a port.
  67  */
  68 struct GNUNET_CADET_Port;
  69
  70
  71 /**
  72  * Channel options.  Second line indicates filed in the
  73  * CadetChannelInfo union carrying the answer.
  74  */
  75 enum GNUNET_CADET_ChannelOption
  76 {
  77   /**
  78    * Default options: unreliable, default buffering, not out of order.
  79    */
  80   GNUNET_CADET_OPTION_DEFAULT    = 0x0,
  81
  82   /**
  83    * Disable buffering on intermediate nodes (for minimum latency).
  84    * Yes/No.
  85    */
  86   GNUNET_CADET_OPTION_NOBUFFER   = 0x1,
  87
  88   /**
  89    * Enable channel reliability, lost messages will be retransmitted.
  90    * Yes/No.
  91    */
  92   GNUNET_CADET_OPTION_RELIABLE   = 0x2,
  93
  94   /**
  95    * Enable out of order delivery of messages.
  96    * Set bit for out-of-order delivery.
  97    */
  98   GNUNET_CADET_OPTION_OUT_OF_ORDER = 0x4,
  99
 100   /**
 101    * Who is the peer at the other end of the channel.
 102    * Only for use in @c GNUNET_CADET_channel_get_info
 103    * struct GNUNET_PeerIdentity *peer
 104    */
 105   GNUNET_CADET_OPTION_PEER       = 0x8
 106
 107 };
 108
 109
 110 /**
 111  * Functions with this signature are called whenever a message is
 112  * received.
 113  *
 114  * Each time the function must call #GNUNET_CADET_receive_done on the channel
 115  * in order to receive the next message. This doesn't need to be immediate:
 116  * can be delayed if some processing is done on the message.
 117  *
 118  * @param cls Closure (set from #GNUNET_CADET_connect).
 119  * @param channel Connection to the other end.
 120  * @param channel_ctx Place to store local state associated with the channel.
 121  * @param message The actual message.
 122  * @return #GNUNET_OK to keep the channel open,
 123  *         #GNUNET_SYSERR to close it (signal serious error).
 124  */
 125 typedef int
 126 (*GNUNET_CADET_MessageCallback) (void *cls,
 127                                  struct GNUNET_CADET_Channel *channel,
 128                                  void **channel_ctx,
 129                                  const struct GNUNET_MessageHeader *message);
 130
 131
 132 /**
 133  * Message handler.  Each struct specifies how to handle on particular
 134  * type of message received.
 135  */
 136 struct GNUNET_CADET_MessageHandler
 137 {
 138   /**
 139    * Function to call for messages of type @e type.
 140    */
 141   GNUNET_CADET_MessageCallback callback;
 142
 143   /**
 144    * Type of the message this handler covers.
 145    */
 146   uint16_t type;
 147
 148   /**
 149    * Expected size of messages of this type.  Use 0 for variable-size.
 150    * If non-zero, messages of the given type will be discarded if they
 151    * do not have the right size.
 152    */
 153   uint16_t expected_size;
 154 };
 155
 156
 157 /**
 158  * Method called whenever another peer has added us to a channel
 159  * the other peer initiated.
 160  * Only called (once) upon reception of data with a message type which was
 161  * subscribed to in #GNUNET_CADET_connect.
 162  *
 163  * A call to #GNUNET_CADET_channel_destroy causes te channel to be ignored. In
 164  * this case the handler MUST return NULL.
 165  *
 166  * @param cls closure
 167  * @param channel new handle to the channel
 168  * @param initiator peer that started the channel
 169  * @param port Port this channel is for.
 170  * @param options CadetOption flag field, with all active option bits set to 1.
 171  *
 172  * @return initial channel context for the channel
 173  *         (can be NULL -- that's not an error)
 174  */
 175 typedef void *
 176 (GNUNET_CADET_InboundChannelNotificationHandler) (void *cls,
 177                                                   struct GNUNET_CADET_Channel *channel,
 178                                                   const struct GNUNET_PeerIdentity *initiator,
 179                                                   const struct GNUNET_HashCode *port,
 180                                                   enum GNUNET_CADET_ChannelOption options);
 181
 182
 183 /**
 184  * Function called whenever a channel is destroyed.  Should clean up
 185  * any associated state, including cancelling any pending transmission on this
 186  * channel.
 187  *
 188  * It must NOT call #GNUNET_CADET_channel_destroy on the channel.
 189  *
 190  * @param cls closure (set from #GNUNET_CADET_connect)
 191  * @param channel connection to the other end (henceforth invalid)
 192  * @param channel_ctx place where local state associated
 193  *                   with the channel is stored
 194  */
 195 typedef void
 196 (GNUNET_CADET_ChannelEndHandler) (void *cls,
 197                                   const struct GNUNET_CADET_Channel *channel,
 198                                   void *channel_ctx);
 199
 200
 201 /**
 202  * Connect to the cadet service.
 203  *
 204  * @param cfg Configuration to use.
 205  * @param cls Closure for the various callbacks that follow (including
 206  *            handlers in the handlers array).
 207  * @param cleaner Function called when a channel is destroyed.
 208  *                It is called immediately if #GNUNET_CADET_channel_destroy
 209  *                is called on the channel.
 210  * @param handlers Callbacks for messages we care about, NULL-terminated. Each
 211  *                 one must call #GNUNET_CADET_receive_done on the channel to
 212  *                 receive the next message.  Messages of a type that is not
 213  *                 in the handlers array are ignored if received.
 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_ChannelEndHandler cleaner,
 222                       const struct GNUNET_CADET_MessageHandler *handlers);
 223
 224
 225 /**
 226  * Disconnect from the cadet service. All channels will be destroyed. All channel
 227  * disconnect callbacks will be called on any still connected peers, notifying
 228  * about their disconnection. The registered inbound channel cleaner will be
 229  * called should any inbound channels still exist.
 230  *
 231  * @param handle connection to cadet to disconnect
 232  */
 233 void
 234 GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle);
 235
 236 /**
 237  * Open a port to receive incomming channels.
 238  *
 239  * @param h CADET handle.
 240  * @param port Hash representing the port number.
 241  * @param new_channel Function called when an channel is received.
 242  * @param new_channel_cls Closure for @a new_channel.
 243  *
 244  * @return Port handle.
 245  */
 246 struct GNUNET_CADET_Port *
 247 GNUNET_CADET_open_port (struct GNUNET_CADET_Handle *h,
 248                         const struct GNUNET_HashCode *port,
 249                         GNUNET_CADET_InboundChannelNotificationHandler new_channel,
 250                         void *new_channel_cls);
 251
 252 /**
 253  * Close a port opened with @a GNUNET_CADET_open_port.
 254  * The @a new_channel callback will no longer be called.
 255  *
 256  * @param p Port handle.
 257  */
 258 void
 259 GNUNET_CADET_close_port (struct GNUNET_CADET_Port *p);
 260
 261 /**
 262  * Create a new channel towards a remote peer.
 263  *
 264  * If the destination port is not open by any peer or the destination peer
 265  * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called
 266  * for this channel.
 267  *
 268  * @param h cadet handle
 269  * @param channel_ctx client's channel context to associate with the channel
 270  * @param peer peer identity the channel should go to
 271  * @param port Port hash (port number).
 272  * @param options CadetOption flag field, with all desired option bits set to 1.
 273  *
 274  * @return handle to the channel
 275  */
 276 struct GNUNET_CADET_Channel *
 277 GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h,
 278                             void *channel_ctx,
 279                             const struct GNUNET_PeerIdentity *peer,
 280                             const struct GNUNET_HashCode *port,
 281                             enum GNUNET_CADET_ChannelOption options);
 282
 283
 284 /**
 285  * Destroy an existing channel.
 286  *
 287  * The existing end callback for the channel will be called immediately.
 288  * Any pending outgoing messages will be sent but no incoming messages will be
 289  * accepted and no data callbacks will be called.
 290  *
 291  * @param channel Channel handle, becomes invalid after this call.
 292  */
 293 void
 294 GNUNET_CADET_channel_destroy (struct GNUNET_CADET_Channel *channel);
 295
 296
 297 /**
 298  * Struct to retrieve info about a channel.
 299  */
 300 union GNUNET_CADET_ChannelInfo
 301 {
 302
 303   /**
 304    * #GNUNET_YES / #GNUNET_NO, for binary flags.
 305    */
 306   int yes_no;
 307
 308   /**
 309    * Peer on the other side of the channel
 310    */
 311   const struct GNUNET_PeerIdentity peer;
 312 };
 313
 314
 315 /**
 316  * Get information about a channel.
 317  *
 318  * @param channel Channel handle.
 319  * @param option Query type GNUNET_CADET_OPTION_*
 320  * @param ... dependant on option, currently not used
 321  * @return Union with an answer to the query.
 322  */
 323 const union GNUNET_CADET_ChannelInfo *
 324 GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel,
 325                               enum GNUNET_CADET_ChannelOption option,
 326                                ...);
 327
 328
 329 /**
 330  * Handle for a transmission request.
 331  */
 332 struct GNUNET_CADET_TransmitHandle;
 333
 334
 335 /**
 336  * Ask the cadet to call @a notify once it is ready to transmit the
 337  * given number of bytes to the specified channel.
 338  * Only one call can be active at any time, to issue another request,
 339  * wait for the callback or cancel the current request.
 340  *
 341  * @param channel channel to use for transmission
 342  * @param cork is corking allowed for this transmission?
 343  * @param maxdelay how long can the message wait?
 344  * @param notify_size how many bytes of buffer space does notify want?
 345  * @param notify function to call when buffer space is available;
 346  *        will be called with NULL on timeout or if the overall queue
 347  *        for this peer is larger than queue_size and this is currently
 348  *        the message with the lowest priority
 349  * @param notify_cls closure for @a notify
 350  * @return non-NULL if the notify callback was queued,
 351  *         NULL if we can not even queue the request (insufficient
 352  *         memory); if NULL is returned, @a notify will NOT be called.
 353  */
 354 struct GNUNET_CADET_TransmitHandle *
 355 GNUNET_CADET_notify_transmit_ready (struct GNUNET_CADET_Channel *channel,
 356                                    int cork,
 357                                    struct GNUNET_TIME_Relative maxdelay,
 358                                    size_t notify_size,
 359                                    GNUNET_CONNECTION_TransmitReadyNotify notify,
 360                                    void *notify_cls);
 361
 362
 363 /**
 364  * Cancel the specified transmission-ready notification.
 365  *
 366  * #DEPRECATED
 367  * Since soon we will send immediately with mq (via request_data),
 368  * there will be time or need to cancel a "pending" transmission.
 369  *
 370  * @param th handle that was returned by "notify_transmit_ready".
 371  */
 372 void
 373 GNUNET_CADET_notify_transmit_ready_cancel (struct GNUNET_CADET_TransmitHandle *th);
 374
 375
 376 /**
 377  * Indicate readiness to receive the next message on a channel.
 378  *
 379  * Should only be called once per handler called.
 380  *
 381  * @param channel Channel that will be allowed to call another handler.
 382  */
 383 void
 384 GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel);
 385
 386
 387
 388 /******************************************************************************/
 389 /********************       MONITORING /DEBUG API     *************************/
 390 /******************************************************************************/
 391 /* The following calls are not useful for normal CADET operation, but for      */
 392 /* debug and monitoring of the cadet state. They can be safely ignored.        */
 393 /* The API can change at any point without notice.                            */
 394 /* Please contact the developer if you consider any of this calls useful for  */
 395 /* normal cadet applications.                                                  */
 396 /******************************************************************************/
 397
 398
 399 /**
 400  * Method called to retrieve information about a specific channel the cadet peer
 401  * is aware of, including all transit nodes.
 402  *
 403  * @param cls Closure.
 404  * @param root Root of the channel.
 405  * @param dest Destination of the channel.
 406  * @param port Destination port of the channel.
 407  * @param root_channel_number Local number for root, if known.
 408  * @param dest_channel_number Local number for dest, if known.
 409  * @param public_channel_numbe Number for P2P, always known.
 410  */
 411 typedef void
 412 (*GNUNET_CADET_ChannelCB) (void *cls,
 413                            const struct GNUNET_PeerIdentity *root,
 414                            const struct GNUNET_PeerIdentity *dest,
 415                            uint32_t /* UGH */ port,
 416                            uint32_t /* ugh */ root_channel_number,
 417                            uint32_t /* ugh */ dest_channel_number,
 418                            uint32_t /* ugh */ public_channel_number);
 419
 420 /**
 421  * Method called to retrieve information about all peers in CADET, called
 422  * once per peer.
 423  *
 424  * After last peer has been reported, an additional call with NULL is done.
 425  *
 426  * @param cls Closure.
 427  * @param peer Peer, or NULL on "EOF".
 428  * @param tunnel Do we have a tunnel towards this peer?
 429  * @param n_paths Number of known paths towards this peer.
 430  * @param best_path How long is the best path?
 431  *                  (0 = unknown, 1 = ourselves, 2 = neighbor)
 432  */
 433 typedef void
 434 (*GNUNET_CADET_PeersCB) (void *cls,
 435                          const struct GNUNET_PeerIdentity *peer,
 436                          int tunnel,
 437                          unsigned int n_paths,
 438                          unsigned int best_path);
 439
 440 /**
 441  * Method called to retrieve information about a specific peer
 442  * known to the service.
 443  *
 444  * @param cls Closure.
 445  * @param peer Peer ID.
 446  * @param tunnel Do we have a tunnel towards this peer? #GNUNET_YES/#GNUNET_NO
 447  * @param neighbor Is this a direct neighbor? #GNUNET_YES/#GNUNET_NO
 448  * @param n_paths Number of paths known towards peer.
 449  * @param paths Array of PEER_IDs representing all paths to reach the peer.
 450  *              Each path starts with the first hop (local peer not included).
 451  *              Each path ends with the destination peer (given in @c peer).
 452  */
 453 typedef void
 454 (*GNUNET_CADET_PeerCB) (void *cls,
 455                         const struct GNUNET_PeerIdentity *peer,
 456                         int tunnel,
 457                         int neighbor,
 458                         unsigned int n_paths,
 459                         struct GNUNET_PeerIdentity *paths);
 460
 461
 462 /**
 463  * Method called to retrieve information about all tunnels in CADET, called
 464  * once per tunnel.
 465  *
 466  * After last tunnel has been reported, an additional call with NULL is done.
 467  *
 468  * @param cls Closure.
 469  * @param peer Destination peer, or NULL on "EOF".
 470  * @param channels Number of channels.
 471  * @param connections Number of connections.
 472  * @param estate Encryption state.
 473  * @param cstate Connectivity state.
 474  */
 475 typedef void
 476 (*GNUNET_CADET_TunnelsCB) (void *cls,
 477                            const struct GNUNET_PeerIdentity *peer,
 478                            unsigned int channels,
 479                            unsigned int connections,
 480                            uint16_t estate,
 481                            uint16_t cstate);
 482
 483
 484 /**
 485  * Hash uniquely identifying a connection below a tunnel.
 486  */
 487 struct GNUNET_CADET_ConnectionTunnelIdentifier
 488 {
 489   struct GNUNET_ShortHashCode connection_of_tunnel;
 490 };
 491
 492
 493 /**
 494  * Number identifying a CADET channel within a tunnel.
 495  */
 496 struct GNUNET_CADET_ChannelTunnelNumber
 497 {
 498   /**
 499    * Which number does this channel have that uniquely identfies
 500    * it within its tunnel, in network byte order.
 501    *
 502    * Given two peers, both may initiate channels over the same tunnel.
 503    * The @e cn must be greater or equal to 0x80000000 (high-bit set)
 504    * for tunnels initiated with the peer that has the larger peer
 505    * identity as compared using #GNUNET_CRYPTO_cmp_peer_identity().
 506    */
 507   uint32_t cn GNUNET_PACKED;
 508 };
 509
 510
 511 /**
 512  * Method called to retrieve information about a specific tunnel the cadet peer
 513  * has established, o`r is trying to establish.
 514  *
 515  * @param cls Closure.
 516  * @param peer Peer towards whom the tunnel is directed.
 517  * @param n_channels Number of channels.
 518  * @param n_connections Number of connections.
 519  * @param channels Channels.
 520  * @param connections Connections.
 521  * @param estate Encryption state.
 522  * @param cstate Connectivity state.
 523  */
 524 typedef void
 525 (*GNUNET_CADET_TunnelCB) (void *cls,
 526                           const struct GNUNET_PeerIdentity *peer,
 527                           unsigned int n_channels,
 528                           unsigned int n_connections,
 529                           const struct GNUNET_CADET_ChannelTunnelNumber *channels,
 530                           const struct GNUNET_CADET_ConnectionTunnelIdentifier *connections,
 531                           unsigned int estate,
 532                           unsigned int cstate);
 533
 534
 535 /**
 536  * Request information about a specific channel of the running cadet peer.
 537  *
 538  * WARNING: unstable API, likely to change in the future!
 539  *
 540  * @param h Handle to the cadet peer.
 541  * @param peer ID of the other end of the channel.
 542  * @param channel_number Channel number.
 543  * @param callback Function to call with the requested data.
 544  * @param callback_cls Closure for @c callback.
 545  */
 546 void
 547 GNUNET_CADET_get_channel (struct GNUNET_CADET_Handle *h,
 548                           struct GNUNET_PeerIdentity *peer,
 549                           uint32_t /* UGH */ channel_number,
 550                           GNUNET_CADET_ChannelCB callback,
 551                           void *callback_cls);
 552
 553
 554 /**
 555  * Request a debug dump on the service's STDERR.
 556  *
 557  * WARNING: unstable API, likely to change in the future!
 558  *
 559  * @param h cadet handle
 560  */
 561 void
 562 GNUNET_CADET_request_dump (struct GNUNET_CADET_Handle *h);
 563
 564
 565 /**
 566  * Request information about peers known to the running cadet service.
 567  * The callback will be called for every peer known to the service.
 568  * Only one info request (of any kind) can be active at once.
 569  *
 570  *
 571  * WARNING: unstable API, likely to change in the future!
 572  *
 573  * @param h Handle to the cadet peer.
 574  * @param callback Function to call with the requested data.
 575  * @param callback_cls Closure for @c callback.
 576  *
 577  * @return #GNUNET_OK / #GNUNET_SYSERR
 578  */
 579 int
 580 GNUNET_CADET_get_peers (struct GNUNET_CADET_Handle *h,
 581                         GNUNET_CADET_PeersCB callback,
 582                         void *callback_cls);
 583
 584
 585 /**
 586  * Cancel a peer info request. The callback will not be called (anymore).
 587  *
 588  * WARNING: unstable API, likely to change in the future!
 589  *
 590  * @param h Cadet handle.
 591  *
 592  * @return Closure that was given to #GNUNET_CADET_get_peers().
 593  */
 594 void *
 595 GNUNET_CADET_get_peers_cancel (struct GNUNET_CADET_Handle *h);
 596
 597
 598 /**
 599  * Request information about a peer known to the running cadet peer.
 600  * The callback will be called for the tunnel once.
 601  * Only one info request (of any kind) can be active at once.
 602  *
 603  * WARNING: unstable API, likely to change in the future!
 604  *
 605  * @param h Handle to the cadet peer.
 606  * @param id Peer whose tunnel to examine.
 607  * @param callback Function to call with the requested data.
 608  * @param callback_cls Closure for @c callback.
 609  *
 610  * @return #GNUNET_OK / #GNUNET_SYSERR
 611  */
 612 int
 613 GNUNET_CADET_get_peer (struct GNUNET_CADET_Handle *h,
 614                       const struct GNUNET_PeerIdentity *id,
 615                       GNUNET_CADET_PeerCB callback,
 616                       void *callback_cls);
 617
 618
 619 /**
 620  * Request information about tunnels of the running cadet peer.
 621  * The callback will be called for every tunnel of the service.
 622  * Only one info request (of any kind) can be active at once.
 623  *
 624  * WARNING: unstable API, likely to change in the future!
 625  *
 626  * @param h Handle to the cadet peer.
 627  * @param callback Function to call with the requested data.
 628  * @param callback_cls Closure for @c callback.
 629  *
 630  * @return #GNUNET_OK / #GNUNET_SYSERR
 631  */
 632 int
 633 GNUNET_CADET_get_tunnels (struct GNUNET_CADET_Handle *h,
 634                           GNUNET_CADET_TunnelsCB callback,
 635                           void *callback_cls);
 636
 637
 638 /**
 639  * Cancel a monitor request. The monitor callback will not be called.
 640  *
 641  * @param h Cadet handle.
 642  *
 643  * @return Closure given to #GNUNET_CADET_get_tunnels(), if any.
 644  */
 645 void *
 646 GNUNET_CADET_get_tunnels_cancel (struct GNUNET_CADET_Handle *h);
 647
 648
 649 /**
 650  * Request information about a tunnel of the running cadet peer.
 651  * The callback will be called for the tunnel once.
 652  * Only one info request (of any kind) can be active at once.
 653  *
 654  * WARNING: unstable API, likely to change in the future!
 655  *
 656  * @param h Handle to the cadet peer.
 657  * @param id Peer whose tunnel to examine.
 658  * @param callback Function to call with the requested data.
 659  * @param callback_cls Closure for @c callback.
 660  *
 661  * @return #GNUNET_OK / #GNUNET_SYSERR
 662  */
 663 int
 664 GNUNET_CADET_get_tunnel (struct GNUNET_CADET_Handle *h,
 665                          const struct GNUNET_PeerIdentity *id,
 666                          GNUNET_CADET_TunnelCB callback,
 667                          void *callback_cls);
 668
 669
 670 /**
 671  * Create a message queue for a cadet channel.
 672  * The message queue can only be used to transmit messages,
 673  * not to receive them.
 674  *
 675  * @param channel the channel to create the message qeue for
 676  * @return a message queue to messages over the channel
 677  */
 678 struct GNUNET_MQ_Handle *
 679 GNUNET_CADET_mq_create (struct GNUNET_CADET_Channel *channel);
 680
 681
 682 /**
 683  * Transitional function to convert an unsigned int port to a hash value.
 684  * WARNING: local static value returned, NOT reentrant!
 685  * WARNING: do not use this function for new code!
 686  *
 687  * @param port Numerical port (unsigned int format).
 688  *
 689  * @return A GNUNET_HashCode usable for the new CADET API.
 690  */
 691 const struct GNUNET_HashCode *
 692 GC_u2h (uint32_t port);
 693
 694
 695 /******************************************************************************/
 696 /******************************* MQ-BASED API *********************************/
 697 /******************************************************************************/
 698
 699 /**
 700  * Method called whenever a peer connects to a port in MQ-based CADET.
 701  *
 702  * @param cls Closure from #GNUNET_CADET_open_porT.
 703  * @param channel New handle to the channel.
 704  * @param source Peer that started this channel.
 705  * @return Closure for the incoming @a channel. It's given to:
 706  *         - The #GNUNET_CADET_DisconnectEventHandler (given to
 707  *           #GNUNET_CADET_open_porT) when the channel dies.
 708  *         - Each the #GNUNET_MQ_MessageCallback handlers for each message
 709  *           received on the @a channel.
 710  */
 711 typedef void *
 712 (*GNUNET_CADET_ConnectEventHandler) (void *cls,
 713                                      struct GNUNET_CADET_Channel *channel,
 714                                      const struct GNUNET_PeerIdentity *source);
 715
 716 /**
 717  * Function called whenever an MQ-channel is destroyed, even if the destruction
 718  * was requested by #GNUNET_CADET_channel_destroy.
 719  * It must NOT call #GNUNET_CADET_channel_destroy on the channel.
 720  *
 721  * It should clean up any associated state, including cancelling any pending
 722  * transmission on this channel.
 723  *
 724  * @param cls Channel closure.
 725  * @param channel Connection to the other end (henceforth invalid).
 726  */
 727 typedef void
 728 (*GNUNET_CADET_DisconnectEventHandler) (void *cls,
 729                                         const struct GNUNET_CADET_Channel *channel);
 730
 731 /**
 732  * Function called whenever an MQ-channel's transmission window size changes.
 733  *
 734  * The first callback in an outgoing channel will be with a non-zero value
 735  * and will mean the channel is connected to the destination.
 736  *
 737  * For an incoming channel it will be called immediately after the
 738  * #GNUNET_CADET_ConnectEventHandler, also with a non-zero value.
 739  *
 740  * @param cls Channel closure.
 741  * @param channel Connection to the other end (henceforth invalid).
 742  * @param window_size New window size. If the is more messages than buffer size
 743  *                    this value will be negative..
 744  */
 745 typedef void
 746 (*GNUNET_CADET_WindowSizeEventHandler) (void *cls,
 747                                         const struct GNUNET_CADET_Channel *channel,
 748                                         int window_size);
 749
 750 /**
 751  * Connect to the MQ-based cadet service.
 752  *
 753  * @param cfg Configuration to use.
 754  * @return Handle to the cadet service NULL on error.
 755  */
 756 struct GNUNET_CADET_Handle *
 757 GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg);
 758
 759 /**
 760  * Open a port to receive incomming MQ-based channels.
 761  *
 762  * @param h CADET handle.
 763  * @param port Hash identifying the port.
 764  * @param connects Function called when an incoming channel is connected.
 765  * @param connects_cls Closure for the @a connects handler.
 766  * @param window_changes Function called when the transmit window size changes.
 767  *                       Can be NULL.
 768  * @param disconnects Function called when a channel is disconnected.
 769  * @param handlers Callbacks for messages we care about, NULL-terminated.
 770  * @return Port handle.
 771  */
 772 struct GNUNET_CADET_Port *
 773 GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h,
 774                         const struct GNUNET_HashCode *port,
 775                         GNUNET_CADET_ConnectEventHandler connects,
 776                         void *connects_cls,
 777                         GNUNET_CADET_WindowSizeEventHandler window_changes,
 778                         GNUNET_CADET_DisconnectEventHandler disconnects,
 779                         const struct GNUNET_MQ_MessageHandler *handlers);
 780
 781 /**
 782  * Create a new channel towards a remote peer.
 783  *
 784  * If the destination port is not open by any peer or the destination peer
 785  * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called
 786  * for this channel.
 787  *
 788  * @param h CADET handle.
 789  * @param channel_cls Closure for the channel. It's given to:
 790  *                    - The management handler @a window_changes.
 791  *                    - The disconnect handler @a disconnects
 792  *                    - Each message type callback in @a handlers
 793  * @param destination Peer identity the channel should go to.
 794  * @param port Identification of the destination port.
 795  * @param options CadetOption flag field, with all desired option bits set to 1.
 796  * @param window_changes Function called when the transmit window size changes.
 797  *                       Can be NULL if this data is of no interest.
 798  * TODO                  Not yet implemented.
 799  * @param disconnects Function called when the channel is disconnected.
 800  * @param handlers Callbacks for messages we care about, NULL-terminated.
 801  * @return Handle to the channel.
 802  */
 803 struct GNUNET_CADET_Channel *
 804 GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h,
 805                              void *channel_cls,
 806                              const struct GNUNET_PeerIdentity *destination,
 807                              const struct GNUNET_HashCode *port,
 808                              enum GNUNET_CADET_ChannelOption options,
 809                              GNUNET_CADET_WindowSizeEventHandler window_changes,
 810                              GNUNET_CADET_DisconnectEventHandler disconnects,
 811                              const struct GNUNET_MQ_MessageHandler *handlers);
 812
 813 /**
 814  * Obtain the message queue for a connected channel.
 815  *
 816  * @param channel The channel handle from which to get the MQ.
 817  * @return The message queue of the channel.
 818  */
 819 struct GNUNET_MQ_Handle *
 820 GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel);
 821
 822
 823 /******************************************************************************/
 824 /******************************* MQ-BASED API *********************************/
 825 /******************************************************************************/
 826
 827
 828
 829 #if 0                           /* keep Emacsens' auto-indent happy */
 830 {
 831 #endif
 832 #ifdef __cplusplus
 833 }
 834 #endif
 835
 836 /* ifndef GNUNET_CADET_SERVICE_H */
 837 #endif
 838
 839 /** @} */  /* end of group */
 840
 841 /* end of gnunet_cadet_service.h */