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