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
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.
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.
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.
23 * @file cadet/gnunet-service-cadet-new_peer.h
24 * @brief Information we track per peer.
25 * @author Bartlomiej Polot
26 * @author Christian Grothoff
28 #ifndef GNUNET_SERVICE_CADET_PEER_H
29 #define GNUNET_SERVICE_CADET_PEER_H
31 #include "gnunet-service-cadet-new.h"
32 #include "gnunet_hello_lib.h"
36 * Get the static string for a peer ID.
40 * @return Static string for it's ID.
43 GCP_2s (const struct CadetPeer *peer);
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.
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
58 GCP_get (const struct GNUNET_PeerIdentity *peer_id,
63 * Obtain the peer identity for a `struct CadetPeer`.
65 * @param cp our peer handle
66 * @return the peer identity
68 const struct GNUNET_PeerIdentity *
69 GCP_get_id (struct CadetPeer *cp);
73 * Iterate over all known peers.
75 * @param iter Iterator.
76 * @param cls Closure for @c iter.
79 GCP_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter,
84 * Count the number of known paths toward the peer.
86 * @param cp Peer to get path info.
87 * @return Number of known paths.
90 GCP_count_paths (const struct CadetPeer *cp);
94 * Drop all paths owned by this peer, and do not
95 * allow new ones to be added: We are shutting down.
97 * @param cp peer to drop paths to
100 GCP_drop_owned_paths (struct CadetPeer *cp);
104 * Peer path iterator.
106 * @param cls Closure.
107 * @param path Path itself
108 * @param off offset of the target peer in @a path
109 * @return #GNUNET_YES if should keep iterating.
110 * #GNUNET_NO otherwise.
113 (*GCP_PathIterator) (void *cls,
114 struct CadetPeerPath *path,
119 * Iterate over the paths to a peer.
121 * @param cp Peer to get path info.
122 * @param callback Function to call for every path.
123 * @param callback_cls Closure for @a callback.
124 * @return Number of iterated paths.
127 GCP_iterate_paths (struct CadetPeer *cp,
128 GCP_PathIterator callback,
133 * Iterate over the paths to @a peer where
134 * @a peer is at distance @a dist from us.
136 * @param cp Peer to get path info.
137 * @param dist desired distance of @a peer to us on the path
138 * @param callback Function to call for every path.
139 * @param callback_cls Closure for @a callback.
140 * @return Number of iterated paths.
143 GCP_iterate_paths_at (struct CadetPeer *cp,
145 GCP_PathIterator callback,
150 * Remove an entry from the DLL of all of the paths that this peer is on.
152 * @param cp peer to modify
153 * @param entry an entry on a path
154 * @param off offset of this peer on the path
157 GCP_path_entry_remove (struct CadetPeer *cp,
158 struct CadetPeerPathEntry *entry,
163 * Add an entry to the DLL of all of the paths that this peer is on.
165 * @param cp peer to modify
166 * @param entry an entry on a path
167 * @param off offset of this peer on the path
170 GCP_path_entry_add (struct CadetPeer *cp,
171 struct CadetPeerPathEntry *entry,
176 * Get the tunnel towards a peer.
178 * @param cp Peer to get from.
179 * @param create #GNUNET_YES to create a tunnel if we do not have one
180 * @return Tunnel towards peer.
183 GCP_get_tunnel (struct CadetPeer *cp,
188 * The tunnel to the given peer no longer exists, remove it from our
189 * data structures, and possibly clean up the peer itself.
191 * @param cp the peer affected
192 * @param t the dead tunnel
195 GCP_drop_tunnel (struct CadetPeer *cp,
196 struct CadetTunnel *t);
200 * Try adding a @a path to this @a cp. If the peer already
201 * has plenty of paths, return NULL.
203 * @param cp peer to which the @a path leads to
204 * @param path a path looking for an owner; may not be fully initialized yet!
205 * @param off offset of @a cp in @a path
206 * @param force for attaching the path
207 * @return NULL if this peer does not care to become a new owner,
208 * otherwise the node in the peer's path heap for the @a path.
210 struct GNUNET_CONTAINER_HeapNode *
211 GCP_attach_path (struct CadetPeer *cp,
212 struct CadetPeerPath *path,
218 * This peer can no longer own @a path as the path
219 * has been extended and a peer further down the line
220 * is now the new owner.
222 * @param cp old owner of the @a path
223 * @param path path where the ownership is lost
224 * @param hn note in @a cp's path heap that must be deleted
227 GCP_detach_path (struct CadetPeer *cp,
228 struct CadetPeerPath *path,
229 struct GNUNET_CONTAINER_HeapNode *hn);
233 * Add a @a connection to this @a cp.
235 * @param cp peer via which the @a connection goes
236 * @param cc the connection to add
239 GCP_add_connection (struct CadetPeer *cp,
240 struct CadetConnection *cc);
244 * Remove a @a connection that went via this @a cp.
246 * @param cp peer via which the @a connection went
247 * @param cc the connection to remove
250 GCP_remove_connection (struct CadetPeer *cp,
251 struct CadetConnection *cc);
255 * We got a HELLO for a @a cp, remember it, and possibly
256 * trigger adequate actions (like trying to connect).
258 * @param cp the peer we got a HELLO for
259 * @param hello the HELLO to remember
262 GCP_set_hello (struct CadetPeer *cp,
263 const struct GNUNET_HELLO_Message *hello);
267 * Clean up all entries about all peers.
268 * Must only be called after all tunnels, CORE-connections and
269 * connections are down.
272 GCP_destroy_all_peers (void);
276 * Data structure used to track whom we have to notify about changes
277 * in our ability to transmit to a given peer.
279 * All queue managers will be given equal chance for sending messages
280 * to @a cp. This construct this guarantees fairness for access to @a
281 * cp among the different message queues. Each connection or route
282 * will have its respective message queue managers for each direction.
284 struct GCP_MessageQueueManager;
288 * Function to call with updated message queue object.
291 * @param available #GNUNET_YES if sending is now possible,
292 * #GNUNET_NO if sending is no longer possible
293 * #GNUNET_SYSERR if sending is no longer possible
294 * and the last envelope was discarded
297 (*GCP_MessageQueueNotificationCallback)(void *cls,
302 * Start message queue change notifications. Will create a new slot
303 * to manage the message queue to the given @a cp.
305 * @param cp peer to notify for
306 * @param cb function to call if mq becomes available or unavailable
307 * @param cb_cls closure for @a cb
308 * @return handle to cancel request
310 struct GCP_MessageQueueManager *
311 GCP_request_mq (struct CadetPeer *cp,
312 GCP_MessageQueueNotificationCallback cb,
317 * Test if @a cp has a core-level connection
319 * @param cp peer to test
320 * @return #GNUNET_YES if @a cp has a core-level connection
323 GCP_has_core_connection (struct CadetPeer *cp);
327 * Send the message in @a env via a @a mqm. Must only be called at
328 * most once after the respective
329 * #GCP_MessageQueueNotificationCallback was called with `available`
330 * set to #GNUNET_YES, and not after the callback was called with
331 * `available` set to #GNUNET_NO or #GNUNET_SYSERR.
333 * @param mqm message queue manager for the transmission
334 * @param env envelope with the message to send; must NOT
335 * yet have a #GNUNET_MQ_notify_sent() callback attached to it
338 GCP_send (struct GCP_MessageQueueManager *mqm,
339 struct GNUNET_MQ_Envelope *env);
343 * Send the message in @a env to @a cp, overriding queueing logic.
344 * This function should only be used to send error messages outside
345 * of flow and congestion control, similar to ICMP. Note that
346 * the envelope may be silently discarded as well.
348 * @param cp peer to send the message to
349 * @param env envelope with the message to send
352 GCP_send_ooo (struct CadetPeer *cp,
353 struct GNUNET_MQ_Envelope *env);
357 * Stops message queue change notifications and sends a last message.
358 * In practice, this is implemented by sending that @a last_env
359 * message immediately (if any), ignoring queue order.
361 * @param mqm handle matching request to cancel
362 * @param last_env final message to transmit, or NULL
365 GCP_request_mq_cancel (struct GCP_MessageQueueManager *mqm,
366 struct GNUNET_MQ_Envelope *last_env);
370 * Set the message queue to @a mq for peer @a cp and notify watchers.
372 * @param cp peer to modify
373 * @param mq message queue to set (can be NULL)
376 GCP_set_mq (struct CadetPeer *cp,
377 struct GNUNET_MQ_Handle *mq);