3 This file is part of GNUnet.
4 Copyright (C) 2001-2017 GNUnet e.V.
6 GNUnet is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published
8 by the Free Software Foundation; either version 3, or (at your
9 option) any later version.
11 GNUnet is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNUnet; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
23 * @file cadet/gnunet-service-cadet-new_channel.h
24 * @brief GNUnet CADET service with encryption
25 * @author Bartlomiej Polot
26 * @author Christian Grothoff
28 #ifndef GNUNET_SERVICE_CADET_CHANNEL_H
29 #define GNUNET_SERVICE_CADET_CHANNEL_H
31 #include "gnunet-service-cadet-new.h"
32 #include "gnunet-service-cadet-new_peer.h"
33 #include "cadet_protocol.h"
37 * A channel is a bidirectional connection between two CADET
38 * clients. Communiation can be reliable, unreliable, in-order
39 * or out-of-order. One client is the "local" client, this
40 * one initiated the connection. The other client is the
41 * "incoming" client, this one listened on a port to accept
42 * the connection from the "local" client.
48 * Get the static string for identification of the channel.
52 * @return Static string with the channel IDs.
55 GCCH_2s (const struct CadetChannel *ch);
62 * @param level Debug level to use.
65 GCCH_debug (struct CadetChannel *ch,
66 enum GNUNET_ErrorType level);
70 * Get the channel's public ID.
74 * @return ID used to identify the channel with the remote peer.
76 struct GNUNET_CADET_ChannelTunnelNumber
77 GCCH_get_id (const struct CadetChannel *ch);
81 * Create a new channel.
83 * @param owner local client owning the channel
84 * @param owner_id local chid of this channel at the @a owner
85 * @param destination peer to which we should build the channel
86 * @param port desired port at @a destination
87 * @param options options for the channel
88 * @return handle to the new channel
91 GCCH_channel_local_new (struct CadetClient *owner,
92 struct GNUNET_CADET_ClientChannelNumber owner_id,
93 struct CadetPeer *destination,
94 const struct GNUNET_HashCode *port,
99 * A client is bound to the port that we have a channel
100 * open to. Send the acknowledgement for the connection
101 * request and establish the link with the client.
103 * @param ch open incoming channel
104 * @param c client listening on the respective port
107 GCCH_bind (struct CadetChannel *ch,
108 struct CadetClient *c);
112 * Destroy locally created channel. Called by the
113 * local client, so no need to tell the client.
115 * @param ch channel to destroy
116 * @param c client that caused the destruction
117 * @param ccn client number of the client @a c
120 GCCH_channel_local_destroy (struct CadetChannel *ch,
121 struct CadetClient *c,
122 struct GNUNET_CADET_ClientChannelNumber ccn);
126 * Function called once and only once after a channel was bound
127 * to its tunnel via #GCT_add_channel() is ready for transmission.
128 * Note that this is only the case for channels that this peer
129 * initiates, as for incoming channels we assume that they are
130 * ready for transmission immediately upon receiving the open
131 * message. Used to bootstrap the #GCT_send() process.
133 * @param ch the channel for which the tunnel is now ready
136 GCCH_tunnel_up (struct CadetChannel *ch);
140 * Create a new channel based on a request coming in over the network.
142 * @param t tunnel to the remote peer
143 * @param chid identifier of this channel in the tunnel
144 * @param origin peer to who initiated the channel
145 * @param port desired local port
146 * @param options options for the channel
147 * @return handle to the new channel
149 struct CadetChannel *
150 GCCH_channel_incoming_new (struct CadetTunnel *t,
151 struct GNUNET_CADET_ChannelTunnelNumber chid,
152 const struct GNUNET_HashCode *port,
157 * We got a #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN message again for
158 * this channel. If the binding was successful, (re)transmit the
159 * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK.
161 * @param ch channel that got the duplicate open
164 GCCH_handle_duplicate_open (struct CadetChannel *ch);
168 * We got payload data for a channel. Pass it on to the client.
170 * @param ch channel that got data
171 * @param msg message that was received
174 GCCH_handle_channel_plaintext_data (struct CadetChannel *ch,
175 const struct GNUNET_CADET_ChannelAppDataMessage *msg);
179 * We got an acknowledgement for payload data for a channel.
180 * Possibly resume transmissions.
182 * @param ch channel that got the ack
183 * @param ack details about what was received
186 GCCH_handle_channel_plaintext_data_ack (struct CadetChannel *ch,
187 const struct GNUNET_CADET_ChannelDataAckMessage *ack);
191 * We got an acknowledgement for the creation of the channel
192 * (the port is open on the other side). Begin transmissions.
194 * @param ch channel to destroy
197 GCCH_handle_channel_open_ack (struct CadetChannel *ch);
201 * Destroy channel, based on the other peer closing the
202 * connection. Also needs to remove this channel from
205 * FIXME: need to make it possible to defer destruction until we have
206 * received all messages up to the destroy, and right now the destroy
207 * message (and this API) fails to give is the information we need!
209 * FIXME: also need to know if the other peer got a destroy from
212 * @param ch channel to destroy
215 GCCH_handle_remote_destroy (struct CadetChannel *ch);
219 * Handle data given by a client.
221 * Check whether the client is allowed to send in this tunnel, save if
222 * channel is reliable and send an ACK to the client if there is still
223 * buffer space in the tunnel.
226 * @param sender_ccn ccn of the sender
227 * @param buf payload to transmit.
228 * @param buf_len number of bytes in @a buf
229 * @return #GNUNET_OK if everything goes well,
230 * #GNUNET_SYSERR in case of an error.
233 GCCH_handle_local_data (struct CadetChannel *ch,
234 struct GNUNET_CADET_ClientChannelNumber sender_ccn,
240 * Handle ACK from client on local channel.
242 * @param ch channel to destroy
243 * @param client_ccn ccn of the client sending the ack
246 GCCH_handle_local_ack (struct CadetChannel *ch,
247 struct GNUNET_CADET_ClientChannelNumber client_ccn);