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.
18 * @file cadet/gnunet-service-cadet_connection.h
19 * @brief A connection is a live end-to-end messaging mechanism
20 * where the peers are identified by a path and know how
21 * to forward along the route using a connection identifier
22 * for routing the data.
23 * @author Bartlomiej Polot
24 * @author Christian Grothoff
26 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
27 #define GNUNET_SERVICE_CADET_CONNECTION_H
29 #include "gnunet_util_lib.h"
30 #include "gnunet-service-cadet.h"
31 #include "gnunet-service-cadet_peer.h"
32 #include "cadet_protocol.h"
36 * Function called to notify tunnel about change in our readyness.
39 * @param is_ready #GNUNET_YES if the connection is now ready for transmission,
40 * #GNUNET_NO if the connection is no longer ready for transmission
43 (*GCC_ReadyCallback)(void *cls,
48 * Destroy a connection, called when the CORE layer is already done
49 * (i.e. has received a BROKEN message), but if we still have to
50 * communicate the destruction of the connection to the tunnel (if one
53 * @param cc connection to destroy
56 GCC_destroy_without_core (struct CadetConnection *cc);
60 * Destroy a connection, called if the tunnel association with the
61 * connection was already broken, but we still need to notify the CORE
62 * layer about the breakage.
64 * @param cc connection to destroy
67 GCC_destroy_without_tunnel (struct CadetConnection *cc);
71 * Lookup a connection by its identifier.
73 * @param cid identifier to resolve
74 * @return NULL if connection was not found
76 struct CadetConnection *
77 GCC_lookup (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
81 * Create a connection to @a destination via @a path and
82 * notify @a cb whenever we are ready for more data.
84 * @param destination where to go
85 * @param path which path to take (may not be the full path)
86 * @param off offset of @a destination on @a path
87 * @param options options for the connection
88 * @param ct which tunnel uses this connection
89 * @param ready_cb function to call when ready to transmit
90 * @param ready_cb_cls closure for @a cb
91 * @return handle to the connection
93 struct CadetConnection *
94 GCC_create (struct CadetPeer *destination,
95 struct CadetPeerPath *path,
97 enum GNUNET_CADET_ChannelOption options,
98 struct CadetTConnection *ct,
99 GCC_ReadyCallback ready_cb,
104 * Create a connection to @a destination via @a path and
105 * notify @a cb whenever we are ready for more data. This
106 * is an inbound tunnel, so we must use the existing @a cid
108 * @param destination where to go
109 * @param path which path to take (may not be the full path)
110 * @param options options for the connection
111 * @param ct which tunnel uses this connection
112 * @param ready_cb function to call when ready to transmit
113 * @param ready_cb_cls closure for @a cb
114 * @return handle to the connection, NULL if we already have
115 * a connection that takes precedence on @a path
117 struct CadetConnection *
118 GCC_create_inbound (struct CadetPeer *destination,
119 struct CadetPeerPath *path,
120 enum GNUNET_CADET_ChannelOption options,
121 struct CadetTConnection *ct,
122 const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
123 GCC_ReadyCallback ready_cb,
128 * Transmit message @a msg via connection @a cc. Must only be called
129 * (once) after the connection has signalled that it is ready via the
130 * `ready_cb`. Clients can also use #GCC_is_ready() to check if the
131 * connection is right now ready for transmission.
133 * @param cc connection identification
134 * @param env envelope with message to transmit;
135 * the #GNUNET_MQ_notify_send() must not have yet been used
136 * for the envelope. Also, the message better match the
137 * connection identifier of this connection...
140 GCC_transmit (struct CadetConnection *cc,
141 struct GNUNET_MQ_Envelope *env);
145 * A CREATE_ACK was received for this connection, process it.
147 * @param cc the connection that got the ACK.
150 GCC_handle_connection_create_ack (struct CadetConnection *cc);
154 * We got a #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE for a
155 * connection that we already have. Either our ACK got lost
156 * or something is fishy. Consider retransmitting the ACK.
158 * @param cc connection that got the duplicate CREATE
161 GCC_handle_duplicate_create (struct CadetConnection *cc);
167 * @param cc connection that received encrypted message
168 * @param msg the key exchange message
171 GCC_handle_kx (struct CadetConnection *cc,
172 const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
176 * Handle KX_AUTH message.
178 * @param cc connection that received encrypted message
179 * @param msg the key exchange message
182 GCC_handle_kx_auth (struct CadetConnection *cc,
183 const struct GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
187 * Performance metrics for a connection.
189 struct CadetConnectionMetrics
193 * Our current best estimate of the latency, based on a weighted
194 * average of at least @a latency_datapoints values.
196 struct GNUNET_TIME_Relative aged_latency;
199 * When was this connection first established? (by us sending or
200 * receiving the CREATE_ACK for the first time)
202 struct GNUNET_TIME_Absolute age;
205 * When was this connection last used? (by us sending or
206 * receiving a PAYLOAD message on it)
208 struct GNUNET_TIME_Absolute last_use;
211 * How many packets that ought to generate an ACK did we send via
214 unsigned long long num_acked_transmissions;
217 * Number of packets that were sent via this connection did actually
218 * receive an ACK? (Note: ACKs may be transmitted and lost via
219 * other connections, so this value should only be interpreted
220 * relative to @e num_acked_transmissions and in relation to other
223 unsigned long long num_successes;
229 * Obtain performance @a metrics from @a cc.
231 * @param cc connection to query
232 * @return the metrics
234 const struct CadetConnectionMetrics *
235 GCC_get_metrics (struct CadetConnection *cc);
239 * Handle encrypted message.
241 * @param cc connection that received encrypted message
242 * @param msg the encrypted message to decrypt
245 GCC_handle_encrypted (struct CadetConnection *cc,
246 const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
250 * We sent a message for which we expect to receive an ACK via
251 * the connection identified by @a cti.
253 * @param cid connection identifier where we expect an ACK
256 GCC_ack_expected (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
260 * We observed an ACK for a message that was originally sent via
261 * the connection identified by @a cti.
263 * @param cid connection identifier where we got an ACK for a message
264 * that was originally sent via this connection (the ACK
265 * may have gotten back to us via a different connection).
268 GCC_ack_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
272 * We observed some the given @a latency on the connection
273 * identified by @a cti. (The same connection was taken
274 * in both directions.)
276 * @param cti connection identifier where we measured latency
277 * @param latency the observed latency
280 GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
281 struct GNUNET_TIME_Relative latency);
285 * Return the tunnel associated with this connection.
287 * @param cc connection to query
288 * @return corresponding entry in the tunnel's connection list
290 struct CadetTConnection *
291 GCC_get_ct (struct CadetConnection *cc);
295 * Obtain the path used by this connection.
297 * @param cc connection
298 * @param off[out] set to offset in this path where the connection @a cc ends
299 * @return path to @a cc
301 struct CadetPeerPath *
302 GCC_get_path (struct CadetConnection *cc,
307 * Obtain unique ID for the connection.
309 * @param cc connection.
310 * @return unique number of the connection
312 const struct GNUNET_CADET_ConnectionTunnelIdentifier *
313 GCC_get_id (struct CadetConnection *cc);
317 * Get a (static) string for a connection.
319 * @param cc Connection.
322 GCC_2s (const struct CadetConnection *cc);
326 * Log connection info.
328 * @param cc connection
329 * @param level Debug level to use.
332 GCC_debug (struct CadetConnection *cc,
333 enum GNUNET_ErrorType level);