CADET

The CADET API (defined in gnunet_cadet_service.h) is the messaging API used by P2P applications built using GNUnet. It provides applications the ability to send and receive encrypted messages to any peer participating in GNUnet. The API is heavily based on the CORE API.

CADET delivers messages to other peers in "channels". A channel is a permanent connection defined by a destination peer (identified by its public key) and a port number. Internally, CADET tunnels all channels towards a destination peer using one session key and relays the data on multiple "connections", independent from the channels.

Each channel has optional parameters, the most important being the reliability flag. Should a message get lost on TRANSPORT/CORE level, if a channel is created with as reliable, CADET will retransmit the lost message and deliver it in order to the destination application.

GNUNET_CADET_connect

To communicate with other peers using CADET, it is necessary to first connect to the service using GNUNET_CADET_connect. This function takes several parameters in form of callbacks, to allow the client to react to various events, like incoming channels or channels that terminate, as well as specify a list of ports the client wishes to listen to (at the moment it is not possible to start listening on further ports once connected, but nothing prevents a client to connect several times to CADET, even do one connection per listening port). The function returns a handle which has to be used for any further interaction with the service.

GNUNET_CADET_channel_create

To connect to a remote peer, a client has to call the GNUNET_CADET_channel_create function. The most important parameters given are the remote peer’s identity (it public key) and a port, which specifies which application on the remote peer to connect to, similar to TCP/UDP ports. CADET will then find the peer in the GNUnet network and establish the proper low-level connections and do the necessary key exchanges to assure and authenticated, secure and verified communication. Similar to GNUNET_CADET_connect,GNUNET_CADET_create_channel returns a handle to interact with the created channel.

GNUNET_CADET_notify_transmit_ready

For every message the client wants to send to the remote application, GNUNET_CADET_notify_transmit_ready must be called, indicating the channel on which the message should be sent and the size of the message (but not the message itself!). Once CADET is ready to send the message, the provided callback will fire, and the message contents are provided to this callback.

Please note the CADET does not provide an explicit notification of when a channel is connected. In loosely connected networks, like big wireless mesh networks, this can take several seconds, even minutes in the worst case. To be alerted when a channel is online, a client can call GNUNET_CADET_notify_transmit_ready immediately after GNUNET_CADET_create_channel. When the callback is activated, it means that the channel is online. The callback can give 0 bytes to CADET if no message is to be sent, this is OK.

GNUNET_CADET_notify_transmit_cancel

If a transmission was requested but before the callback fires it is no longer needed, it can be canceled with GNUNET_CADET_notify_transmit_ready_cancel, which uses the handle given back by GNUNET_CADET_notify_transmit_ready. As in the case of CORE, only one message can be requested at a time: a client must not call GNUNET_CADET_notify_transmit_ready again until the callback is called or the request is canceled.

GNUNET_CADET_channel_destroy

When a channel is no longer needed, a client can call GNUNET_CADET_channel_destroy to get rid of it. Note that CADET will try to transmit all pending traffic before notifying the remote peer of the destruction of the channel, including retransmitting lost messages if the channel was reliable.

Incoming channels, channels being closed by the remote peer, and traffic on any incoming or outgoing channels are given to the client when CADET executes the callbacks given to it at the time of GNUNET_CADET_connect.

GNUNET_CADET_disconnect

Finally, when an application no longer wants to use CADET, it should call GNUNET_CADET_disconnect, but first all channels and pending transmissions must be closed (otherwise CADET will complain).