diff options
Diffstat (limited to 'src/cadet/gnunet-service-cadet-new_peer.h')
-rw-r--r-- | src/cadet/gnunet-service-cadet-new_peer.h | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/src/cadet/gnunet-service-cadet-new_peer.h b/src/cadet/gnunet-service-cadet-new_peer.h new file mode 100644 index 000000000..c633f47e5 --- /dev/null +++ b/src/cadet/gnunet-service-cadet-new_peer.h | |||
@@ -0,0 +1,368 @@ | |||
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-new.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 | * Obtain the peer identity for a `struct CadetPeer`. | ||
64 | * | ||
65 | * @param cp our peer handle | ||
66 | * @return the peer identity | ||
67 | */ | ||
68 | const struct GNUNET_PeerIdentity * | ||
69 | GCP_get_id (struct CadetPeer *cp); | ||
70 | |||
71 | |||
72 | /** | ||
73 | * Iterate over all known peers. | ||
74 | * | ||
75 | * @param iter Iterator. | ||
76 | * @param cls Closure for @c iter. | ||
77 | */ | ||
78 | void | ||
79 | GCP_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter, | ||
80 | void *cls); | ||
81 | |||
82 | |||
83 | /** | ||
84 | * Count the number of known paths toward the peer. | ||
85 | * | ||
86 | * @param cp Peer to get path info. | ||
87 | * @return Number of known paths. | ||
88 | */ | ||
89 | unsigned int | ||
90 | GCP_count_paths (const struct CadetPeer *cp); | ||
91 | |||
92 | |||
93 | /** | ||
94 | * Peer path iterator. | ||
95 | * | ||
96 | * @param cls Closure. | ||
97 | * @param path Path itself | ||
98 | * @param off offset of the target peer in @a path | ||
99 | * @return #GNUNET_YES if should keep iterating. | ||
100 | * #GNUNET_NO otherwise. | ||
101 | */ | ||
102 | typedef int | ||
103 | (*GCP_PathIterator) (void *cls, | ||
104 | struct CadetPeerPath *path, | ||
105 | unsigned int off); | ||
106 | |||
107 | |||
108 | /** | ||
109 | * Iterate over the paths to a peer. | ||
110 | * | ||
111 | * @param cp Peer to get path info. | ||
112 | * @param callback Function to call for every path. | ||
113 | * @param callback_cls Closure for @a callback. | ||
114 | * @return Number of iterated paths. | ||
115 | */ | ||
116 | unsigned int | ||
117 | GCP_iterate_paths (struct CadetPeer *cp, | ||
118 | GCP_PathIterator callback, | ||
119 | void *callback_cls); | ||
120 | |||
121 | |||
122 | /** | ||
123 | * Iterate over the paths to @a peer where | ||
124 | * @a peer is at distance @a dist from us. | ||
125 | * | ||
126 | * @param peer Peer to get path info. | ||
127 | * @param dist desired distance of @a peer to us on the path | ||
128 | * @param callback Function to call for every path. | ||
129 | * @param callback_cls Closure for @a callback. | ||
130 | * @return Number of iterated paths. | ||
131 | */ | ||
132 | unsigned int | ||
133 | GCP_iterate_paths_at (struct CadetPeer *peer, | ||
134 | unsigned int dist, | ||
135 | GCP_PathIterator callback, | ||
136 | void *callback_cls); | ||
137 | |||
138 | |||
139 | /** | ||
140 | * Remove an entry from the DLL of all of the paths that this peer is on. | ||
141 | * | ||
142 | * @param cp peer to modify | ||
143 | * @param entry an entry on a path | ||
144 | * @param off offset of this peer on the path | ||
145 | */ | ||
146 | void | ||
147 | GCP_path_entry_remove (struct CadetPeer *cp, | ||
148 | struct CadetPeerPathEntry *entry, | ||
149 | unsigned int off); | ||
150 | |||
151 | |||
152 | /** | ||
153 | * Add an entry to the DLL of all of the paths that this peer is on. | ||
154 | * | ||
155 | * @param cp peer to modify | ||
156 | * @param entry an entry on a path | ||
157 | * @param off offset of this peer on the path | ||
158 | */ | ||
159 | void | ||
160 | GCP_path_entry_add (struct CadetPeer *cp, | ||
161 | struct CadetPeerPathEntry *entry, | ||
162 | unsigned int off); | ||
163 | |||
164 | |||
165 | /** | ||
166 | * Get the tunnel towards a peer. | ||
167 | * | ||
168 | * @param cp Peer to get from. | ||
169 | * @param create #GNUNET_YES to create a tunnel if we do not have one | ||
170 | * @return Tunnel towards peer. | ||
171 | */ | ||
172 | struct CadetTunnel * | ||
173 | GCP_get_tunnel (struct CadetPeer *cp, | ||
174 | int create); | ||
175 | |||
176 | |||
177 | /** | ||
178 | * The tunnel to the given peer no longer exists, remove it from our | ||
179 | * data structures, and possibly clean up the peer itself. | ||
180 | * | ||
181 | * @param cp the peer affected | ||
182 | * @param t the dead tunnel | ||
183 | */ | ||
184 | void | ||
185 | GCP_drop_tunnel (struct CadetPeer *cp, | ||
186 | struct CadetTunnel *t); | ||
187 | |||
188 | |||
189 | /** | ||
190 | * Try adding a @a path to this @a cp. If the peer already | ||
191 | * has plenty of paths, return NULL. | ||
192 | * | ||
193 | * @param cp peer to which the @a path leads to | ||
194 | * @param path a path looking for an owner; may not be fully initialized yet! | ||
195 | * @param off offset of @a cp in @a path | ||
196 | * @return NULL if this peer does not care to become a new owner, | ||
197 | * otherwise the node in the peer's path heap for the @a path. | ||
198 | */ | ||
199 | struct GNUNET_CONTAINER_HeapNode * | ||
200 | GCP_attach_path (struct CadetPeer *cp, | ||
201 | struct CadetPeerPath *path, | ||
202 | unsigned int off); | ||
203 | |||
204 | |||
205 | /** | ||
206 | * This peer can no longer own @a path as the path | ||
207 | * has been extended and a peer further down the line | ||
208 | * is now the new owner. | ||
209 | * | ||
210 | * @param cp old owner of the @a path | ||
211 | * @param path path where the ownership is lost | ||
212 | * @param hn note in @a cp's path heap that must be deleted | ||
213 | */ | ||
214 | void | ||
215 | GCP_detach_path (struct CadetPeer *cp, | ||
216 | struct CadetPeerPath *path, | ||
217 | struct GNUNET_CONTAINER_HeapNode *hn); | ||
218 | |||
219 | |||
220 | /** | ||
221 | * Add a @a connection to this @a cp. | ||
222 | * | ||
223 | * @param cp peer via which the @a connection goes | ||
224 | * @param cc the connection to add | ||
225 | */ | ||
226 | void | ||
227 | GCP_add_connection (struct CadetPeer *cp, | ||
228 | struct CadetConnection *cc); | ||
229 | |||
230 | |||
231 | /** | ||
232 | * Remove a @a connection that went via this @a cp. | ||
233 | * | ||
234 | * @param cp peer via which the @a connection went | ||
235 | * @param cc the connection to remove | ||
236 | */ | ||
237 | void | ||
238 | GCP_remove_connection (struct CadetPeer *cp, | ||
239 | struct CadetConnection *cc); | ||
240 | |||
241 | |||
242 | /** | ||
243 | * We got a HELLO for a @a cp, remember it, and possibly | ||
244 | * trigger adequate actions (like trying to connect). | ||
245 | * | ||
246 | * @param cp the peer we got a HELLO for | ||
247 | * @param hello the HELLO to remember | ||
248 | */ | ||
249 | void | ||
250 | GCP_set_hello (struct CadetPeer *cp, | ||
251 | const struct GNUNET_HELLO_Message *hello); | ||
252 | |||
253 | |||
254 | /** | ||
255 | * Clean up all entries about all peers. | ||
256 | * Must only be called after all tunnels, CORE-connections and | ||
257 | * connections are down. | ||
258 | */ | ||
259 | void | ||
260 | GCP_destroy_all_peers (void); | ||
261 | |||
262 | |||
263 | /** | ||
264 | * Data structure used to track whom we have to notify about changes | ||
265 | * in our ability to transmit to a given peer. | ||
266 | * | ||
267 | * All queue managers will be given equal chance for sending messages | ||
268 | * to @a cp. This construct this guarantees fairness for access to @a | ||
269 | * cp among the different message queues. Each connection or route | ||
270 | * will have its respective message queue managers for each direction. | ||
271 | */ | ||
272 | struct GCP_MessageQueueManager; | ||
273 | |||
274 | |||
275 | /** | ||
276 | * Function to call with updated message queue object. | ||
277 | * | ||
278 | * @param cls closure | ||
279 | * @param available #GNUNET_YES if sending is now possible, | ||
280 | * #GNUNET_NO if sending is no longer possible | ||
281 | * #GNUNET_SYSERR if sending is no longer possible | ||
282 | * and the last envelope was discarded | ||
283 | */ | ||
284 | typedef void | ||
285 | (*GCP_MessageQueueNotificationCallback)(void *cls, | ||
286 | int available); | ||
287 | |||
288 | |||
289 | /** | ||
290 | * Start message queue change notifications. Will create a new slot | ||
291 | * to manage the message queue to the given @a cp. | ||
292 | * | ||
293 | * @param cp peer to notify for | ||
294 | * @param cb function to call if mq becomes available or unavailable | ||
295 | * @param cb_cls closure for @a cb | ||
296 | * @return handle to cancel request | ||
297 | */ | ||
298 | struct GCP_MessageQueueManager * | ||
299 | GCP_request_mq (struct CadetPeer *cp, | ||
300 | GCP_MessageQueueNotificationCallback cb, | ||
301 | void *cb_cls); | ||
302 | |||
303 | |||
304 | /** | ||
305 | * Test if @a cp has a core-level connection | ||
306 | * | ||
307 | * @param cp peer to test | ||
308 | * @return #GNUNET_YES if @a cp has a core-level connection | ||
309 | */ | ||
310 | int | ||
311 | GCP_has_core_connection (struct CadetPeer *cp); | ||
312 | |||
313 | |||
314 | /** | ||
315 | * Send the message in @a env via a @a mqm. Must only be called at | ||
316 | * most once after the respective | ||
317 | * #GCP_MessageQueueNotificationCallback was called with `available` | ||
318 | * set to #GNUNET_YES, and not after the callback was called with | ||
319 | * `available` set to #GNUNET_NO or #GNUNET_SYSERR. | ||
320 | * | ||
321 | * @param mqm message queue manager for the transmission | ||
322 | * @param env envelope with the message to send; must NOT | ||
323 | * yet have a #GNUNET_MQ_notify_sent() callback attached to it | ||
324 | */ | ||
325 | void | ||
326 | GCP_send (struct GCP_MessageQueueManager *mqm, | ||
327 | struct GNUNET_MQ_Envelope *env); | ||
328 | |||
329 | |||
330 | /** | ||
331 | * Send the message in @a env to @a cp, overriding queueing logic. | ||
332 | * This function should only be used to send error messages outside | ||
333 | * of flow and congestion control, similar to ICMP. Note that | ||
334 | * the envelope may be silently discarded as well. | ||
335 | * | ||
336 | * @param cp peer to send the message to | ||
337 | * @param env envelope with the message to send | ||
338 | */ | ||
339 | void | ||
340 | GCP_send_ooo (struct CadetPeer *cp, | ||
341 | struct GNUNET_MQ_Envelope *env); | ||
342 | |||
343 | |||
344 | /** | ||
345 | * Stops message queue change notifications and sends a last message. | ||
346 | * In practice, this is implemented by sending that @a last_env | ||
347 | * message immediately (if any), ignoring queue order. | ||
348 | * | ||
349 | * @param mqm handle matching request to cancel | ||
350 | * @param last_env final message to transmit, or NULL | ||
351 | */ | ||
352 | void | ||
353 | GCP_request_mq_cancel (struct GCP_MessageQueueManager *mqm, | ||
354 | struct GNUNET_MQ_Envelope *last_env); | ||
355 | |||
356 | |||
357 | /** | ||
358 | * Set the message queue to @a mq for peer @a cp and notify watchers. | ||
359 | * | ||
360 | * @param cp peer to modify | ||
361 | * @param mq message queue to set (can be NULL) | ||
362 | */ | ||
363 | void | ||
364 | GCP_set_mq (struct CadetPeer *cp, | ||
365 | struct GNUNET_MQ_Handle *mq); | ||
366 | |||
367 | |||
368 | #endif | ||