src/include/gnunet_transport_plugin.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2009, 2010 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 transport/gnunet_transport_plugin.h
  23  * @brief API for the transport services.  This header
  24  *        specifies the struct that is given to the plugin's entry
  25  *        method and the other struct that must be returned.
  26  *        Note that the destructors of transport plugins will
  27  *        be given the value returned by the constructor
  28  *        and is expected to return a NULL pointer.
  29  * @author Christian Grothoff
  30  */
  31 #ifndef PLUGIN_TRANSPORT_H
  32 #define PLUGIN_TRANSPORT_H
  33
  34 #include "gnunet_configuration_lib.h"
  35 #include "gnunet_scheduler_lib.h"
  36 #include "gnunet_statistics_service.h"
  37 #include "gnunet_transport_service.h"
  38
  39
  40 /**
  41  *  The structs defined here are used by the transport plugin to tell ATS about
  42  *  the transport's properties like cost and quality and on the other side
  43  *  the structs are used by highlevel components to communicate the constraints
  44  *  they have for a transport to ATS
  45  *
  46  *                             +---+
  47  *  +-----------+ Constraints  |   |  Plugin properties +---------+
  48  *  | Highlevel |------------> |ATS| <------------------|Transport|
  49  *  | Component | ATS struct   |   |    ATS struct      | Plugin  |
  50  *  +-----------+              |   |                    +---------+
  51  *                             +---+
  52  *
  53  */
  54
  55 #define GNUNET_TRANSPORT_ATS_ARRAY_TERMINATOR 0
  56
  57 /**
  58  * Enum defining all known property types for ATS
  59  * Enum values are used in the GNUNET_TRANSPORT_ATS_Information struct as (key,value)-pair
  60  *
  61  * Cost are always stored in uint32_t, so all units used to define costs
  62  * have to be normalized to fit in uint32_t [0 .. 4.294.967.295]
  63  *
  64  * To keep the elements ordered
  65  *    1..1024 : Values with a relation to cost
  66  * 1025..2048 : Values with a relation to quality
  67  * 2049..3072 : Values with a relation to availability
  68  *
  69  */
  70 enum GNUNET_TRANSPORT_ATS_Property
  71 {
  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: [μs]
 257          *
 258          * Examples:
 259          *
 260          * LAN   :  180
 261          * Dialup: 4000
 262          * WLAN  : 7000
 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: [μs]
 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         /* Availability related values */
 339         /* =========================== */
 340
 341         /**
 342          * Is a peer reachable?
 343          */
 344         GNUNET_TRANSPORT_ATS_AVAILABILITY_REACHABLE = 2048,
 345
 346         /**
 347          * Is there a connection established to a peer using this transport
 348          */
 349         GNUNET_TRANSPORT_ATS_AVAILABILITY_CONNECTED = 2049
 350 };
 351
 352 /**
 353  * This structure will be used by plugins to communicate costs to ATS or by
 354  * higher level components to tell ATS their constraints.
 355  * Always a pair of (GNUNET_TRANSPORT_ATS_Property, uint32_t value).
 356  * Value is always uint32_t, so all units used to define costs have to
 357  * be normalized to fit uint32_t.
 358  */
 359 struct GNUNET_TRANSPORT_ATS_Information
 360 {
 361         /**
 362          * ATS property type
 363          */
 364         uint32_t type;
 365
 366         /**
 367          * ATS property value
 368          */
 369         uint32_t value;
 370 };
 371
 372
 373
 374 /**
 375  * Opaque pointer that plugins can use to distinguish specific
 376  * connections to a given peer.  Typically used by stateful plugins to
 377  * allow the service to refer to specific streams instead of a more
 378  * general notion of "some connection" to the given peer.  This is
 379  * useful since sometimes (i.e. for inbound TCP connections) a
 380  * connection may not have an address that can be used for meaningful
 381  * distinction between sessions to the same peer.
 382  */
 383 struct Session;
 384
 385 /**
 386  * Every 'struct Session' must begin with this header.
 387  */
 388 struct SessionHeader
 389 {
 390
 391   /**
 392    * Cached signature for PONG generation for the session.  Do not use
 393    * in the plugin!
 394    */
 395   struct GNUNET_CRYPTO_RsaSignature pong_signature;
 396
 397   /**
 398    * Expiration time for signature.  Do not use in the plugin!
 399    */
 400   struct GNUNET_TIME_Absolute pong_sig_expires;
 401
 402 };
 403
 404 /**
 405  * Function that will be called whenever the plugin internally
 406  * cleans up a session pointer and hence the service needs to
 407  * discard all of those sessions as well.  Plugins that do not
 408  * use sessions can simply omit calling this function and always
 409  * use NULL wherever a session pointer is needed.
 410  *
 411  * @param cls closure
 412  * @param peer which peer was the session for
 413  * @param session which session is being destoyed
 414  */
 415 typedef void (*GNUNET_TRANSPORT_SessionEnd) (void *cls,
 416                                              const struct GNUNET_PeerIdentity *peer,
 417                                              struct Session *session);
 418
 419
 420 /**
 421  * Function called by the transport for each received message.
 422  * This function should also be called with "NULL" for the
 423  * message to signal that the other peer disconnected.
 424  *
 425  * @param cls closure
 426  * @param peer (claimed) identity of the other peer
 427  * @param message the message, NULL if we only care about
 428  *                learning about the delay until we should receive again -- FIXME!
 429  * @param distance in overlay hops; use 1 unless DV (or 0 if message == NULL)
 430  * @param session identifier used for this session (NULL for plugins
 431  *                that do not offer bi-directional communication to the sender
 432  *                using the same "connection")
 433  * @param sender_address binary address of the sender (if we established the
 434  *                connection or are otherwise sure of it; should be NULL
 435  *                for inbound TCP/UDP connections since it it not clear
 436  *                that we could establish ourselves a connection to that
 437  *                IP address and get the same system)
 438  * @param sender_address_len number of bytes in sender_address
 439  * @return how long the plugin should wait until receiving more data
 440  *         (plugins that do not support this, can ignore the return value)
 441  */
 442 typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls,
 443                                                                                const struct
 444                                                                                GNUNET_PeerIdentity *
 445                                                                                peer,
 446                                                                                const struct
 447                                                                                GNUNET_MessageHeader *
 448                                                                                message,
 449                                                                                uint32_t distance,
 450                                                                                struct Session *session,
 451                                                                                const char *sender_address,
 452                                                                                uint16_t sender_address_len);
 453
 454
 455 /**
 456  * Function that will be called for each address the transport
 457  * is aware that it might be reachable under.
 458  *
 459  * @param cls closure
 460  * @param name name of the transport that generated the address
 461  * @param addr one of the addresses of the host, NULL for the last address
 462  *        the specific address format depends on the transport
 463  * @param addrlen length of the address
 464  * @param expires when should this address automatically expire?
 465  */
 466 typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls,
 467                                                       const char *name,
 468                                                       const void *addr,
 469                                                       uint16_t addrlen,
 470                                                       struct
 471                                                       GNUNET_TIME_Relative
 472                                                       expires);
 473
 474 /**
 475  * Function that will be called whenever the plugin receives data over
 476  * the network and wants to determine how long it should wait until
 477  * the next time it reads from the given peer.  Note that some plugins
 478  * (such as UDP) may not be able to wait (for a particular peer), so
 479  * the waiting part is optional.  Plugins that can wait should call
 480  * this function, sleep the given amount of time, and call it again
 481  * (with zero bytes read) UNTIL it returns zero and only then read.
 482  *
 483  * @param cls closure
 484  * @param peer which peer did we read data from
 485  * @param amount_recved number of bytes read (can be zero)
 486  * @return how long to wait until reading more from this peer
 487  *         (to enforce inbound quotas)
 488  */
 489 typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_TrafficReport) (void *cls,
 490                                                                       const struct
 491                                                                       GNUNET_PeerIdentity *peer,
 492                                                                       size_t amount_recved);
 493
 494 /**
 495  * Function called whenever the plugin has to notify ATS about costs for using this transport
 496  *
 497  * The cost will be passed as struct GNUNET_TRANSPORT_ATS_Cost_Information[]
 498  * This array is 0-terminated, so the last element will be a pair:
 499  * ((cost->cost_type==GNUNET_TRANSPORT_ATS_ARRAY_TERMINATOR) && cost->cost_value==0))
 500  *
 501  * @param cls closure
 502  * @param peer peer
 503  * @param addr peer address
 504  * @param addrlen address length
 505  * @param cost pointer to the first element of struct GNUNET_TRANSPORT_ATS_Cost_Information[]
 506  */
 507 typedef void (*GNUNET_TRANSPORT_CostReport) (void *cls,
 508                                                                                          const struct GNUNET_PeerIdentity *peer,
 509                                              const void *addr,
 510                                              uint16_t addrlen,
 511                                                                                          struct GNUNET_TRANSPORT_ATS_Information * cost);
 512
 513 /**
 514  * The transport service will pass a pointer to a struct
 515  * of this type as the first and only argument to the
 516  * entry point of each transport plugin.
 517  */
 518 struct GNUNET_TRANSPORT_PluginEnvironment
 519 {
 520   /**
 521    * Configuration to use.
 522    */
 523   const struct GNUNET_CONFIGURATION_Handle *cfg;
 524
 525   /**
 526    * Identity of this peer.
 527    */
 528   const struct GNUNET_PeerIdentity *my_identity;
 529
 530   /**
 531    * Pointer (!) to our HELLO message.  Note that the address
 532    * referred to "*our_hello" might change over time.
 533    */
 534   struct GNUNET_HELLO_Message *const*our_hello;
 535
 536   /**
 537    * Closure for the various callbacks.
 538    */
 539   void *cls;
 540
 541   /**
 542    * Handle for reporting statistics.
 543    */
 544   struct GNUNET_STATISTICS_Handle *stats;
 545
 546   /**
 547    * Function that should be called by the transport plugin
 548    * whenever a message is received.
 549    */
 550   GNUNET_TRANSPORT_PluginReceiveCallback receive;
 551
 552   /**
 553    * Function that must be called by each plugin to notify the
 554    * transport service about the addresses under which the transport
 555    * provided by the plugin can be reached.
 556    */
 557   GNUNET_TRANSPORT_AddressNotification notify_address;
 558
 559   /**
 560    * Inform service about traffic received, get information
 561    * about when we might be willing to receive more.
 562    */
 563   GNUNET_TRANSPORT_TrafficReport traffic_report;
 564
 565   /**
 566    * Function that must be called by the plugin when a non-NULL
 567    * session handle stops being valid (is destroyed).
 568    */
 569   GNUNET_TRANSPORT_SessionEnd session_end;
 570
 571   /**
 572    * Inform service about costs for using this transport plugin
 573    */
 574   GNUNET_TRANSPORT_CostReport cost_report;
 575
 576   /**
 577    * What is the maximum number of connections that this transport
 578    * should allow?  Transports that do not have sessions (such as
 579    * UDP) can ignore this value.
 580    */
 581   uint32_t max_connections;
 582
 583 };
 584
 585
 586 /**
 587  * Function called by the GNUNET_TRANSPORT_TransmitFunction
 588  * upon "completion".
 589  *
 590  * @param cls closure
 591  * @param target who was the recipient of the message?
 592  * @param result GNUNET_OK on success
 593  *               GNUNET_SYSERR if the target disconnected;
 594  *               disconnect will ALSO be signalled using
 595  *               the ReceiveCallback.
 596  */
 597 typedef void
 598   (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls,
 599                                             const struct GNUNET_PeerIdentity *
 600                                             target, int result);
 601
 602
 603 /**
 604  * Function that can be used by the transport service to transmit
 605  * a message using the plugin.   Note that in the case of a
 606  * peer disconnecting, the continuation MUST be called
 607  * prior to the disconnect notification itself.  This function
 608  * will be called with this peer's HELLO message to initiate
 609  * a fresh connection to another peer.
 610  *
 611  * @param cls closure
 612  * @param target who should receive this message
 613  * @param msgbuf the message to transmit
 614  * @param msgbuf_size number of bytes in 'msgbuf'
 615  * @param priority how important is the message (most plugins will
 616  *                 ignore message priority and just FIFO)
 617  * @param timeout how long to wait at most for the transmission (does not
 618  *                require plugins to discard the message after the timeout,
 619  *                just advisory for the desired delay; most plugins will ignore
 620  *                this as well)
 621  * @param session which session must be used (or NULL for "any")
 622  * @param addr the address to use (can be NULL if the plugin
 623  *                is "on its own" (i.e. re-use existing TCP connection))
 624  * @param addrlen length of the address in bytes
 625  * @param force_address GNUNET_YES if the plugin MUST use the given address,
 626  *                GNUNET_NO means the plugin may use any other address and
 627  *                GNUNET_SYSERR means that only reliable existing
 628  *                bi-directional connections should be used (regardless
 629  *                of address)
 630  * @param cont continuation to call once the message has
 631  *        been transmitted (or if the transport is ready
 632  *        for the next transmission call; or if the
 633  *        peer disconnected...); can be NULL
 634  * @param cont_cls closure for cont
 635  * @return number of bytes used (on the physical network, with overheads);
 636  *         -1 on hard errors (i.e. address invalid); 0 is a legal value
 637  *         and does NOT mean that the message was not transmitted (DV)
 638  */
 639 typedef ssize_t
 640   (*GNUNET_TRANSPORT_TransmitFunction) (void *cls,
 641                                         const struct GNUNET_PeerIdentity *
 642                                         target,
 643                                         const char *msgbuf,
 644                                         size_t msgbuf_size,
 645                                         uint32_t priority,
 646                                         struct GNUNET_TIME_Relative timeout,
 647                                         struct Session *session,
 648                                         const void *addr,
 649                                         size_t addrlen,
 650                                         int force_address,
 651                                         GNUNET_TRANSPORT_TransmitContinuation
 652                                         cont, void *cont_cls);
 653
 654
 655 /**
 656  * Function that can be called to force a disconnect from the
 657  * specified neighbour.  This should also cancel all previously
 658  * scheduled transmissions.  Obviously the transmission may have been
 659  * partially completed already, which is OK.  The plugin is supposed
 660  * to close the connection (if applicable) and no longer call the
 661  * transmit continuation(s).
 662  *
 663  * Finally, plugin MUST NOT call the services's receive function to
 664  * notify the service that the connection to the specified target was
 665  * closed after a getting this call.
 666  *
 667  * @param cls closure
 668  * @param target peer for which the last transmission is
 669  *        to be cancelled
 670  */
 671 typedef void
 672   (*GNUNET_TRANSPORT_DisconnectFunction) (void *cls,
 673                                           const struct GNUNET_PeerIdentity *
 674                                           target);
 675
 676
 677 /**
 678  * Function called by the pretty printer for the resolved address for
 679  * each human-readable address obtained.
 680  *
 681  * @param cls closure
 682  * @param hostname one of the names for the host, NULL
 683  *        on the last call to the callback
 684  */
 685 typedef void (*GNUNET_TRANSPORT_AddressStringCallback) (void *cls,
 686                                                         const char *address);
 687
 688
 689 /**
 690  * Convert the transports address to a nice, human-readable
 691  * format.
 692  *
 693  * @param cls closure
 694  * @param name name of the transport that generated the address
 695  * @param addr one of the addresses of the host, NULL for the last address
 696  *        the specific address format depends on the transport
 697  * @param addrlen length of the address
 698  * @param numeric should (IP) addresses be displayed in numeric form?
 699  * @param timeout after how long should we give up?
 700  * @param asc function to call on each string
 701  * @param asc_cls closure for asc
 702  */
 703 typedef void
 704   (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls,
 705                                             const char *type,
 706                                             const void *addr,
 707                                             size_t addrlen,
 708                                             int numeric,
 709                                             struct GNUNET_TIME_Relative
 710                                             timeout,
 711                                             GNUNET_TRANSPORT_AddressStringCallback
 712                                             asc, void *asc_cls);
 713
 714
 715 /**
 716  * Another peer has suggested an address for this peer and transport
 717  * plugin.  Check that this could be a valid address.  This function
 718  * is not expected to 'validate' the address in the sense of trying to
 719  * connect to it but simply to see if the binary format is technically
 720  * legal for establishing a connection to this peer (and make sure that
 721  * the address really corresponds to our network connection/settings
 722  * and not some potential man-in-the-middle).
 723  *
 724  * @param addr pointer to the address
 725  * @param addrlen length of addr
 726  * @return GNUNET_OK if this is a plausible address for this peer
 727  *         and transport, GNUNET_SYSERR if not
 728  */
 729 typedef int
 730 (*GNUNET_TRANSPORT_CheckAddress) (void *cls,
 731                                   const void *addr, size_t addrlen);
 732
 733
 734 /**
 735  * Function called for a quick conversion of the binary address to
 736  * a numeric address.  Note that the caller must not free the
 737  * address and that the next call to this function is allowed
 738  * to override the address again.
 739  *
 740  * @param cls closure
 741  * @param addr binary address
 742  * @param addr_len length of the address
 743  * @return string representing the same address
 744  */
 745 typedef const char* (*GNUNET_TRANSPORT_AddressToString) (void *cls,
 746                                                          const void *addr,
 747                                                          size_t addrlen);
 748
 749
 750 /**
 751  * Each plugin is required to return a pointer to a struct of this
 752  * type as the return value from its entry point.
 753  */
 754 struct GNUNET_TRANSPORT_PluginFunctions
 755 {
 756
 757   /**
 758    * Closure for all of the callbacks.
 759    */
 760   void *cls;
 761
 762   /**
 763    * Function that the transport service will use to transmit data to
 764    * another peer.  May be NULL for plugins that only support
 765    * receiving data.  After this call, the plugin call the specified
 766    * continuation with success or error before notifying us about the
 767    * target having disconnected.
 768    */
 769   GNUNET_TRANSPORT_TransmitFunction send;
 770
 771   /**
 772    * Function that can be used to force the plugin to disconnect from
 773    * the given peer and cancel all previous transmissions (and their
 774    * continuations).  Note that if the transport does not have
 775    * sessions / persistent connections (for example, UDP), this
 776    * function may very well do nothing.
 777    */
 778   GNUNET_TRANSPORT_DisconnectFunction disconnect;
 779
 780   /**
 781    * Function to pretty-print addresses.  NOTE: this function is not
 782    * yet used by transport-service, but will be used in the future
 783    * once the transport-API has been completed.
 784    */
 785   GNUNET_TRANSPORT_AddressPrettyPrinter address_pretty_printer;
 786
 787   /**
 788    * Function that will be called to check if a binary address
 789    * for this plugin is well-formed and corresponds to an
 790    * address for THIS peer (as per our configuration).  Naturally,
 791    * if absolutely necessary, plugins can be a bit conservative in
 792    * their answer, but in general plugins should make sure that the
 793    * address does not redirect traffic to a 3rd party that might
 794    * try to man-in-the-middle our traffic.
 795    */
 796   GNUNET_TRANSPORT_CheckAddress check_address;
 797
 798   /**
 799    * Function that will be called to convert a binary address
 800    * to a string (numeric conversion only).
 801    */
 802   GNUNET_TRANSPORT_AddressToString address_to_string;
 803
 804 };
 805
 806
 807 #endif