src/include/gnunet_transport_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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Low-level P2P IO
  26  *
  27  * @defgroup transport  Transport service
  28  * Low-level P2P IO
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_TRANSPORT_SERVICE_H
  33 #define GNUNET_TRANSPORT_SERVICE_H
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43 #include "gnunet_util_lib.h"
  44 #include "gnunet_ats_service.h"
  45
  46 /**
  47  * Version number of the transport API.
  48  */
  49 #define GNUNET_TRANSPORT_VERSION 0x00000002
  50
  51
  52 /**
  53  * Function called by the transport for each received message.
  54  *
  55  * @param cls closure
  56  * @param peer (claimed) identity of the other peer
  57  * @param message the message
  58  */
  59 typedef void
  60 (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls,
  61                                      const struct GNUNET_PeerIdentity *peer,
  62                                      const struct GNUNET_MessageHeader *message);
  63
  64
  65 /**
  66  * Opaque handle to the service.
  67  */
  68 struct GNUNET_TRANSPORT_Handle;
  69
  70
  71 /**
  72  * Function called to notify transport users that another
  73  * peer connected to us.
  74  *
  75  * @param cls closure
  76  * @param peer the peer that connected
  77  */
  78 typedef void
  79 (*GNUNET_TRANSPORT_NotifyConnect) (void *cls,
  80                                    const struct GNUNET_PeerIdentity *peer);
  81
  82 /**
  83  * Function called to notify transport users that another
  84  * peer disconnected from us.
  85  *
  86  * @param cls closure
  87  * @param peer the peer that disconnected
  88  */
  89 typedef void
  90 (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls,
  91                                       const struct GNUNET_PeerIdentity *peer);
  92
  93
  94 /**
  95  * Connect to the transport service.  Note that the connection may
  96  * complete (or fail) asynchronously.
  97  *
  98  * @param cfg configuration to use
  99  * @param self our own identity (API should check that it matches
 100  *             the identity found by transport), or NULL (no check)
 101  * @param cls closure for the callbacks
 102  * @param rec receive function to call, or NULL
 103  * @param nc function to call on connect events, or NULL
 104  * @param nd function to call on disconnect events, or NULL
 105  * @return NULL on error
 106  */
 107 struct GNUNET_TRANSPORT_Handle *
 108 GNUNET_TRANSPORT_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 109                           const struct GNUNET_PeerIdentity *self,
 110                           void *cls,
 111                           GNUNET_TRANSPORT_ReceiveCallback rec,
 112                           GNUNET_TRANSPORT_NotifyConnect nc,
 113                           GNUNET_TRANSPORT_NotifyDisconnect nd);
 114
 115
 116 /**
 117  * Function called if we have "excess" bandwidth to a peer.
 118  * The notification will happen the first time we have excess
 119  * bandwidth, and then only again after the client has performed
 120  * some transmission to the peer.
 121  *
 122  * Excess bandwidth is defined as being allowed (by ATS) to send
 123  * more data, and us reaching the limit of the capacity build-up
 124  * (which, if we go past it, means we don't use available bandwidth).
 125  * See also the "max carry" in `struct GNUNET_BANDWIDTH_Tracker`.
 126  *
 127  * @param cls the closure
 128  * @param neighbour peer that we have excess bandwidth to
 129  */
 130 typedef void
 131 (*GNUNET_TRANSPORT_NotifyExcessBandwidth)(void *cls,
 132                                           const struct GNUNET_PeerIdentity *neighbour);
 133
 134
 135 /**
 136  * Connect to the transport service.  Note that the connection may
 137  * complete (or fail) asynchronously.
 138  *
 139  * @param cfg configuration to use
 140  * @param self our own identity (API should check that it matches
 141  *             the identity found by transport), or NULL (no check)
 142  * @param cls closure for the callbacks
 143  * @param rec receive function to call, or NULL
 144  * @param nc function to call on connect events, or NULL
 145  * @param nd function to call on disconnect events, or NULL
 146  * @param neb function to call if we have excess bandwidth to a peer
 147  * @return NULL on error
 148  */
 149 struct GNUNET_TRANSPORT_Handle *
 150 GNUNET_TRANSPORT_connect2 (const struct GNUNET_CONFIGURATION_Handle *cfg,
 151                            const struct GNUNET_PeerIdentity *self,
 152                            void *cls,
 153                            GNUNET_TRANSPORT_ReceiveCallback rec,
 154                            GNUNET_TRANSPORT_NotifyConnect nc,
 155                            GNUNET_TRANSPORT_NotifyDisconnect nd,
 156                            GNUNET_TRANSPORT_NotifyExcessBandwidth neb);
 157
 158
 159 /**
 160  * Disconnect from the transport service.
 161  *
 162  * @param handle handle returned from connect
 163  */
 164 void
 165 GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
 166
 167
 168 /* ************************* Sending *************************** */
 169
 170 /**
 171  * Opaque handle for a transmission-ready request.
 172  */
 173 struct GNUNET_TRANSPORT_TransmitHandle;
 174
 175
 176 /**
 177  * Function called to notify a client about the connection begin ready
 178  * to queue more data.  @a buf will be NULL and @a size zero if the
 179  * connection was closed for writing in the meantime.
 180  *
 181  * @param cls closure
 182  * @param size number of bytes available in @a buf
 183  * @param buf where the callee should write the message
 184  * @return number of bytes written to @a buf
 185  */
 186 typedef size_t
 187 (*GNUNET_TRANSPORT_TransmitReadyNotify) (void *cls,
 188                                          size_t size,
 189                                          void *buf);
 190
 191
 192 /**
 193  * Check if we could queue a message of the given size for
 194  * transmission.  The transport service will take both its internal
 195  * buffers and bandwidth limits imposed by the other peer into
 196  * consideration when answering this query.
 197  *
 198  * @param handle connection to transport service
 199  * @param target who should receive the message
 200  * @param size how big is the message we want to transmit?
 201  * @param timeout after how long should we give up (and call
 202  *        notify with buf NULL and size 0)?
 203  * @param notify function to call when we are ready to
 204  *        send such a message
 205  * @param notify_cls closure for @a notify
 206  * @return NULL if someone else is already waiting to be notified
 207  *         non-NULL if the notify callback was queued (can be used to cancel
 208  *         using #GNUNET_TRANSPORT_notify_transmit_ready_cancel())
 209  */
 210 struct GNUNET_TRANSPORT_TransmitHandle *
 211 GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle *handle,
 212                                         const struct GNUNET_PeerIdentity *target,
 213                                         size_t size,
 214                                         struct GNUNET_TIME_Relative timeout,
 215                                         GNUNET_TRANSPORT_TransmitReadyNotify notify,
 216                                         void *notify_cls);
 217
 218
 219 /**
 220  * Cancel the specified transmission-ready notification.
 221  *
 222  * @param th handle of the transmission notification request to cancel
 223  */
 224 void
 225 GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct GNUNET_TRANSPORT_TransmitHandle *th);
 226
 227
 228 /**
 229  * Checks if a given peer is connected to us
 230  *
 231  * @param handle connection to transport service
 232  * @param peer the peer to check
 233  * @return #GNUNET_YES (connected) or #GNUNET_NO (disconnected)
 234  */
 235 int
 236 GNUNET_TRANSPORT_check_peer_connected (struct GNUNET_TRANSPORT_Handle *handle,
 237                                        const struct GNUNET_PeerIdentity *peer);
 238
 239
 240
 241 /* *********************** Metric manipulation ***************** */
 242
 243 /**
 244  * Set transport metrics for a peer and a direction
 245  *
 246  * @param handle transport handle
 247  * @param peer the peer to set the metric for
 248  * @param prop the performance metrics to set
 249  * @param delay_in inbound delay to introduce
 250  * @param delay_out outbound delay to introduce
 251  *
 252  * Note: Delay restrictions in receiving direction will be enforced
 253  * with one message delay.
 254  */
 255 void
 256 GNUNET_TRANSPORT_set_traffic_metric (struct GNUNET_TRANSPORT_Handle *handle,
 257                                      const struct GNUNET_PeerIdentity *peer,
 258                                      const struct GNUNET_ATS_Properties *prop,
 259                                      struct GNUNET_TIME_Relative delay_in,
 260                                      struct GNUNET_TIME_Relative delay_out);
 261
 262
 263 /* *************************** HELLO *************************** */
 264
 265
 266 /**
 267  * Function called whenever there is an update to the
 268  * HELLO of this peer.
 269  *
 270  * @param cls closure
 271  * @param hello our updated HELLO
 272  */
 273 typedef void
 274 (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls,
 275                                          const struct GNUNET_MessageHeader *hello);
 276
 277
 278 /**
 279  * Handle to cancel a #GNUNET_TRANSPORT_get_hello() operation.
 280  */
 281 struct GNUNET_TRANSPORT_GetHelloHandle;
 282
 283
 284 /**
 285  * Obtain updates on changes to the HELLO message for this peer. The callback
 286  * given in this function is never called synchronously.
 287  *
 288  * @param handle connection to transport service
 289  * @param rec function to call with the HELLO
 290  * @param rec_cls closure for @a rec
 291  * @return handle to cancel the operation
 292  */
 293 struct GNUNET_TRANSPORT_GetHelloHandle *
 294 GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle,
 295                             GNUNET_TRANSPORT_HelloUpdateCallback rec,
 296                             void *rec_cls);
 297
 298
 299 /**
 300  * Stop receiving updates about changes to our HELLO message.
 301  *
 302  * @param ghh handle to cancel
 303  */
 304 void
 305 GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh);
 306
 307
 308 /**
 309  * Handle for a #GNUNET_TRANSPORT_offer_hello operation
 310  */
 311 struct GNUNET_TRANSPORT_OfferHelloHandle;
 312
 313
 314 /**
 315  * Offer the transport service the HELLO of another peer.  Note that
 316  * the transport service may just ignore this message if the HELLO is
 317  * malformed or useless due to our local configuration.
 318  *
 319  * @param handle connection to transport service
 320  * @param hello the hello message
 321  * @param cont continuation to call when HELLO has been sent,
 322  *      tc reason #GNUNET_SCHEDULER_REASON_TIMEOUT for fail
 323  *      tc reasong #GNUNET_SCHEDULER_REASON_READ_READY for success
 324  * @param cont_cls closure for @a cont
 325  * @return a GNUNET_TRANSPORT_OfferHelloHandle handle or NULL on failure,
 326  *      in case of failure @a cont will not be called
 327  *
 328  */
 329 struct GNUNET_TRANSPORT_OfferHelloHandle *
 330 GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle,
 331                               const struct GNUNET_MessageHeader *hello,
 332                               GNUNET_SCHEDULER_TaskCallback cont,
 333                               void *cont_cls);
 334
 335
 336 /**
 337  * Cancel the request to transport to offer the HELLO message
 338  *
 339  * @param ohh the `struct GNUNET_TRANSPORT_OfferHelloHandle` to cancel
 340  */
 341 void
 342 GNUNET_TRANSPORT_offer_hello_cancel (struct GNUNET_TRANSPORT_OfferHelloHandle *ohh);
 343
 344
 345 /* *********************** Address to String ******************* */
 346
 347 /**
 348  * Handle to cancel a pending address lookup.
 349  */
 350 struct GNUNET_TRANSPORT_AddressToStringContext;
 351
 352
 353 /**
 354  * Function to call with a textual representation of an address.  This
 355  * function will be called several times with different possible
 356  * textual representations, and a last time with @a address being NULL
 357  * to signal the end of the iteration.  Note that @a address NULL
 358  * always is the last call, regardless of the value in @a res.
 359  *
 360  * @param cls closure
 361  * @param address NULL on end of iteration,
 362  *        otherwise 0-terminated printable UTF-8 string,
 363  *        in particular an empty string if @a res is #GNUNET_NO
 364  * @param res result of the address to string conversion:
 365  *        if #GNUNET_OK: conversion successful
 366  *        if #GNUNET_NO: address was invalid (or not supported)
 367  *        if #GNUNET_SYSERR: communication error (IPC error)
 368  */
 369 typedef void
 370 (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls,
 371                                              const char *address,
 372                                              int res);
 373
 374
 375 /**
 376  * Convert a binary address into a human readable address.
 377  *
 378  * @param cfg configuration to use
 379  * @param address address to convert (binary format)
 380  * @param numeric should (IP) addresses be displayed in numeric form
 381  *                (otherwise do reverse DNS lookup)
 382  * @param timeout how long is the lookup allowed to take at most
 383  * @param aluc function to call with the results
 384  * @param aluc_cls closure for @a aluc
 385  * @return handle to cancel the operation, NULL on error
 386  */
 387 struct GNUNET_TRANSPORT_AddressToStringContext *
 388 GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle *cfg,
 389                                     const struct GNUNET_HELLO_Address *address,
 390                                     int numeric,
 391                                     struct GNUNET_TIME_Relative timeout,
 392                                     GNUNET_TRANSPORT_AddressToStringCallback aluc,
 393                                     void *aluc_cls);
 394
 395
 396 /**
 397  * Cancel request for address conversion.
 398  *
 399  * @param pic the context handle
 400  */
 401 void
 402 GNUNET_TRANSPORT_address_to_string_cancel (struct GNUNET_TRANSPORT_AddressToStringContext *pic);
 403
 404
 405 /* *********************** Monitoring ************************** */
 406
 407
 408 /**
 409  * Possible state of a neighbour.  Initially, we are #GNUNET_TRANSPORT_PS_NOT_CONNECTED.
 410  *
 411  * Then, there are two main paths. If we receive a SYN message, we give
 412  * the inbound address to ATS. After the check we ask ATS for a suggestion
 413  * (#GNUNET_TRANSPORT_PS_CONNECT_RECV_ATS). If ATS makes a suggestion, we
 414  * send our SYN_ACK and go to #GNUNET_TRANSPORT_PS_CONNECT_RECV_ACK.
 415  * If we receive a ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED
 416  * (and notify everyone about the new connection). If the operation times out,
 417  * we go to #GNUNET_TRANSPORT_PS_DISCONNECT.
 418  *
 419  * The other case is where we transmit a SYN message first.  We
 420  * start with #GNUNET_TRANSPORT_PS_INIT_ATS.  If we get an address, we send
 421  * the SYN message and go to state #GNUNET_TRANSPORT_PS_CONNECT_SENT.
 422  * Once we receive a SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED
 423  * (and notify everyone about the new connection and send
 424  * back a ACK).  If the operation times out, we go to
 425  * #GNUNET_TRANSPORT_PS_DISCONNECT.
 426  *
 427  * If the session is in trouble (i.e. transport-level disconnect or
 428  * timeout), we go to #GNUNET_TRANSPORT_PS_RECONNECT_ATS where we ask ATS for a new
 429  * address (we don't notify anyone about the disconnect yet).  Once we
 430  * have a new address, we enter #GNUNET_TRANSPORT_PS_RECONNECT_SENT and send a
 431  * SYN message.  If we receive a
 432  * SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED and nobody noticed that we had
 433  * trouble; we also send a ACK at this time just in case.  If
 434  * the operation times out, we go to #GNUNET_TRANSPORT_PS_DISCONNECT (and notify everyone
 435  * about the lost connection).
 436  *
 437  * If ATS decides to switch addresses while we have a normal
 438  * connection, we go to #GNUNET_TRANSPORT_PS_CONNECTED_SWITCHING_SYN_SENT
 439  * and send a SESSION_CONNECT.  If we get a ACK back, we switch the
 440  * primary connection to the suggested alternative from ATS, go back
 441  * to #GNUNET_TRANSPORT_PS_CONNECTED and send a ACK to the other peer just to be
 442  * sure.  If the operation times out
 443  * we go to #GNUNET_TRANSPORT_PS_CONNECTED (and notify ATS that the given alternative
 444  * address is "invalid").
 445  *
 446  * Once a session is in #GNUNET_TRANSPORT_PS_DISCONNECT, it is cleaned up and then goes
 447  * to (#GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED).  If we receive an explicit disconnect
 448  * request, we can go from any state to #GNUNET_TRANSPORT_PS_DISCONNECT, possibly after
 449  * generating disconnect notifications.
 450  *
 451  * Note that it is quite possible that while we are in any of these
 452  * states, we could receive a 'SYN' request from the other peer.
 453  * We then enter a 'weird' state where we pursue our own primary state
 454  * machine (as described above), but with the 'send_connect_ack' flag
 455  * set to 1.  If our state machine allows us to send a 'SYN_ACK'
 456  * (because we have an acceptable address), we send the 'SYN_ACK'
 457  * and set the 'send_connect_ack' to 2.  If we then receive a
 458  * 'ACK', we go to #GNUNET_TRANSPORT_PS_CONNECTED (and reset 'send_connect_ack'
 459  * to 0).
 460  *
 461  */
 462 enum GNUNET_TRANSPORT_PeerState
 463 {
 464   /**
 465    * Fresh peer or completely disconnected
 466    */
 467   GNUNET_TRANSPORT_PS_NOT_CONNECTED = 0,
 468
 469   /**
 470    * Asked to initiate connection, trying to get address from ATS
 471    */
 472   GNUNET_TRANSPORT_PS_INIT_ATS,
 473
 474   /**
 475    * Sent SYN message to other peer, waiting for SYN_ACK
 476    */
 477   GNUNET_TRANSPORT_PS_SYN_SENT,
 478
 479   /**
 480    * Received a SYN, asking ATS about address suggestions.
 481    */
 482   GNUNET_TRANSPORT_PS_SYN_RECV_ATS,
 483
 484   /**
 485    * SYN request from other peer was SYN_ACK'ed, waiting for ACK.
 486    */
 487   GNUNET_TRANSPORT_PS_SYN_RECV_ACK,
 488
 489   /**
 490    * Got our SYN_ACK/ACK, connection is up.
 491    */
 492   GNUNET_TRANSPORT_PS_CONNECTED,
 493
 494   /**
 495    * Connection got into trouble, rest of the system still believes
 496    * it to be up, but we're getting a new address from ATS.
 497    */
 498   GNUNET_TRANSPORT_PS_RECONNECT_ATS,
 499
 500   /**
 501    * Sent SYN over new address (either by ATS telling us to switch
 502    * addresses or from RECONNECT_ATS); if this fails, we need to tell
 503    * the rest of the system about a disconnect.
 504    */
 505   GNUNET_TRANSPORT_PS_RECONNECT_SENT,
 506
 507   /**
 508    * We have some primary connection, but ATS suggested we switch
 509    * to some alternative; we now sent a SYN message for the
 510    * alternative session to the other peer and waiting for a
 511    * SYN_ACK to make this our primary connection.
 512    */
 513   GNUNET_TRANSPORT_PS_SWITCH_SYN_SENT,
 514
 515   /**
 516    * Disconnect in progress (we're sending the DISCONNECT message to the
 517    * other peer; after that is finished, the state will be cleaned up).
 518    */
 519   GNUNET_TRANSPORT_PS_DISCONNECT,
 520
 521   /**
 522    * We're finished with the disconnect; and are cleaning up the state
 523    * now!  We put the struct into this state when we are really in the
 524    * task that calls 'free' on it and are about to remove the record
 525    * from the map.  We should never find a 'struct NeighbourMapEntry'
 526    * in this state in the map.  Accessing a 'struct NeighbourMapEntry'
 527    * in this state virtually always means using memory that has been
 528    * freed (the exception being the cleanup code in #free_neighbour()).
 529    */
 530   GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED
 531 };
 532
 533
 534 /**
 535  * Convert a transport state to a human readable string.
 536  *
 537  * @param state the state
 538  */
 539 const char *
 540 GNUNET_TRANSPORT_ps2s (enum GNUNET_TRANSPORT_PeerState state);
 541
 542
 543 /**
 544  * Check if a state is defined as connected
 545  *
 546  * @param state the state value
 547  * @return #GNUNET_YES or #GNUNET_NO
 548  */
 549 int
 550 GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState state);
 551
 552
 553 /**
 554  * Handle for a #GNUNET_TRANSPORT_monitor_peers operation.
 555  */
 556 struct GNUNET_TRANSPORT_PeerMonitoringContext;
 557
 558
 559 /**
 560  * Function to call with information about a peer
 561  *
 562  * If one_shot was set to #GNUNET_YES to iterate over all peers once,
 563  * a final call with NULL for peer and address will follow when done.
 564  * In this case state and timeout do not contain valid values.
 565  *
 566  * The #GNUNET_TRANSPORT_monitor_peers_cancel() call MUST not be called from
 567  * within this function!
 568  *
 569  *
 570  * @param cls closure
 571  * @param peer peer this update is about,
 572  *      NULL if this is the final last callback for a iteration operation
 573  * @param address address, NULL if this is the final callback for iteration op
 574  * @param state current state this peer is in
 575  * @param state_timeout timeout for the current state of the peer
 576  */
 577 typedef void
 578 (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls,
 579                                          const struct GNUNET_PeerIdentity *peer,
 580                                          const struct GNUNET_HELLO_Address *address,
 581                                          enum GNUNET_TRANSPORT_PeerState state,
 582                                          struct GNUNET_TIME_Absolute state_timeout);
 583
 584
 585 /**
 586  * Return information about a specific peer or all peers currently known to
 587  * transport service once or in monitoring mode. To obtain information about
 588  * a specific peer, a peer identity can be passed. To obtain information about
 589  * all peers currently known to transport service, NULL can be passed as peer
 590  * identity.
 591  *
 592  * For each peer, the callback is called with information about the address used
 593  * to communicate with this peer, the state this peer is currently in and the
 594  * the current timeout for this state.
 595  *
 596  * Upon completion, the #GNUNET_TRANSPORT_PeerIterateCallback is called one
 597  * more time with `NULL`. After this, the operation must no longer be
 598  * explicitly canceled.
 599  *
 600  * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the
 601  * the peer_callback!
 602  *
 603  * @param cfg configuration to use
 604  * @param peer a specific peer identity to obtain information for,
 605  *      NULL for all peers
 606  * @param one_shot #GNUNET_YES to return the current state and then end (with NULL+NULL),
 607  *                 #GNUNET_NO to monitor peers continuously
 608  * @param timeout how long is the lookup allowed to take at most
 609  * @param peer_callback function to call with the results
 610  * @param peer_callback_cls closure for @a peer_callback
 611  */
 612 struct GNUNET_TRANSPORT_PeerMonitoringContext *
 613 GNUNET_TRANSPORT_monitor_peers (const struct GNUNET_CONFIGURATION_Handle *cfg,
 614                                 const struct GNUNET_PeerIdentity *peer,
 615                                 int one_shot,
 616                                 struct GNUNET_TIME_Relative timeout,
 617                                 GNUNET_TRANSPORT_PeerIterateCallback peer_callback,
 618                                 void *peer_callback_cls);
 619
 620
 621 /**
 622  * Cancel request to monitor peers
 623  *
 624  * @param pic handle for the request to cancel
 625  */
 626 void
 627 GNUNET_TRANSPORT_monitor_peers_cancel (struct GNUNET_TRANSPORT_PeerMonitoringContext *pic);
 628
 629
 630 /**
 631  * Handle for a #GNUNET_TRANSPORT_monitor_validation_entries() operation.
 632  */
 633 struct GNUNET_TRANSPORT_ValidationMonitoringContext;
 634
 635
 636 /**
 637  * Current state of a validation process.
 638  *
 639  * FIXME: what state is used to indicate that a validation
 640  * was successful? If that is clarified/determined, "UGH" in
 641  * ~gnunet-peerinfo-gtk.c:1103 should be resolved.
 642  */
 643 enum GNUNET_TRANSPORT_ValidationState
 644 {
 645   /**
 646    * Undefined state
 647    *
 648    * Used for final callback indicating operation done
 649    */
 650   GNUNET_TRANSPORT_VS_NONE,
 651
 652   /**
 653    * Fresh validation entry
 654    *
 655    * Entry was just created, no validation process was executed
 656    */
 657   GNUNET_TRANSPORT_VS_NEW,
 658
 659   /**
 660    * Updated validation entry
 661    *
 662    * This is an update for an existing validation entry
 663    */
 664   GNUNET_TRANSPORT_VS_UPDATE,
 665
 666   /**
 667    * Timeout for validation entry
 668    *
 669    * A timeout occured during the validation process
 670    */
 671   GNUNET_TRANSPORT_VS_TIMEOUT,
 672
 673   /**
 674    * Validation entry is removed
 675    *
 676    * The validation entry is getting removed due to a failed validation
 677    */
 678   GNUNET_TRANSPORT_VS_REMOVE
 679 };
 680
 681
 682 /**
 683  * Function to call with validation information about a peer
 684  *
 685  * This function is called by the transport validation monitoring api to
 686  * indicate a change to a validation entry. The information included represent
 687  * the current state of the validation entry,
 688  *
 689  * If the monitoring was called with `one_shot==GNUNET_YES`, a final callback
 690  * with `address==NULL` is executed.
 691  *
 692  * @param cls closure
 693  * @param address address this update is about,
 694  *      NULL if this is the final last callback for a iteration operation
 695  * @param last_validation when was this address last validated
 696  * @param valid_until when does this address expire
 697  * @param next_validation time of the next validation operation
 698  * @param state state in the validation state machine
 699  */
 700 typedef void
 701 (*GNUNET_TRANSPORT_ValidationIterateCallback) (void *cls,
 702                                                const struct GNUNET_HELLO_Address *address,
 703                                                struct GNUNET_TIME_Absolute last_validation,
 704                                                struct GNUNET_TIME_Absolute valid_until,
 705                                                struct GNUNET_TIME_Absolute next_validation,
 706                                                enum GNUNET_TRANSPORT_ValidationState state);
 707
 708
 709 /**
 710  * Convert validation state to human-readable string.
 711  *
 712  * @param state the state value
 713  * @return corresponding string
 714  */
 715 const char *
 716 GNUNET_TRANSPORT_vs2s (enum GNUNET_TRANSPORT_ValidationState state);
 717
 718
 719 /**
 720  * Return information about pending address validation operations for a specific
 721  * or all peers
 722  *
 723  * @param cfg configuration to use
 724  * @param peer a specific peer identity to obtain validation entries for,
 725  *      NULL for all peers
 726  * @param one_shot #GNUNET_YES to return all entries and then end (with NULL+NULL),
 727  *                 #GNUNET_NO to monitor validation entries continuously
 728  * @param timeout how long is the lookup allowed to take at most
 729  * @param validation_callback function to call with the results
 730  * @param validation_callback_cls closure for @a validation_callback
 731  */
 732 struct GNUNET_TRANSPORT_ValidationMonitoringContext *
 733 GNUNET_TRANSPORT_monitor_validation_entries (const struct GNUNET_CONFIGURATION_Handle *cfg,
 734                                              const struct GNUNET_PeerIdentity *peer,
 735                                              int one_shot,
 736                                              struct GNUNET_TIME_Relative timeout,
 737                                              GNUNET_TRANSPORT_ValidationIterateCallback validation_callback,
 738                                              void *validation_callback_cls);
 739
 740
 741 /**
 742  * Return information about all current pending validation operations
 743  *
 744  * @param vic handle for the request to cancel
 745  */
 746 void
 747 GNUNET_TRANSPORT_monitor_validation_entries_cancel (struct GNUNET_TRANSPORT_ValidationMonitoringContext *vic);
 748
 749
 750 /* *********************** Blacklisting ************************ */
 751
 752 /**
 753  * Handle for blacklisting peers.
 754  */
 755 struct GNUNET_TRANSPORT_Blacklist;
 756
 757
 758 /**
 759  * Function that decides if a connection is acceptable or not.
 760  *
 761  * @param cls closure
 762  * @param pid peer to approve or disapproave
 763  * @return #GNUNET_OK if the connection is allowed, #GNUNET_SYSERR if not
 764  */
 765 typedef int
 766 (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls,
 767                                        const struct GNUNET_PeerIdentity *pid);
 768
 769
 770 /**
 771  * Install a blacklist callback.  The service will be queried for all
 772  * existing connections as well as any fresh connections to check if
 773  * they are permitted.  If the blacklisting callback is unregistered,
 774  * all hosts that were denied in the past will automatically be
 775  * whitelisted again.  Cancelling the blacklist handle is also the
 776  * only way to re-enable connections from peers that were previously
 777  * blacklisted.
 778  *
 779  * @param cfg configuration to use
 780  * @param cb callback to invoke to check if connections are allowed
 781  * @param cb_cls closure for @a cb
 782  * @return NULL on error, otherwise handle for cancellation
 783  */
 784 struct GNUNET_TRANSPORT_Blacklist *
 785 GNUNET_TRANSPORT_blacklist (const struct GNUNET_CONFIGURATION_Handle *cfg,
 786                             GNUNET_TRANSPORT_BlacklistCallback cb,
 787                             void *cb_cls);
 788
 789
 790 /**
 791  * Abort the blacklist.  Note that this function is the only way for
 792  * removing a peer from the blacklist.
 793  *
 794  * @param br handle of the request that is to be cancelled
 795  */
 796 void
 797 GNUNET_TRANSPORT_blacklist_cancel (struct GNUNET_TRANSPORT_Blacklist *br);
 798
 799
 800 /**
 801  * Handle for a plugin session state monitor.
 802  */
 803 struct GNUNET_TRANSPORT_PluginMonitor;
 804
 805 /**
 806  * Abstract representation of a plugin's session.
 807  * Corresponds to the `struct GNUNET_ATS_Session` within the TRANSPORT service.
 808  */
 809 struct GNUNET_TRANSPORT_PluginSession;
 810
 811
 812 /**
 813  * Possible states of a session in a plugin.
 814  */
 815 enum GNUNET_TRANSPORT_SessionState
 816 {
 817
 818   /**
 819    * The session was created (first call for each session object).
 820    */
 821   GNUNET_TRANSPORT_SS_INIT,
 822
 823   /**
 824    * Initial session handshake is in progress.
 825    */
 826   GNUNET_TRANSPORT_SS_HANDSHAKE,
 827
 828   /**
 829    * Session is fully UP.
 830    */
 831   GNUNET_TRANSPORT_SS_UP,
 832
 833   /**
 834    * This is just an update about the session,
 835    * the state did not change.
 836    */
 837   GNUNET_TRANSPORT_SS_UPDATE,
 838
 839   /**
 840    * Session is being torn down and about to disappear.
 841    * Last call for each session object.
 842    */
 843   GNUNET_TRANSPORT_SS_DONE
 844
 845 };
 846
 847
 848 /**
 849  * Information about a plugin's session.
 850  */
 851 struct GNUNET_TRANSPORT_SessionInfo
 852 {
 853
 854   /**
 855    * New state of the session.
 856    */
 857   enum GNUNET_TRANSPORT_SessionState state;
 858
 859   /**
 860    * #GNUNET_YES if this is an inbound connection,
 861    * #GNUNET_NO if this is an outbound connection,
 862    * #GNUNET_SYSERR if connections of this plugin
 863    *             are so fundamentally bidirectional
 864    *             that they have no 'initiator'
 865    */
 866   int is_inbound;
 867
 868   /**
 869    * Number of messages pending transmission for this session.
 870    */
 871   uint32_t num_msg_pending;
 872
 873   /**
 874    * Number of bytes pending transmission for this session.
 875    */
 876   uint32_t num_bytes_pending;
 877
 878   /**
 879    * Until when does this plugin refuse to receive to manage
 880    * staying within the inbound quota?  ZERO if receive is
 881    * active.
 882    */
 883   struct GNUNET_TIME_Absolute receive_delay;
 884
 885   /**
 886    * At what time will this session timeout (unless activity
 887    * happens)?
 888    */
 889   struct GNUNET_TIME_Absolute session_timeout;
 890
 891   /**
 892    * Address used by the session.  Can be NULL if none is available.
 893    */
 894   const struct GNUNET_HELLO_Address *address;
 895 };
 896
 897
 898 /**
 899  * Function called by the plugin with information about the
 900  * current sessions managed by the plugin (for monitoring).
 901  *
 902  * @param cls closure
 903  * @param session session handle this information is about,
 904  *        NULL to indicate that we are "in sync" (initial
 905  *        iteration complete)
 906  * @param session_ctx storage location where the application
 907  *        can store data; will point to NULL on #GNUNET_TRANSPORT_SS_INIT,
 908  *        and must be reset to NULL on #GNUNET_TRANSPORT_SS_DONE
 909  * @param info information about the state of the session,
 910  *        NULL if @a session is also NULL and we are
 911  *        merely signalling that the initial iteration is over;
 912  *        NULL with @a session being non-NULL if the monitor
 913  *        was being cancelled while sessions were active
 914  */
 915 typedef void
 916 (*GNUNET_TRANSPORT_SessionMonitorCallback) (void *cls,
 917                                             struct GNUNET_TRANSPORT_PluginSession *session,
 918                                             void **session_ctx,
 919                                             const struct GNUNET_TRANSPORT_SessionInfo *info);
 920
 921
 922 /**
 923  * Install a plugin session state monitor callback.  The callback
 924  * will be notified whenever the session changes.
 925  *
 926  * @param cfg configuration to use
 927  * @param cb callback to invoke on events
 928  * @param cb_cls closure for @a cb
 929  * @return NULL on error, otherwise handle for cancellation
 930  */
 931 struct GNUNET_TRANSPORT_PluginMonitor *
 932 GNUNET_TRANSPORT_monitor_plugins (const struct GNUNET_CONFIGURATION_Handle *cfg,
 933                                   GNUNET_TRANSPORT_SessionMonitorCallback cb,
 934                                   void *cb_cls);
 935
 936
 937 /**
 938  * Cancel monitoring the plugin session state.  The callback will be
 939  * called once for each session that is up with the "info" argument
 940  * being NULL (this is just to enable client-side cleanup).
 941  *
 942  * @param pm handle of the request that is to be cancelled
 943  */
 944 void
 945 GNUNET_TRANSPORT_monitor_plugins_cancel (struct GNUNET_TRANSPORT_PluginMonitor *pm);
 946
 947
 948
 949 #if 0                           /* keep Emacsens' auto-indent happy */
 950 {
 951 #endif
 952 #ifdef __cplusplus
 953 }
 954 #endif
 955
 956 /* ifndef GNUNET_TRANSPORT_SERVICE_H */
 957 #endif
 958
 959 /** @} */  /* end of group */
 960
 961 /* end of gnunet_transport_service.h */