diff options
Diffstat (limited to 'src/cadet/gnunet-service-cadet_peer.h')
-rw-r--r-- | src/cadet/gnunet-service-cadet_peer.h | 394 |
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 | */ | ||
42 | const char * | ||
43 | GCP_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 | */ | ||
57 | struct CadetPeer * | ||
58 | GCP_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 | */ | ||
71 | double | ||
72 | GCP_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 | */ | ||
82 | const struct GNUNET_PeerIdentity * | ||
83 | GCP_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 | */ | ||
92 | void | ||
93 | GCP_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 | */ | ||
103 | unsigned int | ||
104 | GCP_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 | */ | ||
113 | void | ||
114 | GCP_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 | */ | ||
126 | typedef 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 | */ | ||
140 | unsigned int | ||
141 | GCP_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 | */ | ||
156 | unsigned int | ||
157 | GCP_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 | */ | ||
170 | void | ||
171 | GCP_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 | */ | ||
183 | void | ||
184 | GCP_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 | */ | ||
196 | struct CadetTunnel * | ||
197 | GCP_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 | */ | ||
208 | void | ||
209 | GCP_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 | */ | ||
224 | struct GNUNET_CONTAINER_HeapNode * | ||
225 | GCP_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 | */ | ||
240 | void | ||
241 | GCP_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 | */ | ||
252 | void | ||
253 | GCP_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 | */ | ||
263 | void | ||
264 | GCP_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 | */ | ||
275 | void | ||
276 | GCP_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 | */ | ||
285 | void | ||
286 | GCP_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 | */ | ||
298 | struct 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 | */ | ||
310 | typedef 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 | */ | ||
324 | struct GCP_MessageQueueManager * | ||
325 | GCP_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 | */ | ||
336 | int | ||
337 | GCP_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 | */ | ||
351 | void | ||
352 | GCP_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 | */ | ||
365 | void | ||
366 | GCP_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 | */ | ||
378 | void | ||
379 | GCP_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 | */ | ||
389 | void | ||
390 | GCP_set_mq (struct CadetPeer *cp, | ||
391 | struct GNUNET_MQ_Handle *mq); | ||
392 | |||
393 | |||
394 | #endif | ||