- internal api change: add channel direction autodetection in non-loopback channels
[oweals/gnunet.git] / src / mesh / gnunet-service-mesh_channel.h
1 /*
2      This file is part of GNUnet.
3      (C) 2013 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 mesh/gnunet-service-mesh_channel.h
23  * @brief mesh service; dealing with end-to-end channels
24  * @author Bartlomiej Polot
25  *
26  * All functions in this file should use the prefix GMCH (Gnunet Mesh CHannel)
27  */
28
29 #ifndef GNUNET_SERVICE_MESH_CHANNEL_H
30 #define GNUNET_SERVICE_MESH_CHANNEL_H
31
32 #ifdef __cplusplus
33 extern "C"
34 {
35 #if 0                           /* keep Emacsens' auto-indent happy */
36 }
37 #endif
38 #endif
39
40 #include "platform.h"
41 #include "gnunet_util_lib.h"
42
43 #include "mesh_protocol_enc.h"
44 #include "mesh_enc.h"
45
46 /**
47  * Struct containing all information regarding a channel to a remote client.
48  */
49 struct MeshChannel;
50
51
52 #include "gnunet-service-mesh_tunnel.h"
53 #include "gnunet-service-mesh_local.h"
54
55
56 /**
57  * Get channel ID.
58  *
59  * @param ch Channel.
60  *
61  * @return ID
62  */
63 MESH_ChannelNumber
64 GMCH_get_id (const struct MeshChannel *ch);
65
66 /**
67  * Get the channel tunnel.
68  *
69  * @param ch Channel to get the tunnel from.
70  *
71  * @return tunnel of the channel.
72  */
73 struct MeshTunnel3 *
74 GMCH_get_tunnel (const struct MeshChannel *ch);
75
76 /**
77  * Get free buffer space towards the client on a specific channel.
78  *
79  * @param ch Channel.
80  * @param fwd Is query about FWD traffic?
81  *
82  * @return Free buffer space [0 - 64]
83  */
84 unsigned int
85 GMCH_get_buffer (struct MeshChannel *ch, int fwd);
86
87
88 /**
89  * Get flow control status of end point: is client allow to send?
90  *
91  * @param ch Channel.
92  * @param fwd Is query about FWD traffic? (Request root status).
93  *
94  * @return #GNUNET_YES if client is allowed to send us data.
95  */
96 int
97 GMCH_get_allowed (struct MeshChannel *ch, int fwd);
98
99
100 /**
101  * Is the root client for this channel on this peer?
102  *
103  * @param ch Channel.
104  * @param fwd Is this for fwd traffic?
105  *
106  * @return #GNUNET_YES in case it is.
107  */
108 int
109 GMCH_is_origin (struct MeshChannel *ch, int fwd);
110
111 /**
112  * Is the destination client for this channel on this peer?
113  *
114  * @param ch Channel.
115  * @param fwd Is this for fwd traffic?
116  *
117  * @return #GNUNET_YES in case it is.
118  */
119 int
120 GMCH_is_terminal (struct MeshChannel *ch, int fwd);
121
122 /**
123  * Send data on a channel.
124  *
125  * If the destination is local, send it to client, otherwise encrypt and
126  * send to next hop.
127  *
128  * @param ch Channel
129  * @param msg Message.
130  * @param fwd Is this a fwd (root->dest) message?
131  */
132 void
133 GMCH_send_data (struct MeshChannel *ch,
134                 const struct GNUNET_MESH_Data *msg,
135                 int fwd);
136
137 /**
138  * Send an end-to-end ACK message for the most recent in-sequence payload.
139  *
140  * If channel is not reliable, do nothing.
141  *
142  * @param ch Channel this is about.
143  * @param fwd Is for FWD traffic? (ACK dest->owner)
144  */
145 void
146 GMCH_send_data_ack (struct MeshChannel *ch, int fwd);
147
148 /**
149  * Notify the destination client that a new incoming channel was created.
150  *
151  * @param ch Channel that was created.
152  */
153 void
154 GMCH_send_create (struct MeshChannel *ch);
155
156 /**
157  * Notify a client that the channel is no longer valid.
158  *
159  * @param ch Channel that is destroyed.
160  */
161 void
162 GMCH_send_destroy (struct MeshChannel *ch);
163
164 /**
165  * Allow a client to send us more data, in case it was choked.
166  *
167  * @param ch Channel.
168  * @param fwd Is this about FWD traffic? (Root client).
169  */
170 void
171 GMCH_allow_client (struct MeshChannel *ch, int fwd);
172
173 /**
174  * Log channel info.
175  *
176  * @param ch Channel.
177  */
178 void
179 GMCH_debug (struct MeshChannel *ch);
180
181 /**
182  * Handle an ACK given by a client.
183  *
184  * Mark client as ready and send him any buffered data we could have for him.
185  *
186  * @param ch Channel.
187  * @param fwd Is this a "FWD ACK"? (FWD ACKs are sent by root and go BCK)
188  */
189 void
190 GMCH_handle_local_ack (struct MeshChannel *ch, int fwd);
191
192 /**
193  * Handle data given by a client.
194  *
195  * Check whether the client is allowed to send in this tunnel, save if channel
196  * is reliable and send an ACK to the client if there is still buffer space
197  * in the tunnel.
198  *
199  * @param ch Channel.
200  * @param c Client which sent the data.
201  * @param message Message.
202  * @param fwd Is this a FWD data?
203  *
204  * @return GNUNET_OK if everything goes well, GNUNET_SYSERR in case of en error.
205  */
206 int
207 GMCH_handle_local_data (struct MeshChannel *ch,
208                         struct MeshClient *c,
209                         struct GNUNET_MessageHeader *message,
210                         int fwd);
211
212 /**
213  * Handle a channel destroy requested by a client.
214  *
215  * Destroy the channel and the tunnel in case this was the last channel.
216  *
217  * @param ch Channel.
218  * @param c Client that requested the destruction (to avoid notifying him).
219  */
220 void
221 GMCH_handle_local_destroy (struct MeshChannel *ch,
222                            struct MeshClient *c);
223
224 /**
225  * Handle a channel create requested by a client.
226  *
227  * Create the channel and the tunnel in case this was the first0 channel.
228  *
229  * @param c Client that requested the creation (will be the root).
230  * @param msg Create Channel message.
231  *
232  * @return GNUNET_OK if everything went fine, GNUNET_SYSERR otherwise.
233  */
234 int
235 GMCH_handle_local_create (struct MeshClient *c,
236                           struct GNUNET_MESH_ChannelMessage *msg);
237
238 /**
239  * Handler for mesh network payload traffic.
240  *
241  * @param ch Channel for the message.
242  * @param msg Unencryted data message.
243  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
244  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
245  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
246  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
247  */
248 void
249 GMCH_handle_data (struct MeshChannel *ch,
250                   const struct GNUNET_MESH_Data *msg,
251                   int fwd);
252
253 /**
254  * Handler for mesh network traffic end-to-end ACKs.
255  *
256  * @param ch Channel on which we got this message.
257  * @param msg Data message.
258  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
259  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
260  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
261  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
262  */
263 void
264 GMCH_handle_data_ack (struct MeshChannel *ch,
265                       const struct GNUNET_MESH_DataACK *msg,
266                       int fwd);
267
268 /**
269  * Handler for channel create messages.
270  *
271  * Does not have fwd parameter because it's always 'FWD': channel is incoming.
272  *
273  * @param t Tunnel this channel will be in.
274  * @param msg Channel crate message.
275  */
276 struct MeshChannel *
277 GMCH_handle_create (struct MeshTunnel3 *t,
278                     const struct GNUNET_MESH_ChannelCreate *msg);
279
280 /**
281  * Handler for channel ack messages.
282  *
283  * @param ch Channel this channel is to be created in.
284  * @param msg Message.
285  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
286  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
287  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
288  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
289  */
290 void
291 GMCH_handle_ack (struct MeshChannel *ch,
292                  const struct GNUNET_MESH_ChannelManage *msg,
293                  int fwd);
294
295 /**
296  * Handler for channel destroy messages.
297  *
298  * @param ch Channel this channel is to be destroyed of.
299  * @param msg Message.
300  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
301  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
302  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
303  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
304  */
305 void
306 GMCH_handle_destroy (struct MeshChannel *ch,
307                      const struct GNUNET_MESH_ChannelManage *msg,
308                      int fwd);
309
310 /**
311  * Sends an already built message on a channel.
312  *
313  * If the channel is on a loopback tunnel, notifies the appropriate destination
314  * client locally.
315  *
316  * On a normal channel passes the message to the tunnel for encryption and
317  * sending on a connection.
318  *
319  * @param message Message to send. Function makes a copy of it.
320  * @param ch Channel on which this message is transmitted.
321  * @param fwd Is this a fwd message?
322  */
323 void
324 GMCH_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
325                             struct MeshChannel *ch, int fwd);
326
327 /**
328  * Get the static string for identification of the channel.
329  *
330  * @param ch Channel.
331  *
332  * @return Static string with the channel IDs.
333  */
334 const char *
335 GMCH_2s (const struct MeshChannel *ch);
336
337
338 #if 0                           /* keep Emacsens' auto-indent happy */
339 {
340 #endif
341 #ifdef __cplusplus
342 }
343 #endif
344
345 /* ifndef GNUNET_SERVICE_MESH_CHANNEL_H */
346 #endif
347 /* end of gnunet-service-mesh_channel.h */