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 it
7 under the terms of the GNU Affero General Public License as published
8 by the Free Software Foundation, either version 3 of the License,
9 or (at your 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 Affero General Public License for more details.
16 You should have received a copy of the GNU Affero General Public License
17 along with this program. If not, see <http://www.gnu.org/licenses/>.
21 * @file cadet/gnunet-service-cadet_connection.h
22 * @brief A connection is a live end-to-end messaging mechanism
23 * where the peers are identified by a path and know how
24 * to forward along the route using a connection identifier
25 * for routing the data.
26 * @author Bartlomiej Polot
27 * @author Christian Grothoff
29 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
30 #define GNUNET_SERVICE_CADET_CONNECTION_H
32 #include "gnunet_util_lib.h"
33 #include "gnunet-service-cadet.h"
34 #include "gnunet-service-cadet_peer.h"
35 #include "cadet_protocol.h"
39 * Function called to notify tunnel about change in our readyness.
42 * @param is_ready #GNUNET_YES if the connection is now ready for transmission,
43 * #GNUNET_NO if the connection is no longer ready for transmission
46 (*GCC_ReadyCallback)(void *cls,
51 * Destroy a connection, called when the CORE layer is already done
52 * (i.e. has received a BROKEN message), but if we still have to
53 * communicate the destruction of the connection to the tunnel (if one
56 * @param cc connection to destroy
59 GCC_destroy_without_core (struct CadetConnection *cc);
63 * Destroy a connection, called if the tunnel association with the
64 * connection was already broken, but we still need to notify the CORE
65 * layer about the breakage.
67 * @param cc connection to destroy
70 GCC_destroy_without_tunnel (struct CadetConnection *cc);
74 * Lookup a connection by its identifier.
76 * @param cid identifier to resolve
77 * @return NULL if connection was not found
79 struct CadetConnection *
80 GCC_lookup (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
84 * Create a connection to @a destination via @a path and
85 * notify @a cb whenever we are ready for more data.
87 * @param destination where to go
88 * @param path which path to take (may not be the full path)
89 * @param off offset of @a destination on @a path
90 * @param options options for the connection
91 * @param ct which tunnel uses this connection
92 * @param ready_cb function to call when ready to transmit
93 * @param ready_cb_cls closure for @a cb
94 * @return handle to the connection
96 struct CadetConnection *
97 GCC_create (struct CadetPeer *destination,
98 struct CadetPeerPath *path,
100 enum GNUNET_CADET_ChannelOption options,
101 struct CadetTConnection *ct,
102 GCC_ReadyCallback ready_cb,
107 * Create a connection to @a destination via @a path and
108 * notify @a cb whenever we are ready for more data. This
109 * is an inbound tunnel, so we must use the existing @a cid
111 * @param destination where to go
112 * @param path which path to take (may not be the full path)
113 * @param options options for the connection
114 * @param ct which tunnel uses this connection
115 * @param ready_cb function to call when ready to transmit
116 * @param ready_cb_cls closure for @a cb
117 * @return handle to the connection, NULL if we already have
118 * a connection that takes precedence on @a path
120 struct CadetConnection *
121 GCC_create_inbound (struct CadetPeer *destination,
122 struct CadetPeerPath *path,
123 enum GNUNET_CADET_ChannelOption options,
124 struct CadetTConnection *ct,
125 const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
126 GCC_ReadyCallback ready_cb,
131 * Transmit message @a msg via connection @a cc. Must only be called
132 * (once) after the connection has signalled that it is ready via the
133 * `ready_cb`. Clients can also use #GCC_is_ready() to check if the
134 * connection is right now ready for transmission.
136 * @param cc connection identification
137 * @param env envelope with message to transmit;
138 * the #GNUNET_MQ_notify_send() must not have yet been used
139 * for the envelope. Also, the message better match the
140 * connection identifier of this connection...
143 GCC_transmit (struct CadetConnection *cc,
144 struct GNUNET_MQ_Envelope *env);
148 * A CREATE_ACK was received for this connection, process it.
150 * @param cc the connection that got the ACK.
153 GCC_handle_connection_create_ack (struct CadetConnection *cc);
157 * We got a #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE for a
158 * connection that we already have. Either our ACK got lost
159 * or something is fishy. Consider retransmitting the ACK.
161 * @param cc connection that got the duplicate CREATE
164 GCC_handle_duplicate_create (struct CadetConnection *cc);
170 * @param cc connection that received encrypted message
171 * @param msg the key exchange message
174 GCC_handle_kx (struct CadetConnection *cc,
175 const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
179 * Handle KX_AUTH message.
181 * @param cc connection that received encrypted message
182 * @param msg the key exchange message
185 GCC_handle_kx_auth (struct CadetConnection *cc,
186 const struct GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
190 * Performance metrics for a connection.
192 struct CadetConnectionMetrics
196 * Our current best estimate of the latency, based on a weighted
197 * average of at least @a latency_datapoints values.
199 struct GNUNET_TIME_Relative aged_latency;
202 * When was this connection first established? (by us sending or
203 * receiving the CREATE_ACK for the first time)
205 struct GNUNET_TIME_Absolute age;
208 * When was this connection last used? (by us sending or
209 * receiving a PAYLOAD message on it)
211 struct GNUNET_TIME_Absolute last_use;
214 * How many packets that ought to generate an ACK did we send via
217 unsigned long long num_acked_transmissions;
220 * Number of packets that were sent via this connection did actually
221 * receive an ACK? (Note: ACKs may be transmitted and lost via
222 * other connections, so this value should only be interpreted
223 * relative to @e num_acked_transmissions and in relation to other
226 unsigned long long num_successes;
232 * Obtain performance @a metrics from @a cc.
234 * @param cc connection to query
235 * @return the metrics
237 const struct CadetConnectionMetrics *
238 GCC_get_metrics (struct CadetConnection *cc);
242 * Handle encrypted message.
244 * @param cc connection that received encrypted message
245 * @param msg the encrypted message to decrypt
248 GCC_handle_encrypted (struct CadetConnection *cc,
249 const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
253 * We sent a message for which we expect to receive an ACK via
254 * the connection identified by @a cti.
256 * @param cid connection identifier where we expect an ACK
259 GCC_ack_expected (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
263 * We observed an ACK for a message that was originally sent via
264 * the connection identified by @a cti.
266 * @param cid connection identifier where we got an ACK for a message
267 * that was originally sent via this connection (the ACK
268 * may have gotten back to us via a different connection).
271 GCC_ack_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
275 * We observed some the given @a latency on the connection
276 * identified by @a cti. (The same connection was taken
277 * in both directions.)
279 * @param cti connection identifier where we measured latency
280 * @param latency the observed latency
283 GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
284 struct GNUNET_TIME_Relative latency);
288 * Return the tunnel associated with this connection.
290 * @param cc connection to query
291 * @return corresponding entry in the tunnel's connection list
293 struct CadetTConnection *
294 GCC_get_ct (struct CadetConnection *cc);
298 * Obtain the path used by this connection.
300 * @param cc connection
301 * @param off[out] set to offset in this path where the connection @a cc ends
302 * @return path to @a cc
304 struct CadetPeerPath *
305 GCC_get_path (struct CadetConnection *cc,
310 * Obtain unique ID for the connection.
312 * @param cc connection.
313 * @return unique number of the connection
315 const struct GNUNET_CADET_ConnectionTunnelIdentifier *
316 GCC_get_id (struct CadetConnection *cc);
320 * Get a (static) string for a connection.
322 * @param cc Connection.
325 GCC_2s (const struct CadetConnection *cc);
329 * Log connection info.
331 * @param cc connection
332 * @param level Debug level to use.
335 GCC_debug (struct CadetConnection *cc,
336 enum GNUNET_ErrorType level);