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