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