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_bandwidth_lib.h"
  39 #include "gnunet_configuration_lib.h"
  40 #include "gnunet_crypto_lib.h"
  41 #include "gnunet_connection_lib.h"
  42 #include "gnunet_scheduler_lib.h"
  43 #include "gnunet_time_lib.h"
  44
  45 /**
  46  * Version number of the transport API.
  47  */
  48 #define GNUNET_TRANSPORT_VERSION 0x00000000
  49
  50
  51 /**
  52  * Enum defining all known property types for ATS Enum values are used
  53  * in the GNUNET_TRANSPORT_ATS_Information struct as
  54  * (key,value)-pairs.
  55  *
  56  * Cost are always stored in uint32_t, so all units used to define costs
  57  * have to be normalized to fit in uint32_t [0 .. 4.294.967.295]
  58  *
  59  * To keep the elements ordered
  60  *    1..1024 : Values with a relation to cost
  61  * 1025..2048 : Values with a relation to quality
  62  * 2049..3072 : Values with a relation to availability
  63  *
  64  */
  65 enum GNUNET_TRANSPORT_ATS_Property
  66 {
  67
  68   /**
  69    * End of the array.
  70    */
  71   GNUNET_TRANSPORT_ATS_ARRAY_TERMINATOR = 0,
  72
  73   /* Cost related values */
  74   /* =================== */
  75
  76   /**
  77    * Volume based cost in financial units to transmit data
  78    *
  79    * Note: This value is not bound to a specific currency or unit and only
  80    * used locally.
  81    * "cent" just refers the smallest amount of money in the respective
  82    * currency.
  83    *
  84    * Unit: [cent/MB]
  85    *
  86    * Interpretation: less is better
  87    *
  88    * Examples:
  89    * LAN:  0 [cent/MB]
  90    * 2G : 10 [cent/MB]
  91    */
  92   GNUNET_TRANSPORT_ATS_COST_FINANCIAL_PER_VOLUME = 1,
  93
  94   /**
  95    * Time based cost in financial units to transmit data
  96    *
  97    * Note: This value is not bound to a specific currency or unit and only
  98    * used locally.
  99    * "cent" just refers the smallest amount of money in the respective
 100    * currency.
 101    *
 102    * Unit: [cent/h]
 103    *
 104    * Interpretation: less is better
 105    *
 106    * Examples:
 107    * LAN   :  0 [cent/h]
 108    * Dialup: 10 [cent/h]
 109    */
 110   GNUNET_TRANSPORT_ATS_COST_FINANCIAL_PER_TIME = 2,
 111
 112   /**
 113    * Computational costs
 114    *
 115    * Effort of preparing data to be sent with this transport
 116    * Includes encoding, encryption and conversion of data
 117    * Partial values can be summed up: c_sum = c_enc + c_enc + c_conv
 118    * Resulting values depend on local system properties, e.g. CPU
 119    *
 120    * Unit: [ms/GB]
 121    *
 122    * Interpretation: less is better
 123    *
 124    * Examples:
 125    *
 126    * HTTPS with AES CBC-256:    7,382
 127    * HTTPS with AES CBC-128:    5,279
 128    * HTTPS with RC4-1024:       2,652
 129    */
 130   GNUNET_TRANSPORT_ATS_COST_COMPUTATIONAL = 3,
 131
 132   /**
 133    * Energy consumption
 134    *
 135    * Energy consumption using this transport when sending with a certain
 136    * power at a certain bitrate. This is only an approximation based on:
 137    * Energy consumption E = P / D
 138    *
 139    * with:
 140    * Power P in Watt (J/s)
 141    * Datarate D in MBit/s
 142    *
 143    * Conversion between power P and dBm used by WLAN in radiotap's dBm TX power:
 144    *
 145    * Lp(dbm) = 10 log10 (P/ 1mW)
 146    *
 147    * => P = 1 mW  * 10^(Lp(dbm)/10)
 148    *
 149    * Unit: [mJ/MB]
 150    *
 151    * Interpretation: less is better
 152    *
 153    * Examples:
 154    *
 155    * LAN:       0
 156    * WLAN:      89 (600 mW @ 802.11g /w 54 MBit/s)
 157    * Bluetooth: 267 (100 mW @ BT2.0 EDR /w 3 MBit/s)
 158    */
 159   GNUNET_TRANSPORT_ATS_COST_ENERGY_CONSUMPTION = 4,
 160
 161   /**
 162    * Connect cost
 163    * How many bytes are transmitted to initiate a new connection using
 164    * this transport?
 165    *
 166    * Unit: [bytes]
 167    *
 168    * Interpretation: less is better
 169    *
 170    * Examples:
 171    *
 172    * UDP (No connection)      :
 173    *     0 bytes
 174    * TCP (TCP 3-Way handshake):
 175    *   220 bytes Ethernet,  172 bytes TCP/IP,  122 bytes TCP
 176    * HTTP (TCP + Header)      :
 177    *   477 bytes Ethernet,  429 bytes TCP/IP,  374 bytes TCP,  278 bytes HTTP
 178    * HTTPS  HTTP+TLS Handshake:
 179    *  2129 bytes Ethernet, 1975 bytes TCP/IP, 1755 bytes TCP, 1403 bytes HTTPS
 180    *
 181    * */
 182   GNUNET_TRANSPORT_ATS_COST_CONNECT = 5,
 183
 184   /**
 185    * Bandwidth cost
 186    *
 187    * How many bandwidth is available to consume?
 188    * Used to calculate which impact sending data with this transport has
 189    *
 190    * Unit: [kB/s]
 191    *
 192    * Interpretation: more is better
 193    *
 194    * Examples:
 195    * LAN:     12,800  (100 MBit/s)
 196    * WLAN:    6,912   (54 MBit/s)
 197    * Dial-up: 8       (64 Kbit/s)
 198    *
 199    */
 200   GNUNET_TRANSPORT_ATS_COST_BANDWITH_AVAILABLE = 6,
 201
 202   /**
 203    *  Network overhead
 204    *
 205    * How many bytes are sent over the wire when 1 kilobyte (1024 bytes)
 206    * of application data is transmitted?
 207    * A factor used with connect cost, bandwidth cost and energy cost
 208    * to describe the overhead produced by the transport protocol
 209    *
 210    * Unit: [bytes/kb]
 211    *
 212    * Interpretation: less is better
 213    *
 214    * Examples:
 215    *
 216    * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
 217    * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
 218    * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8  = 1090 [bytes/kb]
 219    * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8  = 1110 [bytes/kb]
 220    */
 221   GNUNET_TRANSPORT_ATS_COST_NETWORK_OVERHEAD = 7,
 222
 223
 224   /* Quality related values */
 225   /* ====================== */
 226
 227   /* Physical layer quality properties */
 228
 229   /**
 230    * Signal strength on physical layer
 231    *
 232    * Unit: [dBm]
 233    */
 234   GNUNET_TRANSPORT_ATS_QUALITY_PHY_SIGNAL_STRENGTH = 1025,
 235
 236   /**
 237    * Collision rate on physical layer
 238    *
 239    * Unit: [B/s]
 240    */
 241   GNUNET_TRANSPORT_ATS_QUALITY_PHY_COLLISION_RATE = 1026,
 242
 243   /**
 244    * Error rate on physical layer
 245    *
 246    * Unit: [B/s]
 247    */
 248   GNUNET_TRANSPORT_ATS_QUALITY_PHY_ERROR_RATE = 1027,
 249
 250   /* Network layer quality properties */
 251
 252   /**
 253    * Delay
 254    * Time between when the time packet is sent and the packet arrives
 255    *
 256    * Unit: [ms]
 257    *
 258    * Examples:
 259    *
 260    * LAN   :    1
 261    * WLAN  :    2
 262    * Dialup:  500
 263    */
 264   GNUNET_TRANSPORT_ATS_QUALITY_NET_DELAY = 1028,
 265
 266   /**
 267    * Jitter
 268    * Time variations of the delay
 269    * 1st derivative of a delay function
 270    *
 271    * Unit: [ms]
 272    */
 273   GNUNET_TRANSPORT_ATS_QUALITY_NET_JITTER = 1029,
 274
 275   /**
 276    * Error rate on network layer
 277    *
 278    * Unit: [B/s]
 279    *
 280    * Examples:
 281    *
 282    * LAN       :    0
 283    * WLAN      :  400
 284    * Bluetooth :  100
 285    * Note: This numbers are just assumptions as an example, not
 286    * measured or somehow determined
 287    */
 288   GNUNET_TRANSPORT_ATS_QUALITY_NET_ERRORRATE = 1030,
 289
 290   /**
 291    * Drop rate on network layer
 292    * Bytes actively dismissed by a network component during transmission
 293    * Reasons for dropped data can be full queues, congestion, quota violations...
 294    *
 295    * Unit: [B/s]
 296    *
 297    * Examples:
 298    *
 299    * LAN       :    0
 300    * WLAN      :  400
 301    * Bluetooth :  100
 302    * Note: This numbers are just assumptions as an example, not
 303    * measured or somehow determined
 304    */
 305   GNUNET_TRANSPORT_ATS_QUALITY_NET_DROPRATE = 1031,
 306
 307   /**
 308    * Loss rate on network layer
 309    * Bytes lost during transmission
 310    * Reasons can be collisions, ...
 311    *
 312    * Unit: [B/s]
 313    *
 314    * Examples:
 315    *
 316    * LAN       :    0
 317    * WLAN      :   40
 318    * Bluetooth :   10
 319    * Note: This numbers are just assumptions as an example, not measured
 320    * or somehow determined
 321    */
 322   GNUNET_TRANSPORT_ATS_QUALITY_NET_LOSSRATE = 1032,
 323
 324   /**
 325    * Throughput on network layer
 326    *
 327    * Unit: [kB/s]
 328    *
 329    * Examples:
 330    *
 331    * LAN   : 3400
 332    * WLAN  : 1200
 333    * Dialup:      4
 334    *
 335    */
 336   GNUNET_TRANSPORT_ATS_QUALITY_NET_THROUGHPUT = 1033,
 337
 338  /**
 339   * Distance on network layer
 340   *
 341   * Unit: []
 342   */
 343   GNUNET_TRANSPORT_ATS_QUALITY_NET_DISTANCE = 1034,
 344
 345
 346   /* Availability related values */
 347   /* =========================== */
 348
 349   /**
 350    * Is a peer reachable?
 351    */
 352   GNUNET_TRANSPORT_ATS_AVAILABILITY_REACHABLE = 2048,
 353
 354   /**
 355    * Is there a connection established to a peer using this transport
 356    */
 357   GNUNET_TRANSPORT_ATS_AVAILABILITY_CONNECTED = 2049
 358 };
 359
 360
 361 /**
 362  * struct used to communicate the transport's properties like cost and
 363  * quality of service as well as high-level constraints on resource
 364  * consumption.
 365  *
 366  *                             +---+
 367  *  +-----------+ Constraints  |   |  Plugin properties +---------+
 368  *  | Highlevel |------------> |ATS| <------------------|Transport|
 369  *  | Component | ATS struct   |   |    ATS struct      | Plugin  |
 370  *  +-----------+              |   |                    +---------+
 371  *                             +---+
 372  *
 373  * This structure will be used by transport plugins to communicate
 374  * costs to ATS or by higher level components to tell ATS their
 375  * constraints.  Always a pair of (GNUNET_TRANSPORT_ATS_Property,
 376  * uint32_t value).  Value is always uint32_t, so all units used to
 377  * define costs have to be normalized to fit uint32_t.
 378  */
 379 struct GNUNET_TRANSPORT_ATS_Information
 380 {
 381   /**
 382    * ATS property type, in network byte order.
 383    */
 384   uint32_t type;
 385
 386   /**
 387    * ATS property value, in network byte order.
 388    */
 389   uint32_t value;
 390 };
 391
 392
 393
 394 /**
 395  * Function called by the transport for each received message.
 396  *
 397  * @param cls closure
 398  * @param peer (claimed) identity of the other peer
 399  * @param message the message
 400  * @param ats performance data
 401  * @param ats_count number of entries in ats (excluding 0-termination)
 402  */
 403 typedef void (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls,
 404                                                   const struct
 405                                                   GNUNET_PeerIdentity * peer,
 406                                                   const struct
 407                                                   GNUNET_MessageHeader *
 408                                                   message,
 409                                                   const struct
 410                                                   GNUNET_TRANSPORT_ATS_Information
 411                                                   * ats, uint32_t ats_count);
 412
 413
 414 /**
 415  * Opaque handle to the service.
 416  */
 417 struct GNUNET_TRANSPORT_Handle;
 418
 419
 420 /**
 421  * Function called to notify transport users that another
 422  * peer connected to us.
 423  *
 424  * @param cls closure
 425  * @param peer the peer that connected
 426  * @param ats performance data
 427  * @param ats_count number of entries in ats (excluding 0-termination)
 428  */
 429 typedef void
 430     (*GNUNET_TRANSPORT_NotifyConnect) (void *cls,
 431                                        const struct GNUNET_PeerIdentity * peer,
 432                                        const struct
 433                                        GNUNET_TRANSPORT_ATS_Information * ats,
 434                                        uint32_t ats_count);
 435
 436 /**
 437  * Function called to notify transport users that another
 438  * peer disconnected from us.
 439  *
 440  * @param cls closure
 441  * @param peer the peer that disconnected
 442  */
 443 typedef void
 444     (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls,
 445                                           const struct GNUNET_PeerIdentity *
 446                                           peer);
 447
 448
 449 /**
 450  * Function to call with a human-readable format of an address
 451  *
 452  * @param cls closure
 453  * @param address NULL on error, otherwise 0-terminated printable UTF-8 string
 454  */
 455 typedef void
 456     (*GNUNET_TRANSPORT_AddressLookUpCallback) (void *cls, const char *address);
 457
 458
 459 /**
 460  * Connect to the transport service.  Note that the connection may
 461  * complete (or fail) asynchronously.
 462  *
 463  * @param cfg configuration to use
 464  * @param self our own identity (API should check that it matches
 465  *             the identity found by transport), or NULL (no check)
 466  * @param cls closure for the callbacks
 467  * @param rec receive function to call
 468  * @param nc function to call on connect events
 469  * @param nd function to call on disconnect events
 470  * @return NULL on error
 471  */
 472 struct GNUNET_TRANSPORT_Handle *GNUNET_TRANSPORT_connect (const struct
 473                                                           GNUNET_CONFIGURATION_Handle
 474                                                           *cfg,
 475                                                           const struct
 476                                                           GNUNET_PeerIdentity
 477                                                           *self, void *cls,
 478                                                           GNUNET_TRANSPORT_ReceiveCallback
 479                                                           rec,
 480                                                           GNUNET_TRANSPORT_NotifyConnect
 481                                                           nc,
 482                                                           GNUNET_TRANSPORT_NotifyDisconnect
 483                                                           nd);
 484
 485
 486 /**
 487  * Disconnect from the transport service.
 488  *
 489  * @param handle handle returned from connect
 490  */
 491 void GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
 492
 493
 494 /**
 495  * Ask the transport service to establish a connection to
 496  * the given peer.
 497  *
 498  * @param handle connection to transport service
 499  * @param target who we should try to connect to
 500  */
 501 void
 502 GNUNET_TRANSPORT_try_connect (struct GNUNET_TRANSPORT_Handle *handle,
 503                               const struct GNUNET_PeerIdentity *target);
 504
 505
 506 /**
 507  * Set the share of incoming/outgoing bandwidth for the given
 508  * peer to the specified amount.
 509  *
 510  * @param handle connection to transport service
 511  * @param target who's bandwidth quota is being changed
 512  * @param quota_in incoming bandwidth quota
 513  * @param quota_out outgoing bandwidth quota
 514  */
 515 void
 516 GNUNET_TRANSPORT_set_quota (struct GNUNET_TRANSPORT_Handle *handle,
 517                             const struct GNUNET_PeerIdentity *target,
 518                             struct GNUNET_BANDWIDTH_Value32NBO quota_in,
 519                             struct GNUNET_BANDWIDTH_Value32NBO quota_out);
 520
 521
 522 /**
 523  * Opaque handle for a transmission-ready request.
 524  */
 525 struct GNUNET_TRANSPORT_TransmitHandle;
 526
 527
 528 /**
 529  * Check if we could queue a message of the given size for
 530  * transmission.  The transport service will take both its internal
 531  * buffers and bandwidth limits imposed by the other peer into
 532  * consideration when answering this query.
 533  *
 534  * @param handle connection to transport service
 535  * @param target who should receive the message
 536  * @param size how big is the message we want to transmit?
 537  * @param priority how important is the message?
 538  * @param timeout after how long should we give up (and call
 539  *        notify with buf NULL and size 0)?
 540  * @param notify function to call when we are ready to
 541  *        send such a message
 542  * @param notify_cls closure for notify
 543  * @return NULL if someone else is already waiting to be notified
 544  *         non-NULL if the notify callback was queued (can be used to cancel
 545  *         using GNUNET_TRANSPORT_notify_transmit_ready_cancel)
 546  */
 547 struct GNUNET_TRANSPORT_TransmitHandle
 548     *GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle
 549                                              *handle,
 550                                              const struct GNUNET_PeerIdentity
 551                                              *target, size_t size,
 552                                              uint32_t priority,
 553                                              struct GNUNET_TIME_Relative
 554                                              timeout,
 555                                              GNUNET_CONNECTION_TransmitReadyNotify
 556                                              notify, void *notify_cls);
 557
 558
 559 /**
 560  * Cancel the specified transmission-ready notification.
 561  *
 562  * @param th handle of the transmission notification request to cancel
 563  */
 564 void
 565 GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct
 566                                                GNUNET_TRANSPORT_TransmitHandle
 567                                                *th);
 568
 569
 570
 571 /**
 572  * Function called whenever there is an update to the
 573  * HELLO of this peer.
 574  *
 575  * @param cls closure
 576  * @param hello our updated HELLO
 577  */
 578 typedef void (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls,
 579                                                       const struct
 580                                                       GNUNET_MessageHeader *
 581                                                       hello);
 582
 583
 584 /**
 585  * Obtain updates on changes to the HELLO message for this peer.
 586  *
 587  * @param handle connection to transport service
 588  * @param rec function to call with the HELLO
 589  * @param rec_cls closure for rec
 590  */
 591 void
 592 GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle,
 593                             GNUNET_TRANSPORT_HelloUpdateCallback rec,
 594                             void *rec_cls);
 595
 596
 597 /**
 598  * Stop receiving updates about changes to our HELLO message.
 599  *
 600  * @param handle connection to transport service
 601  * @param rec function previously registered to be called with the HELLOs
 602  * @param rec_cls closure for rec
 603  */
 604 void
 605 GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_Handle *handle,
 606                                    GNUNET_TRANSPORT_HelloUpdateCallback rec,
 607                                    void *rec_cls);
 608
 609
 610 /**
 611  * Offer the transport service the HELLO of another peer.  Note that
 612  * the transport service may just ignore this message if the HELLO is
 613  * malformed or useless due to our local configuration.
 614  *
 615  * @param handle connection to transport service
 616  * @param hello the hello message
 617  * @param cont continuation to call when HELLO has been sent
 618  * @param cls closure for continuation
 619  *
 620  */
 621 void
 622 GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle,
 623                               const struct GNUNET_MessageHeader *hello,
 624                               GNUNET_SCHEDULER_Task cont, void *cls);
 625
 626
 627 /**
 628  * Convert a binary address into a human readable address.
 629  *
 630  * @param cfg configuration to use
 631  * @param address address to convert (binary format)
 632  * @param addressLen number of bytes in address
 633  * @param numeric should (IP) addresses be displayed in numeric form
 634  *                (otherwise do reverse DNS lookup)
 635  * @param nameTrans name of the transport to which the address belongs
 636  * @param timeout how long is the lookup allowed to take at most
 637  * @param aluc function to call with the results
 638  * @param aluc_cls closure for aluc
 639  */
 640 void
 641 GNUNET_TRANSPORT_address_lookup (const struct GNUNET_CONFIGURATION_Handle *cfg,
 642                                  const char *address,
 643                                  size_t addressLen,
 644                                  int numeric,
 645                                  const char *nameTrans,
 646                                  struct GNUNET_TIME_Relative timeout,
 647                                  GNUNET_TRANSPORT_AddressLookUpCallback aluc,
 648                                  void *aluc_cls);
 649
 650
 651 /**
 652  * Return all the known addresses for a peer. FIXME: document better!
 653  * FIXME: use better name!
 654  *
 655  * @param cfg configuration to use
 656  * @param peer peer identity to look up the addresses of
 657  * @param timeout how long is the lookup allowed to take at most
 658  * @param peer_address_callback function to call with the results
 659  * @param peer_address_callback_cls closure for peer_address_callback
 660  */
 661 void
 662 GNUNET_TRANSPORT_peer_address_lookup (const struct GNUNET_CONFIGURATION_Handle
 663                                       *cfg,
 664                                       const struct GNUNET_PeerIdentity *peer,
 665                                       struct GNUNET_TIME_Relative timeout,
 666                                       GNUNET_TRANSPORT_AddressLookUpCallback
 667                                       peer_address_callback,
 668                                       void *peer_address_callback_cls);
 669
 670
 671 /**
 672  * Return all the known addresses. FIXME: document better!
 673  * FIXME: use better name!
 674  *
 675  * @param cfg configuration to use
 676  * @param timeout how long is the lookup allowed to take at most
 677  * @param peer_address_callback function to call with the results
 678  * @param peer_address_callback_cls closure for peer_address_callback
 679  */
 680 void
 681 GNUNET_TRANSPORT_address_iterate (const struct GNUNET_CONFIGURATION_Handle *cfg,
 682                                   struct GNUNET_TIME_Relative timeout,
 683                                   GNUNET_TRANSPORT_AddressLookUpCallback
 684                                   peer_address_callback,
 685                                   void *peer_address_callback_cls);
 686
 687
 688 /**
 689  * Handle for blacklisting peers.
 690  */
 691 struct GNUNET_TRANSPORT_Blacklist;
 692
 693
 694 /**
 695  * Function that decides if a connection is acceptable or not.
 696  *
 697  * @param cls closure
 698  * @param pid peer to approve or disapproave
 699  * @return GNUNET_OK if the connection is allowed
 700  */
 701 typedef int (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls,
 702                                                    const struct
 703                                                    GNUNET_PeerIdentity * pid);
 704
 705
 706 /**
 707  * Install a blacklist callback.  The service will be queried for all
 708  * existing connections as well as any fresh connections to check if
 709  * they are permitted.  If the blacklisting callback is unregistered,
 710  * all hosts that were denied in the past will automatically be
 711  * whitelisted again.  Cancelling the blacklist handle is also the
 712  * only way to re-enable connections from peers that were previously
 713  * blacklisted.
 714  *
 715  * @param cfg configuration to use
 716  * @param cb callback to invoke to check if connections are allowed
 717  * @param cb_cls closure for cb
 718  * @return NULL on error, otherwise handle for cancellation
 719  */
 720 struct GNUNET_TRANSPORT_Blacklist *GNUNET_TRANSPORT_blacklist (const struct
 721                                                                GNUNET_CONFIGURATION_Handle
 722                                                                *cfg,
 723                                                                GNUNET_TRANSPORT_BlacklistCallback
 724                                                                cb,
 725                                                                void *cb_cls);
 726
 727
 728 /**
 729  * Abort the blacklist.  Note that this function is the only way for
 730  * removing a peer from the blacklist.
 731  *
 732  * @param br handle of the request that is to be cancelled
 733  */
 734 void GNUNET_TRANSPORT_blacklist_cancel (struct GNUNET_TRANSPORT_Blacklist *br);
 735
 736
 737
 738 #if 0                           /* keep Emacsens' auto-indent happy */
 739 {
 740 #endif
 741 #ifdef __cplusplus
 742 }
 743 #endif
 744
 745 /* ifndef GNUNET_TRANSPORT_SERVICE_H */
 746 #endif
 747 /* end of gnunet_transport_service.h */