cadet.rst (4778B)
1 2 .. _CADET-Subsystem-Dev: 3 4 .. index:: 5 double: CADET; subsystem 6 7 CADET 8 ===== 9 10 11 The CADET API (defined in ``gnunet_cadet_service.h``) is the messaging 12 API used by P2P applications built using GNUnet. It provides 13 applications the ability to send and receive encrypted messages to any 14 peer participating in GNUnet. The API is heavily based on the CORE API. 15 16 CADET delivers messages to other peers in \"channels\". A channel is a 17 permanent connection defined by a destination peer (identified by its 18 public key) and a port number. Internally, CADET tunnels all channels 19 towards a destination peer using one session key and relays the data on 20 multiple \"connections\", independent from the channels. 21 22 Each channel has optional parameters, the most important being the 23 reliability flag. Should a message get lost on TRANSPORT/CORE level, if 24 a channel is created with as reliable, CADET will retransmit the lost 25 message and deliver it in order to the destination application. 26 27 GNUNET_CADET_connect 28 29 .. .. doxygenfunction:: GNUNET_CADET_connect 30 31 To communicate with other peers using CADET, it is necessary to first 32 connect to the service using ``GNUNET_CADET_connect``. This function 33 takes several parameters in form of callbacks, to allow the client to 34 react to various events, like incoming channels or channels that 35 terminate, as well as specify a list of ports the client wishes to 36 listen to (at the moment it is not possible to start listening on 37 further ports once connected, but nothing prevents a client to connect 38 several times to CADET, even do one connection per listening port). The 39 function returns a handle which has to be used for any further 40 interaction with the service. 41 42 GNUNET_CADET_channel_create 43 44 .. .. doxygenfunction:: GNUNET_CADET_channel_create 45 46 To connect to a remote peer, a client has to call the 47 ``GNUNET_CADET_channel_create`` function. The most important parameters 48 given are the remote peer's identity (it public key) and a port, which 49 specifies which application on the remote peer to connect to, similar to 50 TCP/UDP ports. CADET will then find the peer in the GNUnet network and 51 establish the proper low-level connections and do the necessary key 52 exchanges to assure and authenticated, secure and verified 53 communication. Similar to 54 ``GNUNET_CADET_connect``,\ ``GNUNET_CADET_create_channel`` returns a 55 handle to interact with the created channel. 56 57 GNUNET_CADET_notify_transmit_ready 58 59 .. .. doxygenfunction:: GNUNET_CADET_notify_transmit_ready 60 61 For every message the client wants to send to the remote application, 62 ``GNUNET_CADET_notify_transmit_ready`` must be called, indicating the 63 channel on which the message should be sent and the size of the message 64 (but not the message itself!). Once CADET is ready to send the message, 65 the provided callback will fire, and the message contents are provided 66 to this callback. 67 68 Please note the CADET does not provide an explicit notification of when 69 a channel is connected. In loosely connected networks, like big wireless 70 mesh networks, this can take several seconds, even minutes in the worst 71 case. To be alerted when a channel is online, a client can call 72 ``GNUNET_CADET_notify_transmit_ready`` immediately after 73 ``GNUNET_CADET_create_channel``. When the callback is activated, it 74 means that the channel is online. The callback can give 0 bytes to CADET 75 if no message is to be sent, this is OK. 76 77 GNUNET_CADET_notify_transmit_cancel 78 79 .. .. doxygenfunction:: GNUNET_CADET_notify_transmit_cancel 80 81 If a transmission was requested but before the callback fires it is no 82 longer needed, it can be canceled with 83 ``GNUNET_CADET_notify_transmit_ready_cancel``, which uses the handle 84 given back by ``GNUNET_CADET_notify_transmit_ready``. As in the case of 85 CORE, only one message can be requested at a time: a client must not 86 call ``GNUNET_CADET_notify_transmit_ready`` again until the callback is 87 called or the request is canceled. 88 89 GNUNET_CADET_channel_destroy 90 91 .. .. doxygenfunction:: GNUNET_CADET_notify_channel_destroy 92 93 When a channel is no longer needed, a client can call 94 ``GNUNET_CADET_channel_destroy`` to get rid of it. Note that CADET will 95 try to transmit all pending traffic before notifying the remote peer of 96 the destruction of the channel, including retransmitting lost messages 97 if the channel was reliable. 98 99 Incoming channels, channels being closed by the remote peer, and traffic 100 on any incoming or outgoing channels are given to the client when CADET 101 executes the callbacks given to it at the time of 102 ``GNUNET_CADET_connect``. 103 104 GNUNET_CADET_disconnect 105 106 .. .. doxygenfunction:: GNUNET_CADET_disconnect 107 108 Finally, when an application no longer wants to use CADET, it should 109 call ``GNUNET_CADET_disconnect``, but first all channels and pending 110 transmissions must be closed (otherwise CADET will complain).