2 This file is part of GNUnet.
3 Copyright (C) 2001-2017 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
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 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @file cadet/gnunet-service-cadet_connection.h
23 * @brief A connection is a live end-to-end messaging mechanism
24 * where the peers are identified by a path and know how
25 * to forward along the route using a connection identifier
26 * for routing the data.
27 * @author Bartlomiej Polot
28 * @author Christian Grothoff
30 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
31 #define GNUNET_SERVICE_CADET_CONNECTION_H
33 #include "gnunet_util_lib.h"
34 #include "gnunet-service-cadet.h"
35 #include "gnunet-service-cadet_peer.h"
36 #include "cadet_protocol.h"
40 * Function called to notify tunnel about change in our readyness.
43 * @param is_ready #GNUNET_YES if the connection is now ready for transmission,
44 * #GNUNET_NO if the connection is no longer ready for transmission
47 (*GCC_ReadyCallback)(void *cls,
52 * Destroy a connection, called when the CORE layer is already done
53 * (i.e. has received a BROKEN message), but if we still have to
54 * communicate the destruction of the connection to the tunnel (if one
57 * @param cc connection to destroy
60 GCC_destroy_without_core (struct CadetConnection *cc);
64 * Destroy a connection, called if the tunnel association with the
65 * connection was already broken, but we still need to notify the CORE
66 * layer about the breakage.
68 * @param cc connection to destroy
71 GCC_destroy_without_tunnel (struct CadetConnection *cc);
75 * Lookup a connection by its identifier.
77 * @param cid identifier to resolve
78 * @return NULL if connection was not found
80 struct CadetConnection *
81 GCC_lookup (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
85 * Create a connection to @a destination via @a path and
86 * notify @a cb whenever we are ready for more data.
88 * @param destination where to go
89 * @param path which path to take (may not be the full path)
90 * @param off offset of @a destination on @a path
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 struct CadetTConnection *ct,
101 GCC_ReadyCallback ready_cb,
106 * Create a connection to @a destination via @a path and
107 * notify @a cb whenever we are ready for more data. This
108 * is an inbound tunnel, so we must use the existing @a cid
110 * @param destination where to go
111 * @param path which path to take (may not be the full path)
112 * @param ct which tunnel uses this connection
113 * @param ready_cb function to call when ready to transmit
114 * @param ready_cb_cls closure for @a cb
115 * @return handle to the connection, NULL if we already have
116 * a connection that takes precedence on @a path
118 struct CadetConnection *
119 GCC_create_inbound (struct CadetPeer *destination,
120 struct CadetPeerPath *path,
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,
184 GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
188 * Performance metrics for a connection.
190 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;
228 * Obtain performance @a metrics from @a cc.
230 * @param cc connection to query
231 * @return the metrics
233 const struct CadetConnectionMetrics *
234 GCC_get_metrics (struct CadetConnection *cc);
238 * Handle encrypted message.
240 * @param cc connection that received encrypted message
241 * @param msg the encrypted message to decrypt
244 GCC_handle_encrypted (struct CadetConnection *cc,
245 const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
249 * We sent a message for which we expect to receive an ACK via
250 * the connection identified by @a cti.
252 * @param cid connection identifier where we expect an ACK
255 GCC_ack_expected (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
259 * We observed an ACK for a message that was originally sent via
260 * the connection identified by @a cti.
262 * @param cid connection identifier where we got an ACK for a message
263 * that was originally sent via this connection (the ACK
264 * may have gotten back to us via a different connection).
267 GCC_ack_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
271 * We observed some the given @a latency on the connection
272 * identified by @a cti. (The same connection was taken
273 * in both directions.)
275 * @param cti connection identifier where we measured latency
276 * @param latency the observed latency
279 GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
280 struct GNUNET_TIME_Relative latency);
284 * Return the tunnel associated with this connection.
286 * @param cc connection to query
287 * @return corresponding entry in the tunnel's connection list
289 struct CadetTConnection *
290 GCC_get_ct (struct CadetConnection *cc);
294 * Obtain the path used by this connection.
296 * @param cc connection
297 * @param off[out] set to offset in this path where the connection @a cc ends
298 * @return path to @a cc
300 struct CadetPeerPath *
301 GCC_get_path (struct CadetConnection *cc,
306 * Obtain unique ID for the connection.
308 * @param cc connection.
309 * @return unique number of the connection
311 const struct GNUNET_CADET_ConnectionTunnelIdentifier *
312 GCC_get_id (struct CadetConnection *cc);
316 * Get a (static) string for a connection.
318 * @param cc Connection.
321 GCC_2s (const struct CadetConnection *cc);
325 * Log connection info.
327 * @param cc connection
328 * @param level Debug level to use.
331 GCC_debug (struct CadetConnection *cc,
332 enum GNUNET_ErrorType level);