src/include/gnunet_transport_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009, 2010, 2011 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_transport_service.h
  23  * @brief low-level P2P IO
  24  * @author Christian Grothoff
  25  */
  26
  27 #ifndef GNUNET_TRANSPORT_SERVICE_H
  28 #define GNUNET_TRANSPORT_SERVICE_H
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38 #include "gnunet_util_lib.h"
  39 #include "gnunet_ats_service.h"
  40
  41 /**
  42  * Version number of the transport API.
  43  */
  44 #define GNUNET_TRANSPORT_VERSION 0x00000000
  45
  46 enum TRAFFIC_METRIC_DIRECTION
  47 {
  48         TM_SEND = 0,
  49         TM_RECEIVE = 1,
  50         TM_BOTH = 2
  51 };
  52
  53
  54 /**
  55  * Function called by the transport for each received message.
  56  *
  57  * @param cls closure
  58  * @param peer (claimed) identity of the other peer
  59  * @param message the message
  60  * @param ats performance data
  61  * @param ats_count number of entries in ats
  62  */
  63 typedef void (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls,
  64                                                   const struct
  65                                                   GNUNET_PeerIdentity * peer,
  66                                                   const struct
  67                                                   GNUNET_MessageHeader *
  68                                                   message,
  69                                                   const struct
  70                                                   GNUNET_ATS_Information * ats,
  71                                                   uint32_t ats_count);
  72
  73
  74 /**
  75  * Opaque handle to the service.
  76  */
  77 struct GNUNET_TRANSPORT_Handle;
  78
  79
  80 /**
  81  * Function called to notify transport users that another
  82  * peer connected to us.
  83  *
  84  * @param cls closure
  85  * @param peer the peer that connected
  86  * @param ats performance data
  87  * @param ats_count number of entries in ats (excluding 0-termination)
  88  */
  89 typedef void (*GNUNET_TRANSPORT_NotifyConnect) (void *cls,
  90                                                 const struct GNUNET_PeerIdentity
  91                                                 * peer,
  92                                                 const struct
  93                                                 GNUNET_ATS_Information * ats,
  94                                                 uint32_t ats_count);
  95
  96 /**
  97  * Function called to notify transport users that another
  98  * peer disconnected from us.
  99  *
 100  * @param cls closure
 101  * @param peer the peer that disconnected
 102  */
 103 typedef void (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls,
 104                                                    const struct
 105                                                    GNUNET_PeerIdentity * peer);
 106
 107
 108 /**
 109  * Function to call with result of the try connect request.
 110  *
 111  *
 112  * @param cls closure
 113  * @param result GNUNET_OK if message was transmitted to transport service
 114  *               GNUNET_SYSERR if message was not transmitted to transport service
 115  */
 116 typedef void (*GNUNET_TRANSPORT_TryConnectCallback) (void *cls,
 117                                                      const int result);
 118
 119
 120 /**
 121  * Function to call with a textual representation of an address.
 122  * This function will be called several times with different possible
 123  * textual representations, and a last time with NULL to signal the end
 124  * of the iteration.
 125  *
 126  * @param cls closure
 127  * @param address NULL on error or end of iteration,
 128  *        otherwise 0-terminated printable UTF-8 string
 129  */
 130 typedef void (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls,
 131                                                           const char *address);
 132
 133
 134 /**
 135  * Function to call with a binary format of an address
 136  *
 137  * @param cls closure
 138  * @param peer peer this update is about (never NULL)
 139  * @param address address, NULL for disconnect notification in monitor mode
 140  */
 141 typedef void (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls,
 142                                                       const struct
 143                                                       GNUNET_PeerIdentity *
 144                                                       peer,
 145                                                       const struct
 146                                                       GNUNET_HELLO_Address *
 147                                                       address);
 148
 149
 150 /**
 151  * Connect to the transport service.  Note that the connection may
 152  * complete (or fail) asynchronously.
 153  *
 154  * @param cfg configuration to use
 155  * @param self our own identity (API should check that it matches
 156  *             the identity found by transport), or NULL (no check)
 157  * @param cls closure for the callbacks
 158  * @param rec receive function to call
 159  * @param nc function to call on connect events
 160  * @param nd function to call on disconnect events
 161  * @return NULL on error
 162  */
 163 struct GNUNET_TRANSPORT_Handle *
 164 GNUNET_TRANSPORT_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 165                           const struct GNUNET_PeerIdentity *self, void *cls,
 166                           GNUNET_TRANSPORT_ReceiveCallback rec,
 167                           GNUNET_TRANSPORT_NotifyConnect nc,
 168                           GNUNET_TRANSPORT_NotifyDisconnect nd);
 169
 170
 171 /**
 172  * Disconnect from the transport service.
 173  *
 174  * @param handle handle returned from connect
 175  */
 176 void
 177 GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
 178
 179
 180 /**
 181  * Opaque handle for a transmission-ready request.
 182  */
 183 struct GNUNET_TRANSPORT_TryConnectHandle;
 184
 185
 186 /**
 187  * Ask the transport service to establish a connection to
 188  * the given peer.
 189  *
 190  * @param handle connection to transport service
 191  * @param target who we should try to connect to
 192  * @param cb callback to be called when request was transmitted to transport
 193  *         service
 194  * @param cb_cls closure for the callback
 195  * @return a GNUNET_TRANSPORT_TryConnectHandle handle or
 196  *         NULL on failure (cb will not be called)
 197  */
 198 struct GNUNET_TRANSPORT_TryConnectHandle *
 199 GNUNET_TRANSPORT_try_connect (struct GNUNET_TRANSPORT_Handle *handle,
 200                               const struct GNUNET_PeerIdentity *target,
 201                               GNUNET_TRANSPORT_TryConnectCallback cb,
 202                               void *cb_cls);
 203
 204
 205 /**
 206  * Cancel the request to transport to try a connect
 207  * Callback will not be called
 208  *
 209  * @param tch GNUNET_TRANSPORT_TryConnectHandle handle to cancel
 210  */
 211 void
 212 GNUNET_TRANSPORT_try_connect_cancel (struct GNUNET_TRANSPORT_TryConnectHandle *tch);
 213
 214 /**
 215  * Opaque handle for a transmission-ready request.
 216  */
 217 struct GNUNET_TRANSPORT_TransmitHandle;
 218
 219
 220 /**
 221  * Check if we could queue a message of the given size for
 222  * transmission.  The transport service will take both its internal
 223  * buffers and bandwidth limits imposed by the other peer into
 224  * consideration when answering this query.
 225  *
 226  * @param handle connection to transport service
 227  * @param target who should receive the message
 228  * @param size how big is the message we want to transmit?
 229  * @param priority how important is the message? @deprecated - remove?
 230  * @param timeout after how long should we give up (and call
 231  *        notify with buf NULL and size 0)?
 232  * @param notify function to call when we are ready to
 233  *        send such a message
 234  * @param notify_cls closure for notify
 235  * @return NULL if someone else is already waiting to be notified
 236  *         non-NULL if the notify callback was queued (can be used to cancel
 237  *         using GNUNET_TRANSPORT_notify_transmit_ready_cancel)
 238  */
 239 struct GNUNET_TRANSPORT_TransmitHandle *
 240 GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle *handle,
 241                                         const struct GNUNET_PeerIdentity
 242                                         *target, size_t size, uint32_t priority,
 243                                         struct GNUNET_TIME_Relative timeout,
 244                                         GNUNET_CONNECTION_TransmitReadyNotify
 245                                         notify, void *notify_cls);
 246
 247
 248 /**
 249  * Cancel the specified transmission-ready notification.
 250  *
 251  * @param th handle of the transmission notification request to cancel
 252  */
 253 void
 254 GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct
 255                                                GNUNET_TRANSPORT_TransmitHandle
 256                                                *th);
 257
 258
 259
 260 /**
 261  * Function called whenever there is an update to the
 262  * HELLO of this peer.
 263  *
 264  * @param cls closure
 265  * @param hello our updated HELLO
 266  */
 267 typedef void (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls,
 268                                                       const struct
 269                                                       GNUNET_MessageHeader *
 270                                                       hello);
 271
 272
 273 /**
 274  * Handle to cancel a 'GNUNET_TRANSPORT_get_hello' operation.
 275  */
 276 struct GNUNET_TRANSPORT_GetHelloHandle;
 277
 278
 279 /**
 280   * Checks if a neighbour is connected
 281   *
 282   * @param handle connection to transport service
 283   * @peer the peer to check
 284   * @return GNUNET_YES or GNUNET_NO
 285   *
 286   */
 287 int
 288 GNUNET_TRANSPORT_check_neighbour_connected (struct GNUNET_TRANSPORT_Handle *handle,
 289                                                                 const struct GNUNET_PeerIdentity *peer);
 290
 291
 292 /**
 293  * Set transport metrics for a peer and a direction
 294  *
 295  * @param handle transport handle
 296  * @param peer the peer to set the metric for
 297  * @param direction can be: TM_SEND, TM_RECV, TM_BOTH
 298  * @param ats the metric as ATS information
 299  * @param ats_count the number of metrics
 300  *
 301  * Supported ATS values:
 302  * GNUNET_ATS_QUALITY_NET_DELAY  (value in ms)
 303  * GNUNET_ATS_QUALITY_NET_DISTANCE (value in #hops)
 304  *
 305  * Example
 306  * To enforce a delay of 10 ms for peer p1 in sending direction use:
 307  *
 308  * struct GNUNET_ATS_Information ats;
 309  * ats.type = ntohl (GNUNET_ATS_QUALITY_NET_DELAY);
 310  * ats.value = ntohl (10);
 311  * GNUNET_TRANSPORT_set_traffic_metric (th, p1, TM_SEND, &ats, 1);
 312  *
 313  * Note:
 314  * Delay restrictions in receiving direction will be enforced with
 315  * 1 message delay.
 316  */
 317 void
 318 GNUNET_TRANSPORT_set_traffic_metric (struct GNUNET_TRANSPORT_Handle *handle,
 319                                                                                                                                                 const struct GNUNET_PeerIdentity *peer,
 320                                                                                                                                                 int direction,
 321                                                                                                                                                 const struct GNUNET_ATS_Information *ats,
 322                                                                                                                                                 size_t ats_count);
 323
 324
 325 /**
 326  * Obtain updates on changes to the HELLO message for this peer. The callback
 327  * given in this function is never called synchronously.
 328  *
 329  * @param handle connection to transport service
 330  * @param rec function to call with the HELLO
 331  * @param rec_cls closure for rec
 332  * @return handle to cancel the operation
 333  */
 334 struct GNUNET_TRANSPORT_GetHelloHandle *
 335 GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle,
 336                             GNUNET_TRANSPORT_HelloUpdateCallback rec,
 337                             void *rec_cls);
 338
 339
 340 /**
 341  * Stop receiving updates about changes to our HELLO message.
 342  *
 343  * @param ghh handle to cancel
 344  */
 345 void
 346 GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh);
 347
 348
 349 /**
 350  * Offer the transport service the HELLO of another peer.  Note that
 351  * the transport service may just ignore this message if the HELLO is
 352  * malformed or useless due to our local configuration.
 353  *
 354  * @param handle connection to transport service
 355  * @param hello the hello message
 356  * @param cont continuation to call when HELLO has been sent,
 357  *      tc reason GNUNET_SCHEDULER_REASON_TIMEOUT for fail
 358  *      tc reasong GNUNET_SCHEDULER_REASON_READ_READY for success
 359  * @param cls closure for continuation
 360  * @return a GNUNET_TRANSPORT_OfferHelloHandle handle or NULL on failure,
 361  *      in case of failure cont will not be called
 362  *
 363  */
 364 struct GNUNET_TRANSPORT_OfferHelloHandle *
 365 GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle,
 366                               const struct GNUNET_MessageHeader *hello,
 367                               GNUNET_SCHEDULER_Task cont, void *cls);
 368
 369
 370 /**
 371  * Cancel the request to transport to offer the HELLO message
 372  *
 373  * @param ohh the GNUNET_TRANSPORT_OfferHelloHandle to cancel
 374  */
 375 void
 376 GNUNET_TRANSPORT_offer_hello_cancel (struct GNUNET_TRANSPORT_OfferHelloHandle *ohh);
 377
 378 /**
 379  * Handle to cancel a pending address lookup.
 380  */
 381 struct GNUNET_TRANSPORT_AddressToStringContext;
 382
 383
 384 /**
 385  * Convert a binary address into a human readable address.
 386  *
 387  * @param cfg configuration to use
 388  * @param address address to convert (binary format)
 389  * @param numeric should (IP) addresses be displayed in numeric form
 390  *                (otherwise do reverse DNS lookup)
 391  * @param timeout how long is the lookup allowed to take at most
 392  * @param aluc function to call with the results
 393  * @param aluc_cls closure for aluc
 394  * @return handle to cancel the operation, NULL on error
 395  */
 396 struct GNUNET_TRANSPORT_AddressToStringContext *
 397 GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle
 398                                     *cfg,
 399                                     const struct GNUNET_HELLO_Address *address,
 400                                     int numeric,
 401                                     struct GNUNET_TIME_Relative timeout,
 402                                     GNUNET_TRANSPORT_AddressToStringCallback
 403                                     aluc, void *aluc_cls);
 404
 405
 406 /**
 407  * Cancel request for address conversion.
 408  *
 409  * @param alc handle for the request to cancel
 410  */
 411 void
 412 GNUNET_TRANSPORT_address_to_string_cancel (struct
 413                                            GNUNET_TRANSPORT_AddressToStringContext
 414                                            *alc);
 415
 416
 417 /**
 418  * Return all the known addresses for a specific peer or all peers.
 419  * Returns continuously all address if one_shot is set to GNUNET_NO
 420  *
 421  * CHANGE: Returns the address(es) that we are currently using for this
 422  * peer.  Upon completion, the 'AddressLookUpCallback' is called one more
 423  * time with 'NULL' for the address and the peer.  After this, the operation must no
 424  * longer be explicitly cancelled.
 425  *
 426  * @param cfg configuration to use
 427  * @param peer peer identity to look up the addresses of, CHANGE: allow NULL for all (connected) peers
 428  * @param one_shot GNUNET_YES to return the current state and then end (with NULL+NULL),
 429  *                 GNUNET_NO to monitor the set of addresses used (continuously, must be explicitly canceled, NOT implemented yet!)
 430  * @param timeout how long is the lookup allowed to take at most
 431  * @param peer_address_callback function to call with the results
 432  * @param peer_address_callback_cls closure for peer_address_callback
 433  */
 434 struct GNUNET_TRANSPORT_PeerIterateContext *
 435 GNUNET_TRANSPORT_peer_get_active_addresses (const struct
 436                                             GNUNET_CONFIGURATION_Handle *cfg,
 437                                             const struct GNUNET_PeerIdentity
 438                                             *peer, int one_shot,
 439                                             struct GNUNET_TIME_Relative timeout,
 440                                             GNUNET_TRANSPORT_PeerIterateCallback
 441                                             peer_address_callback,
 442                                             void *peer_address_callback_cls);
 443
 444
 445 /**
 446  * Cancel request for peer lookup.
 447  *
 448  * @param alc handle for the request to cancel
 449  */
 450 void
 451 GNUNET_TRANSPORT_peer_get_active_addresses_cancel (struct
 452                                                    GNUNET_TRANSPORT_PeerIterateContext
 453                                                    *alc);
 454
 455
 456 /**
 457  * Handle for blacklisting peers.
 458  */
 459 struct GNUNET_TRANSPORT_Blacklist;
 460
 461
 462 /**
 463  * Function that decides if a connection is acceptable or not.
 464  *
 465  * @param cls closure
 466  * @param pid peer to approve or disapproave
 467  * @return GNUNET_OK if the connection is allowed, GNUNET_SYSERR if not
 468  */
 469 typedef int (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls,
 470                                                    const struct
 471                                                    GNUNET_PeerIdentity * pid);
 472
 473
 474 /**
 475  * Install a blacklist callback.  The service will be queried for all
 476  * existing connections as well as any fresh connections to check if
 477  * they are permitted.  If the blacklisting callback is unregistered,
 478  * all hosts that were denied in the past will automatically be
 479  * whitelisted again.  Cancelling the blacklist handle is also the
 480  * only way to re-enable connections from peers that were previously
 481  * blacklisted.
 482  *
 483  * @param cfg configuration to use
 484  * @param cb callback to invoke to check if connections are allowed
 485  * @param cb_cls closure for cb
 486  * @return NULL on error, otherwise handle for cancellation
 487  */
 488 struct GNUNET_TRANSPORT_Blacklist *
 489 GNUNET_TRANSPORT_blacklist (const struct GNUNET_CONFIGURATION_Handle *cfg,
 490                             GNUNET_TRANSPORT_BlacklistCallback cb,
 491                             void *cb_cls);
 492
 493
 494 /**
 495  * Abort the blacklist.  Note that this function is the only way for
 496  * removing a peer from the blacklist.
 497  *
 498  * @param br handle of the request that is to be cancelled
 499  */
 500 void
 501 GNUNET_TRANSPORT_blacklist_cancel (struct GNUNET_TRANSPORT_Blacklist *br);
 502
 503
 504
 505 #if 0                           /* keep Emacsens' auto-indent happy */
 506 {
 507 #endif
 508 #ifdef __cplusplus
 509 }
 510 #endif
 511
 512 /* ifndef GNUNET_TRANSPORT_SERVICE_H */
 513 #endif
 514 /* end of gnunet_transport_service.h */