- migrate handlers to channel.c
[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  * Is the root client for this channel on this peer?
89  *
90  * @param ch Channel.
91  * @param fwd Is this for fwd traffic?
92  *
93  * @return GNUNET_YES in case it is.
94  */
95 int
96 GMCH_is_origin (struct MeshChannel *ch, int fwd);
97
98 /**
99  * Is the destination client for this channel on this peer?
100  *
101  * @param ch Channel.
102  * @param fwd Is this for fwd traffic?
103  *
104  * @return GNUNET_YES in case it is.
105  */
106 int
107 GMCH_is_terminal (struct MeshChannel *ch, int fwd);
108
109 /**
110  * Send an end-to-end ACK message for the most recent in-sequence payload.
111  *
112  * If channel is not reliable, do nothing.
113  *
114  * @param ch Channel this is about.
115  * @param fwd Is for FWD traffic? (ACK dest->owner)
116  */
117 void
118 GMCH_send_ack (struct MeshChannel *ch, int fwd);
119
120 /**
121  * Send data on a channel.
122  *
123  * If the destination is local, send it to client, otherwise encrypt and
124  * send to next hop.
125  *
126  * @param ch Channel
127  * @param msg Message.
128  * @param fwd Is this a fwd (root->dest) message?
129  */
130 void
131 GMCH_send_data (struct MeshChannel *ch,
132                 const struct GNUNET_MESH_Data *msg,
133                 int fwd);
134
135 /**
136  * Notify the destination client that a new incoming channel was created.
137  *
138  * @param ch Channel that was created.
139  */
140 void
141 GMCH_send_create (struct MeshChannel *ch);
142
143 /**
144  * Notify a client that the channel is no longer valid.
145  *
146  * @param ch Channel that is destroyed.
147  */
148 void
149 GMCH_send_destroy (struct MeshChannel *ch);
150
151 /**
152  * Log channel info.
153  *
154  * @param ch Channel.
155  */
156 void
157 GMCH_debug (struct MeshChannel *ch);
158
159 /**
160  * Handle an ACK given by a client.
161  *
162  * Mark client as ready and send him any buffered data we could have for him.
163  *
164  * @param ch Channel.
165  * @param fwd Is this a "FWD ACK"? (FWD ACKs are sent by root and go BCK)
166  */
167 void
168 GMCH_handle_local_ack (struct MeshChannel *ch, int fwd);
169
170 /**
171  * Handle data given by a client.
172  *
173  * Check whether the client is allowed to send in this tunnel, save if channel
174  * is reliable and send an ACK to the client if there is still buffer space
175  * in the tunnel.
176  *
177  * @param ch Channel.
178  * @param fwd Is this a FWD data?
179  *
180  * @return GNUNET_OK if everything goes well, GNUNET_SYSERR in case of en error.
181  */
182 int
183 GMCH_handle_local_data (struct MeshChannel *ch,
184                         struct MeshClient *c,
185                         struct GNUNET_MessageHeader *message,
186                         int fwd);
187
188 /**
189  * Handle a channel destroy requested by a client.
190  *
191  * Destroy the channel and the tunnel in case this was the last channel.
192  *
193  * @param ch Channel.
194  * @param c Client that requested the destruction (to avoid notifying him).
195  * @param chid Channel ID used.
196  */
197 void
198 GMCH_handle_local_destroy (struct MeshChannel *ch,
199                            struct MeshClient *c,
200                            MESH_ChannelNumber chid);
201
202 /**
203  * Handler for mesh network payload traffic.
204  *
205  * @param ch Channel for the message.
206  * @param message Unencryted data message.
207  * @param fwd Is this FWD traffic? GNUNET_YES : GNUNET_NO;
208  */
209 void
210 GMCH_handle_data (struct MeshChannel *ch,
211                   const struct GNUNET_MESH_Data *msg,
212                   int fwd);
213
214 /**
215  * Handler for mesh network traffic end-to-end ACKs.
216  *
217  * @param t Tunnel on which we got this message.
218  * @param message Data message.
219  * @param fwd Is this a fwd ACK? (dest->orig)
220  */
221 void
222 GMCH_handle_data_ack (struct MeshChannel *ch,
223                       const struct GNUNET_MESH_DataACK *msg,
224                       int fwd);
225
226 /**
227  * Handler for channel create messages.
228  *
229  * @param t Tunnel this channel is to be created in.
230  * @param msg Message.
231  * @param fwd Is this FWD traffic? GNUNET_YES : GNUNET_NO;
232  */
233 struct MeshChannel *
234 GMCH_handle_create (const struct GNUNET_MESH_ChannelCreate *msg,
235                     int fwd);
236
237 /**
238  * Handler for channel ack messages.
239  *
240  * @param t Tunnel this channel is to be created in.
241  * @param msg Message.
242  * @param fwd Is this FWD traffic? GNUNET_YES : GNUNET_NO;
243  */
244 void
245 GMCH_handle_ack (struct MeshChannel *ch,
246                  const struct GNUNET_MESH_ChannelManage *msg,
247                  int fwd);
248
249 /**
250  * Handler for channel destroy messages.
251  *
252  * @param t Tunnel this channel is to be destroyed of.
253  * @param msg Message.
254  * @param fwd Is this FWD traffic? GNUNET_YES : GNUNET_NO;
255  */
256 void
257 GMCH_handle_destroy (struct MeshChannel *ch,
258                      const struct GNUNET_MESH_ChannelManage *msg,
259                      int fwd);
260
261 /**
262  * Sends an already built message on a channel.
263  *
264  * If the channel is on a loopback tunnel, notifies the appropriate destination
265  * client locally.
266  *
267  * On a normal channel passes the message to the tunnel for encryption and
268  * sending on a connection.
269  *
270  * @param message Message to send. Function makes a copy of it.
271  * @param ch Channel on which this message is transmitted.
272  * @param fwd Is this a fwd message?
273  */
274 void
275 GMCH_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
276                             struct MeshChannel *ch, int fwd);
277
278
279 #if 0                           /* keep Emacsens' auto-indent happy */
280 {
281 #endif
282 #ifdef __cplusplus
283 }
284 #endif
285
286 /* ifndef GNUNET_SERVICE_MESH_CHANNEL_H */
287 #endif
288 /* end of gnunet-service-mesh_channel.h */