src/include/gnunet_transport_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2009 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 (excluding 0-termination)
  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
  64                                                   * ats, 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
  87                                                 * ats, 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 a binary format of an address
 103  *
 104  * @param cls closure
 105  * @param address NULL on error, otherwise 0-terminated printable UTF-8 string
 106  */
 107 typedef void (*GNUNET_TRANSPORT_AddressLookUpCallback) (void *cls,
 108                                                         const char *address);
 109
 110
 111 /**
 112  * Function to call with a binary format of an address
 113  *
 114  * @param cls closure
 115  * @param peer peer identity
 116  * @param transport transport plugin
 117  * @param addr address
 118  * @param addrlen address length
 119  */
 120 typedef void (*GNUNET_TRANSPORT_AddressLookUpBinaryCallback) (void *cls,
 121                                                               const struct
 122                                                               GNUNET_PeerIdentity
 123                                                               * peer,
 124                                                               const char
 125                                                               *transport,
 126                                                               const void *addr,
 127                                                               size_t addrlen);
 128
 129
 130 /**
 131  * Connect to the transport service.  Note that the connection may
 132  * complete (or fail) asynchronously.
 133  *
 134  * @param cfg configuration to use
 135  * @param self our own identity (API should check that it matches
 136  *             the identity found by transport), or NULL (no check)
 137  * @param cls closure for the callbacks
 138  * @param rec receive function to call
 139  * @param nc function to call on connect events
 140  * @param nd function to call on disconnect events
 141  * @return NULL on error
 142  */
 143 struct GNUNET_TRANSPORT_Handle *
 144 GNUNET_TRANSPORT_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 145                           const struct GNUNET_PeerIdentity *self, void *cls,
 146                           GNUNET_TRANSPORT_ReceiveCallback rec,
 147                           GNUNET_TRANSPORT_NotifyConnect nc,
 148                           GNUNET_TRANSPORT_NotifyDisconnect nd);
 149
 150
 151 /**
 152  * Disconnect from the transport service.
 153  *
 154  * @param handle handle returned from connect
 155  */
 156 void
 157 GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
 158
 159
 160 /**
 161  * Ask the transport service to establish a connection to
 162  * the given peer.
 163  *
 164  * @param handle connection to transport service
 165  * @param target who we should try to connect to
 166  */
 167 void
 168 GNUNET_TRANSPORT_try_connect (struct GNUNET_TRANSPORT_Handle *handle,
 169                               const struct GNUNET_PeerIdentity *target);
 170
 171
 172 /**
 173  * Set the share of incoming/outgoing bandwidth for the given
 174  * peer to the specified amount.
 175  *
 176  * @param handle connection to transport service
 177  * @param target who's bandwidth quota is being changed
 178  * @param quota_in incoming bandwidth quota
 179  * @param quota_out outgoing bandwidth quota
 180  */
 181 void
 182 GNUNET_TRANSPORT_set_quota (struct GNUNET_TRANSPORT_Handle *handle,
 183                             const struct GNUNET_PeerIdentity *target,
 184                             struct GNUNET_BANDWIDTH_Value32NBO quota_in,
 185                             struct GNUNET_BANDWIDTH_Value32NBO quota_out);
 186
 187
 188 /**
 189  * Opaque handle for a transmission-ready request.
 190  */
 191 struct GNUNET_TRANSPORT_TransmitHandle;
 192
 193
 194 /**
 195  * Check if we could queue a message of the given size for
 196  * transmission.  The transport service will take both its internal
 197  * buffers and bandwidth limits imposed by the other peer into
 198  * consideration when answering this query.
 199  *
 200  * @param handle connection to transport service
 201  * @param target who should receive the message
 202  * @param size how big is the message we want to transmit?
 203  * @param priority how important is the message? @deprecated - remove?
 204  * @param timeout after how long should we give up (and call
 205  *        notify with buf NULL and size 0)?
 206  * @param notify function to call when we are ready to
 207  *        send such a message
 208  * @param notify_cls closure for notify
 209  * @return NULL if someone else is already waiting to be notified
 210  *         non-NULL if the notify callback was queued (can be used to cancel
 211  *         using GNUNET_TRANSPORT_notify_transmit_ready_cancel)
 212  */
 213 struct GNUNET_TRANSPORT_TransmitHandle *
 214 GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle *handle,
 215                                         const struct GNUNET_PeerIdentity
 216                                         *target, size_t size, uint32_t priority,
 217                                         struct GNUNET_TIME_Relative timeout,
 218                                         GNUNET_CONNECTION_TransmitReadyNotify
 219                                         notify, void *notify_cls);
 220
 221
 222 /**
 223  * Cancel the specified transmission-ready notification.
 224  *
 225  * @param th handle of the transmission notification request to cancel
 226  */
 227 void
 228 GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct
 229                                                GNUNET_TRANSPORT_TransmitHandle
 230                                                *th);
 231
 232
 233
 234 /**
 235  * Function called whenever there is an update to the
 236  * HELLO of this peer.
 237  *
 238  * @param cls closure
 239  * @param hello our updated HELLO
 240  */
 241 typedef void (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls,
 242                                                       const struct
 243                                                       GNUNET_MessageHeader *
 244                                                       hello);
 245
 246
 247 /**
 248  * Handle to cancel a 'GNUNET_TRANSPORT_get_hello' operation.
 249  */
 250 struct GNUNET_TRANSPORT_GetHelloHandle;
 251
 252
 253 /**
 254  * Obtain updates on changes to the HELLO message for this peer.
 255  *
 256  * @param handle connection to transport service
 257  * @param rec function to call with the HELLO
 258  * @param rec_cls closure for rec
 259  * @return handle to cancel the operation
 260  */
 261 struct GNUNET_TRANSPORT_GetHelloHandle *
 262 GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle,
 263                             GNUNET_TRANSPORT_HelloUpdateCallback rec,
 264                             void *rec_cls);
 265
 266
 267 /**
 268  * Stop receiving updates about changes to our HELLO message.
 269  *
 270  * @param ghh handle returned from 'GNUNET_TRANSPORT_get_hello')
 271  */
 272 void
 273 GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh);
 274
 275
 276 /**
 277  * Offer the transport service the HELLO of another peer.  Note that
 278  * the transport service may just ignore this message if the HELLO is
 279  * malformed or useless due to our local configuration.
 280  *
 281  * @param handle connection to transport service
 282  * @param hello the hello message
 283  * @param cont continuation to call when HELLO has been sent
 284  * @param cls closure for continuation
 285  */
 286 void
 287 GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle,
 288                               const struct GNUNET_MessageHeader *hello,
 289                               GNUNET_SCHEDULER_Task cont, void *cls);
 290
 291
 292 /**
 293  * Handle to cancel a pending address lookup.
 294  */
 295 struct GNUNET_TRANSPORT_AddressLookupContext;
 296
 297
 298 /**
 299  * Convert a binary address into a human readable address.
 300  *
 301  * @param cfg configuration to use
 302  * @param address address to convert (binary format)
 303  * @param addressLen number of bytes in address
 304  * @param numeric should (IP) addresses be displayed in numeric form
 305  *                (otherwise do reverse DNS lookup)
 306  * @param nameTrans name of the transport to which the address belongs
 307  * @param timeout how long is the lookup allowed to take at most
 308  * @param aluc function to call with the results
 309  * @param aluc_cls closure for aluc
 310  * @return handle to cancel the operation, NULL on error
 311  */
 312 struct GNUNET_TRANSPORT_AddressLookupContext *
 313 GNUNET_TRANSPORT_address_lookup (const struct GNUNET_CONFIGURATION_Handle *cfg,
 314                                  const char *address, size_t addressLen,
 315                                  int numeric, const char *nameTrans,
 316                                  struct GNUNET_TIME_Relative timeout,
 317                                  GNUNET_TRANSPORT_AddressLookUpCallback aluc,
 318                                  void *aluc_cls);
 319
 320
 321 /**
 322  * Cancel request for address conversion.
 323  *
 324  * @param alc handle for the request to cancel
 325  */
 326 void
 327 GNUNET_TRANSPORT_address_lookup_cancel (struct
 328                                         GNUNET_TRANSPORT_AddressLookupContext
 329                                         *alc);
 330
 331
 332 /**
 333  * Handle to cancel a pending address lookup.
 334  */
 335 struct GNUNET_TRANSPORT_AddressLookupContext;
 336
 337
 338 /**
 339  * Return all the known addresses for a peer. FIXME: document better!
 340  * FIXME: use better name!
 341  *
 342  * @param cfg configuration to use
 343  * @param peer peer identity to look up the addresses of
 344  * @param timeout how long is the lookup allowed to take at most
 345  * @param peer_address_callback function to call with the results
 346  * @param peer_address_callback_cls closure for peer_address_callback
 347  */
 348 struct GNUNET_TRANSPORT_PeerAddressLookupContext *
 349 GNUNET_TRANSPORT_peer_address_lookup (const struct GNUNET_CONFIGURATION_Handle
 350                                       *cfg,
 351                                       const struct GNUNET_PeerIdentity *peer,
 352                                       struct GNUNET_TIME_Relative timeout,
 353                                       GNUNET_TRANSPORT_AddressLookUpCallback
 354                                       peer_address_callback,
 355                                       void *peer_address_callback_cls);
 356
 357
 358 /**
 359  * Cancel request for peer lookup.
 360  *
 361  * @param alc handle for the request to cancel
 362  */
 363 void
 364 GNUNET_TRANSPORT_peer_address_lookup_cancel (struct
 365                                              GNUNET_TRANSPORT_PeerAddressLookupContext
 366                                              *alc);
 367
 368
 369 /**
 370  * Return all the known addresses. FIXME: document better!
 371  * FIXME: use better name! FIXME: extend API to allow cancellation!
 372  *
 373  * @param cfg configuration to use
 374  * @param timeout how long is the lookup allowed to take at most
 375  * @param peer_address_callback function to call with the results
 376  * @param peer_address_callback_cls closure for peer_address_callback
 377  */
 378 void
 379 GNUNET_TRANSPORT_address_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg,
 380                                   struct GNUNET_TIME_Relative timeout,
 381                                   GNUNET_TRANSPORT_AddressLookUpBinaryCallback
 382                                   peer_address_callback,
 383                                   void *peer_address_callback_cls);
 384
 385
 386 /**
 387  * Handle for blacklisting peers.
 388  */
 389 struct GNUNET_TRANSPORT_Blacklist;
 390
 391
 392 /**
 393  * Function that decides if a connection is acceptable or not.
 394  *
 395  * @param cls closure
 396  * @param pid peer to approve or disapproave
 397  * @return GNUNET_OK if the connection is allowed
 398  */
 399 typedef int (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls,
 400                                                    const struct
 401                                                    GNUNET_PeerIdentity * pid);
 402
 403
 404 /**
 405  * Install a blacklist callback.  The service will be queried for all
 406  * existing connections as well as any fresh connections to check if
 407  * they are permitted.  If the blacklisting callback is unregistered,
 408  * all hosts that were denied in the past will automatically be
 409  * whitelisted again.  Cancelling the blacklist handle is also the
 410  * only way to re-enable connections from peers that were previously
 411  * blacklisted.
 412  *
 413  * @param cfg configuration to use
 414  * @param cb callback to invoke to check if connections are allowed
 415  * @param cb_cls closure for cb
 416  * @return NULL on error, otherwise handle for cancellation
 417  */
 418 struct GNUNET_TRANSPORT_Blacklist *
 419 GNUNET_TRANSPORT_blacklist (const struct GNUNET_CONFIGURATION_Handle *cfg,
 420                             GNUNET_TRANSPORT_BlacklistCallback cb,
 421                             void *cb_cls);
 422
 423
 424 /**
 425  * Abort the blacklist.  Note that this function is the only way for
 426  * removing a peer from the blacklist.
 427  *
 428  * @param br handle of the request that is to be cancelled
 429  */
 430 void
 431 GNUNET_TRANSPORT_blacklist_cancel (struct GNUNET_TRANSPORT_Blacklist *br);
 432
 433
 434
 435 #if 0                           /* keep Emacsens' auto-indent happy */
 436 {
 437 #endif
 438 #ifdef __cplusplus
 439 }
 440 #endif
 441
 442 /* ifndef GNUNET_TRANSPORT_SERVICE_H */
 443 #endif
 444 /* end of gnunet_transport_service.h */