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