aboutsummaryrefslogtreecommitdiff
path: root/src/cadet/gnunet-service-cadet_peer.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/cadet/gnunet-service-cadet_peer.h')
-rw-r--r--src/cadet/gnunet-service-cadet_peer.h427
1 files changed, 0 insertions, 427 deletions
diff --git a/src/cadet/gnunet-service-cadet_peer.h b/src/cadet/gnunet-service-cadet_peer.h
deleted file mode 100644
index 7a39615ff..000000000
--- a/src/cadet/gnunet-service-cadet_peer.h
+++ /dev/null
@@ -1,427 +0,0 @@
1/*
2 This file is part of GNUnet.
3 Copyright (C) 2001-2017 GNUnet e.V.
4
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.
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 Affero General Public License for more details.
14
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/>.
17
18 SPDX-License-Identifier: AGPL3.0-or-later
19 */
20
21/**
22 * @file cadet/gnunet-service-cadet_peer.h
23 * @brief Information we track per peer.
24 * @author Bartlomiej Polot
25 * @author Christian Grothoff
26 */
27#ifndef GNUNET_SERVICE_CADET_PEER_H
28#define GNUNET_SERVICE_CADET_PEER_H
29
30#include "gnunet-service-cadet.h"
31#include "gnunet_hello_lib.h"
32
33
34/**
35 * Get the static string for a peer ID.
36 *
37 * @param peer Peer.
38 *
39 * @return Static string for it's ID.
40 */
41const char *
42GCP_2s (const struct CadetPeer *peer);
43
44
45/**
46 * Retrieve the CadetPeer structure associated with the
47 * peer. Optionally create one and insert it in the appropriate
48 * structures if the peer is not known yet.
49 *
50 * @param peer_id Full identity of the peer.
51 * @param create #GNUNET_YES if a new peer should be created if unknown.
52 * #GNUNET_NO to return NULL if peer is unknown.
53 * @return Existing or newly created peer structure.
54 * NULL if unknown and not requested @a create
55 */
56struct CadetPeer *
57GCP_get (const struct GNUNET_PeerIdentity *peer_id,
58 int create);
59
60
61/**
62 * Calculate how desirable a path is for @a cp if
63 * @a cp is at offset @a off in the path.
64 *
65 * @param cp a peer reachable via a path
66 * @param off offset of @a cp in a path
67 * @return score how useful a path is to reach @a cp,
68 * positive scores mean path is more desirable
69 */
70double
71GCP_get_desirability_of_path (struct CadetPeer *cp,
72 unsigned int off);
73
74
75/**
76 * Obtain the peer identity for a `struct CadetPeer`.
77 *
78 * @param cp our peer handle
79 * @return the peer identity
80 */
81const struct GNUNET_PeerIdentity *
82GCP_get_id (struct CadetPeer *cp);
83
84
85/**
86 * Iterate over all known peers.
87 *
88 * @param iter Iterator.
89 * @param cls Closure for @c iter.
90 */
91void
92GCP_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter,
93 void *cls);
94
95
96/**
97 * Count the number of known paths toward the peer.
98 *
99 * @param cp Peer to get path info.
100 * @return Number of known paths.
101 */
102unsigned int
103GCP_count_paths (const struct CadetPeer *cp);
104
105
106/**
107 * Drop all paths owned by this peer, and do not
108 * allow new ones to be added: We are shutting down.
109 *
110 * @param cp peer to drop paths to
111 */
112void
113GCP_drop_owned_paths (struct CadetPeer *cp);
114
115
116/**
117 * Peer path iterator.
118 *
119 * @param cls Closure.
120 * @param path Path itself
121 * @param off offset of the target peer in @a path
122 * @return #GNUNET_YES if should keep iterating.
123 * #GNUNET_NO otherwise.
124 */
125typedef int
126(*GCP_PathIterator) (void *cls,
127 struct CadetPeerPath *path,
128 unsigned int off);
129
130
131/**
132 * Iterate over the paths to a peer.
133 *
134 * @param cp Peer to get path info.
135 * @param callback Function to call for every path.
136 * @param callback_cls Closure for @a callback.
137 * @return Number of iterated paths.
138 */
139unsigned int
140GCP_iterate_paths (struct CadetPeer *cp,
141 GCP_PathIterator callback,
142 void *callback_cls);
143
144/**
145 * Iterate over the paths to a peer without direct link.
146 *
147 * @param cp Peer to get path info.
148 * @param callback Function to call for every path.
149 * @param callback_cls Closure for @a callback.
150 * @return Number of iterated paths.
151 */
152unsigned int
153GCP_iterate_indirect_paths (struct CadetPeer *cp,
154 GCP_PathIterator callback,
155 void *callback_cls);
156
157
158/**
159 * Iterate over the paths to @a peer where
160 * @a peer is at distance @a dist from us.
161 *
162 * @param cp Peer to get path info.
163 * @param dist desired distance of @a peer to us on the path
164 * @param callback Function to call for every path.
165 * @param callback_cls Closure for @a callback.
166 * @return Number of iterated paths.
167 */
168unsigned int
169GCP_iterate_paths_at (struct CadetPeer *cp,
170 unsigned int dist,
171 GCP_PathIterator callback,
172 void *callback_cls);
173
174
175/**
176 * Remove an entry from the DLL of all of the paths that this peer is on.
177 *
178 * @param cp peer to modify
179 * @param entry an entry on a path
180 * @param off offset of this peer on the path
181 */
182void
183GCP_path_entry_remove (struct CadetPeer *cp,
184 struct CadetPeerPathEntry *entry,
185 unsigned int off);
186
187
188/**
189 * Add an entry to the DLL of all of the paths that this peer is on.
190 *
191 * @param cp peer to modify
192 * @param entry an entry on a path
193 * @param off offset of this peer on the path
194 */
195void
196GCP_path_entry_add (struct CadetPeer *cp,
197 struct CadetPeerPathEntry *entry,
198 unsigned int off);
199
200
201/**
202 * Get the tunnel towards a peer.
203 *
204 * @param cp Peer to get from.
205 * @param create #GNUNET_YES to create a tunnel if we do not have one
206 * @return Tunnel towards peer.
207 */
208struct CadetTunnel *
209GCP_get_tunnel (struct CadetPeer *cp,
210 int create);
211
212
213/**
214 * The tunnel to the given peer no longer exists, remove it from our
215 * data structures, and possibly clean up the peer itself.
216 *
217 * @param cp the peer affected
218 * @param t the dead tunnel
219 */
220void
221GCP_drop_tunnel (struct CadetPeer *cp,
222 struct CadetTunnel *t);
223
224
225/**
226 * Try adding a @a path to this @a cp. If the peer already
227 * has plenty of paths, return NULL.
228 *
229 * @param cp peer to which the @a path leads to
230 * @param path a path looking for an owner; may not be fully initialized yet!
231 * @param off offset of @a cp in @a path
232 * @param force for attaching the path
233 * @return NULL if this peer does not care to become a new owner,
234 * otherwise the node in the peer's path heap for the @a path.
235 */
236struct GNUNET_CONTAINER_HeapNode *
237GCP_attach_path (struct CadetPeer *cp,
238 struct CadetPeerPath *path,
239 unsigned int off,
240 int force);
241
242
243/**
244 * This peer can no longer own @a path as the path
245 * has been extended and a peer further down the line
246 * is now the new owner.
247 *
248 * @param cp old owner of the @a path
249 * @param path path where the ownership is lost
250 * @param hn note in @a cp's path heap that must be deleted
251 */
252void
253GCP_detach_path (struct CadetPeer *cp,
254 struct CadetPeerPath *path,
255 struct GNUNET_CONTAINER_HeapNode *hn);
256
257
258/**
259 * Add a @a connection to this @a cp.
260 *
261 * @param cp peer via which the @a connection goes
262 * @param cc the connection to add
263 */
264void
265GCP_add_connection (struct CadetPeer *cp,
266 struct CadetConnection *cc);
267
268
269/**
270 * Remove a @a connection that went via this @a cp.
271 *
272 * @param cp peer via which the @a connection went
273 * @param cc the connection to remove
274 */
275void
276GCP_remove_connection (struct CadetPeer *cp,
277 struct CadetConnection *cc);
278
279
280/**
281 * We got a HELLO for a @a cp, remember it, and possibly
282 * trigger adequate actions (like trying to connect).
283 *
284 * @param cp the peer we got a HELLO for
285 * @param hello the HELLO to remember
286 */
287void
288GCP_set_hello (struct CadetPeer *cp,
289 const struct GNUNET_HELLO_Message *hello);
290
291
292/**
293 * Clean up all entries about all peers.
294 * Must only be called after all tunnels, CORE-connections and
295 * connections are down.
296 */
297void
298GCP_destroy_all_peers (void);
299
300
301/**
302 * Data structure used to track whom we have to notify about changes
303 * in our ability to transmit to a given peer.
304 *
305 * All queue managers will be given equal chance for sending messages
306 * to @a cp. This construct this guarantees fairness for access to @a
307 * cp among the different message queues. Each connection or route
308 * will have its respective message queue managers for each direction.
309 */
310struct GCP_MessageQueueManager;
311
312
313/**
314 * Function to call with updated message queue object.
315 *
316 * @param cls closure
317 * @param available #GNUNET_YES if sending is now possible,
318 * #GNUNET_NO if sending is no longer possible
319 * #GNUNET_SYSERR if sending is no longer possible
320 * and the last envelope was discarded
321 */
322typedef void
323(*GCP_MessageQueueNotificationCallback)(void *cls,
324 int available);
325
326
327/**
328 * Start message queue change notifications. Will create a new slot
329 * to manage the message queue to the given @a cp.
330 *
331 * @param cp peer to notify for
332 * @param cb function to call if mq becomes available or unavailable
333 * @param cb_cls closure for @a cb
334 * @return handle to cancel request
335 */
336struct GCP_MessageQueueManager *
337GCP_request_mq (struct CadetPeer *cp,
338 GCP_MessageQueueNotificationCallback cb,
339 void *cb_cls);
340
341
342/**
343 * Test if @a cp has a core-level connection
344 *
345 * @param cp peer to test
346 * @return #GNUNET_YES if @a cp has a core-level connection
347 */
348int
349GCP_has_core_connection (struct CadetPeer *cp);
350
351
352/**
353 * Send the message in @a env via a @a mqm. Must only be called at
354 * most once after the respective
355 * #GCP_MessageQueueNotificationCallback was called with `available`
356 * set to #GNUNET_YES, and not after the callback was called with
357 * `available` set to #GNUNET_NO or #GNUNET_SYSERR.
358 *
359 * @param mqm message queue manager for the transmission
360 * @param env envelope with the message to send; must NOT
361 * yet have a #GNUNET_MQ_notify_sent() callback attached to it
362 */
363void
364GCP_send (struct GCP_MessageQueueManager *mqm,
365 struct GNUNET_MQ_Envelope *env);
366
367
368/**
369 * Send the message in @a env to @a cp, overriding queueing logic.
370 * This function should only be used to send error messages outside
371 * of flow and congestion control, similar to ICMP. Note that
372 * the envelope may be silently discarded as well.
373 *
374 * @param cp peer to send the message to
375 * @param env envelope with the message to send
376 */
377void
378GCP_send_ooo (struct CadetPeer *cp,
379 struct GNUNET_MQ_Envelope *env);
380
381
382/**
383 * Stops message queue change notifications and sends a last message.
384 * In practice, this is implemented by sending that @a last_env
385 * message immediately (if any), ignoring queue order.
386 *
387 * @param mqm handle matching request to cancel
388 * @param last_env final message to transmit, or NULL
389 */
390void
391GCP_request_mq_cancel (struct GCP_MessageQueueManager *mqm,
392 struct GNUNET_MQ_Envelope *last_env);
393
394
395/**
396 * Set the message queue to @a mq for peer @a cp and notify watchers.
397 *
398 * @param cp peer to modify
399 * @param mq message queue to set (can be NULL)
400 */
401void
402GCP_set_mq (struct CadetPeer *cp,
403 struct GNUNET_MQ_Handle *mq);
404
405/**
406 * Checking the signature for a monotime of a GNUNET_CADET_ConnectionCreateMessage.
407 *
408 * @param peer The peer that signed the monotime value.
409 * @param msg The GNUNET_CADET_ConnectionCreateMessage with the monotime value.
410 * @return GNUNET_OK if the signature is good, GNUNET_SYSERR if not.
411 */
412int
413GCP_check_monotime_sig (struct CadetPeer *peer, const struct
414 GNUNET_CADET_ConnectionCreateMessage *msg);
415
416/**
417 * Checking if a monotime value is newer than the last monotime value received from a peer. If the time value is newer it will be stored at the peer.
418 *
419 * @param peer The peer we received a new time value from.
420 * @param monotime Time value we check against the last time value we received from a peer.
421 * @return GNUNET_YES if monotime is newer than the last received time value, GNUNET_NO if monotime is not newer.
422 */
423int
424GCP_check_and_update_monotime (struct CadetPeer *peer,
425 struct GNUNET_TIME_AbsoluteNBO monotime);
426
427#endif