diff options
Diffstat (limited to 'src/rps/gnunet-service-rps_peers.h')
-rw-r--r-- | src/rps/gnunet-service-rps_peers.h | 437 |
1 files changed, 0 insertions, 437 deletions
diff --git a/src/rps/gnunet-service-rps_peers.h b/src/rps/gnunet-service-rps_peers.h deleted file mode 100644 index 15970a7ce..000000000 --- a/src/rps/gnunet-service-rps_peers.h +++ /dev/null | |||
@@ -1,437 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 3, or (at your | ||
8 | 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 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, | ||
18 | Boston, MA 02110-1301, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file rps/gnunet-service-rps_peers.h | ||
23 | * @brief utilities for managing (information about) peers | ||
24 | * @author Julius Bünger | ||
25 | */ | ||
26 | #include "gnunet_util_lib.h" | ||
27 | #include <inttypes.h> | ||
28 | #include "gnunet_cadet_service.h" | ||
29 | |||
30 | |||
31 | /** | ||
32 | * Different flags indicating the status of another peer. | ||
33 | */ | ||
34 | enum Peers_PeerFlags | ||
35 | { | ||
36 | /** | ||
37 | * If we are waiting for a reply from that peer (sent a pull request). | ||
38 | */ | ||
39 | Peers_PULL_REPLY_PENDING = 0x01, | ||
40 | |||
41 | /* IN_OTHER_GOSSIP_LIST = 0x02, unneeded? */ | ||
42 | /* IN_OWN_SAMPLER_LIST = 0x04, unneeded? */ | ||
43 | /* IN_OWN_GOSSIP_LIST = 0x08, unneeded? */ | ||
44 | |||
45 | /** | ||
46 | * We set this bit when we know the peer is online. | ||
47 | */ | ||
48 | Peers_ONLINE = 0x20, | ||
49 | |||
50 | /** | ||
51 | * We set this bit when we are going to destroy the channel to this peer. | ||
52 | * When cleanup_channel is called, we know that we wanted to destroy it. | ||
53 | * Otherwise the channel to the other peer was destroyed. | ||
54 | */ | ||
55 | Peers_TO_DESTROY = 0x40, | ||
56 | }; | ||
57 | |||
58 | /** | ||
59 | * Keep track of the status of a channel. | ||
60 | * | ||
61 | * This is needed in order to know what to do with a channel when it's | ||
62 | * destroyed. | ||
63 | */ | ||
64 | enum Peers_ChannelFlags | ||
65 | { | ||
66 | /** | ||
67 | * We destroyed the channel because the other peer established a second one. | ||
68 | */ | ||
69 | Peers_CHANNEL_ESTABLISHED_TWICE = 0x1, | ||
70 | |||
71 | /** | ||
72 | * The channel was removed because it was not needed any more. This should be | ||
73 | * the sending channel. | ||
74 | */ | ||
75 | Peers_CHANNEL_CLEAN = 0x2, | ||
76 | }; | ||
77 | |||
78 | /** | ||
79 | * @brief The role of a channel. Sending or receiving. | ||
80 | */ | ||
81 | enum Peers_ChannelRole | ||
82 | { | ||
83 | /** | ||
84 | * Channel is used for sending | ||
85 | */ | ||
86 | Peers_CHANNEL_ROLE_SENDING = 0x01, | ||
87 | |||
88 | /** | ||
89 | * Channel is used for receiving | ||
90 | */ | ||
91 | Peers_CHANNEL_ROLE_RECEIVING = 0x02, | ||
92 | }; | ||
93 | |||
94 | /** | ||
95 | * @brief Functions of this type can be used to be stored at a peer for later execution. | ||
96 | * | ||
97 | * @param cls closure | ||
98 | * @param peer peer to execute function on | ||
99 | */ | ||
100 | typedef void (* PeerOp) (void *cls, const struct GNUNET_PeerIdentity *peer); | ||
101 | |||
102 | /** | ||
103 | * @brief Iterator over valid peers. | ||
104 | * | ||
105 | * @param cls closure | ||
106 | * @param peer current public peer id | ||
107 | * @return #GNUNET_YES if we should continue to | ||
108 | * iterate, | ||
109 | * #GNUNET_NO if not. | ||
110 | */ | ||
111 | typedef int | ||
112 | (*PeersIterator) (void *cls, | ||
113 | const struct GNUNET_PeerIdentity *peer); | ||
114 | |||
115 | /** | ||
116 | * @brief Initialise storage of peers | ||
117 | * | ||
118 | * @param fn_valid_peers filename of the file used to store valid peer ids | ||
119 | * @param cadet_h cadet handle | ||
120 | * @param disconnect_handler Disconnect handler | ||
121 | * @param c_handlers cadet handlers | ||
122 | * @param own_id own peer identity | ||
123 | */ | ||
124 | void | ||
125 | Peers_initialise (char* fn_valid_peers, | ||
126 | struct GNUNET_CADET_Handle *cadet_h, | ||
127 | GNUNET_CADET_DisconnectEventHandler disconnect_handler, | ||
128 | const struct GNUNET_MQ_MessageHandler *c_handlers, | ||
129 | const struct GNUNET_PeerIdentity *own_id); | ||
130 | |||
131 | /** | ||
132 | * @brief Delete storage of peers that was created with #Peers_initialise () | ||
133 | */ | ||
134 | void | ||
135 | Peers_terminate (); | ||
136 | |||
137 | |||
138 | /** | ||
139 | * @brief Get all currently known, valid peer ids. | ||
140 | * | ||
141 | * @param it function to call on each peer id | ||
142 | * @param it_cls extra argument to @a it | ||
143 | * @return the number of key value pairs processed, | ||
144 | * #GNUNET_SYSERR if it aborted iteration | ||
145 | */ | ||
146 | int | ||
147 | Peers_get_valid_peers (PeersIterator iterator, | ||
148 | void *it_cls); | ||
149 | |||
150 | /** | ||
151 | * @brief Add peer to known peers. | ||
152 | * | ||
153 | * This function is called on new peer_ids from 'external' sources | ||
154 | * (client seed, cadet get_peers(), ...) | ||
155 | * | ||
156 | * @param peer the new #GNUNET_PeerIdentity | ||
157 | * | ||
158 | * @return #GNUNET_YES if peer was inserted | ||
159 | * #GNUNET_NO otherwise (if peer was already known or | ||
160 | * peer was #own_identity) | ||
161 | */ | ||
162 | int | ||
163 | Peers_insert_peer (const struct GNUNET_PeerIdentity *peer); | ||
164 | |||
165 | /** | ||
166 | * @brief Try connecting to a peer to see whether it is online | ||
167 | * | ||
168 | * If not known yet, insert into known peers | ||
169 | * | ||
170 | * @param peer the peer whose liveliness is to be checked | ||
171 | * @return #GNUNET_YES if peer had to be inserted | ||
172 | * #GNUNET_NO otherwise (if peer was already known or | ||
173 | * peer was #own_identity) | ||
174 | */ | ||
175 | int | ||
176 | Peers_issue_peer_liveliness_check (const struct GNUNET_PeerIdentity *peer); | ||
177 | |||
178 | /** | ||
179 | * @brief Check if peer is removable. | ||
180 | * | ||
181 | * Check if | ||
182 | * - a recv channel exists | ||
183 | * - there are pending messages | ||
184 | * - there is no pending pull reply | ||
185 | * | ||
186 | * @param peer the peer in question | ||
187 | * @return #GNUNET_YES if peer is removable | ||
188 | * #GNUNET_NO if peer is NOT removable | ||
189 | * #GNUNET_SYSERR if peer is not known | ||
190 | */ | ||
191 | int | ||
192 | Peers_check_removable (const struct GNUNET_PeerIdentity *peer); | ||
193 | |||
194 | /** | ||
195 | * @brief Remove peer | ||
196 | * | ||
197 | * @param peer the peer to clean | ||
198 | * @return #GNUNET_YES if peer was removed | ||
199 | * #GNUNET_NO otherwise | ||
200 | */ | ||
201 | int | ||
202 | Peers_remove_peer (const struct GNUNET_PeerIdentity *peer); | ||
203 | |||
204 | /** | ||
205 | * @brief set flags on a given peer. | ||
206 | * | ||
207 | * @param peer the peer to set flags on | ||
208 | * @param flags the flags | ||
209 | */ | ||
210 | void | ||
211 | Peers_set_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags); | ||
212 | |||
213 | /** | ||
214 | * @brief unset flags on a given peer. | ||
215 | * | ||
216 | * @param peer the peer to unset flags on | ||
217 | * @param flags the flags | ||
218 | */ | ||
219 | void | ||
220 | Peers_unset_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags); | ||
221 | |||
222 | /** | ||
223 | * @brief Check whether flags on a peer are set. | ||
224 | * | ||
225 | * @param peer the peer to check the flag of | ||
226 | * @param flags the flags to check | ||
227 | * | ||
228 | * @return #GNUNET_YES if all given flags are set | ||
229 | * ##GNUNET_NO otherwise | ||
230 | */ | ||
231 | int | ||
232 | Peers_check_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags); | ||
233 | |||
234 | |||
235 | /** | ||
236 | * @brief set flags on a given channel. | ||
237 | * | ||
238 | * @param channel the channel to set flags on | ||
239 | * @param flags the flags | ||
240 | */ | ||
241 | void | ||
242 | Peers_set_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags); | ||
243 | |||
244 | /** | ||
245 | * @brief unset flags on a given channel. | ||
246 | * | ||
247 | * @param channel the channel to unset flags on | ||
248 | * @param flags the flags | ||
249 | */ | ||
250 | void | ||
251 | Peers_unset_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags); | ||
252 | |||
253 | /** | ||
254 | * @brief Check whether flags on a channel are set. | ||
255 | * | ||
256 | * @param channel the channel to check the flag of | ||
257 | * @param flags the flags to check | ||
258 | * | ||
259 | * @return #GNUNET_YES if all given flags are set | ||
260 | * #GNUNET_NO otherwise | ||
261 | */ | ||
262 | int | ||
263 | Peers_check_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags); | ||
264 | |||
265 | /** | ||
266 | * @brief Get the flags for the channel in @a role for @a peer. | ||
267 | * | ||
268 | * @param peer Peer to get the channel flags for. | ||
269 | * @param role Role of channel to get flags for | ||
270 | * | ||
271 | * @return The flags. | ||
272 | */ | ||
273 | uint32_t * | ||
274 | Peers_get_channel_flag (const struct GNUNET_PeerIdentity *peer, | ||
275 | enum Peers_ChannelRole role); | ||
276 | |||
277 | /** | ||
278 | * @brief Check whether we have information about the given peer. | ||
279 | * | ||
280 | * FIXME probably deprecated. Make this the new _online. | ||
281 | * | ||
282 | * @param peer peer in question | ||
283 | * | ||
284 | * @return #GNUNET_YES if peer is known | ||
285 | * #GNUNET_NO if peer is not knwon | ||
286 | */ | ||
287 | int | ||
288 | Peers_check_peer_known (const struct GNUNET_PeerIdentity *peer); | ||
289 | |||
290 | /** | ||
291 | * @brief Check whether @a peer is actually a peer. | ||
292 | * | ||
293 | * A valid peer is a peer that we know exists eg. we were connected to once. | ||
294 | * | ||
295 | * @param peer peer in question | ||
296 | * | ||
297 | * @return #GNUNET_YES if peer is valid | ||
298 | * #GNUNET_NO if peer is not valid | ||
299 | */ | ||
300 | int | ||
301 | Peers_check_peer_valid (const struct GNUNET_PeerIdentity *peer); | ||
302 | |||
303 | /** | ||
304 | * @brief Indicate that we want to send to the other peer | ||
305 | * | ||
306 | * This establishes a sending channel | ||
307 | * | ||
308 | * @param peer the peer to establish channel to | ||
309 | */ | ||
310 | void | ||
311 | Peers_indicate_sending_intention (const struct GNUNET_PeerIdentity *peer); | ||
312 | |||
313 | /** | ||
314 | * @brief Check whether other peer has the intention to send/opened channel | ||
315 | * towars us | ||
316 | * | ||
317 | * @param peer the peer in question | ||
318 | * | ||
319 | * @return #GNUNET_YES if peer has the intention to send | ||
320 | * #GNUNET_NO otherwise | ||
321 | */ | ||
322 | int | ||
323 | Peers_check_peer_send_intention (const struct GNUNET_PeerIdentity *peer); | ||
324 | |||
325 | /** | ||
326 | * Handle the channel a peer opens to us. | ||
327 | * | ||
328 | * @param cls The closure | ||
329 | * @param channel The channel the peer wants to establish | ||
330 | * @param initiator The peer's peer ID | ||
331 | * | ||
332 | * @return initial channel context for the channel | ||
333 | * (can be NULL -- that's not an error) | ||
334 | */ | ||
335 | void * | ||
336 | Peers_handle_inbound_channel (void *cls, | ||
337 | struct GNUNET_CADET_Channel *channel, | ||
338 | const struct GNUNET_PeerIdentity *initiator); | ||
339 | |||
340 | /** | ||
341 | * @brief Check whether a sending channel towards the given peer exists | ||
342 | * | ||
343 | * @param peer the peer to check for | ||
344 | * | ||
345 | * @return #GNUNET_YES if a sending channel towards that peer exists | ||
346 | * #GNUNET_NO otherwise | ||
347 | */ | ||
348 | int | ||
349 | Peers_check_sending_channel_exists (const struct GNUNET_PeerIdentity *peer); | ||
350 | |||
351 | /** | ||
352 | * @brief check whether the given channel is the sending channel of the given | ||
353 | * peer | ||
354 | * | ||
355 | * @param peer the peer in question | ||
356 | * @param channel the channel to check for | ||
357 | * @param role either #Peers_CHANNEL_ROLE_SENDING, or | ||
358 | * #Peers_CHANNEL_ROLE_RECEIVING | ||
359 | * | ||
360 | * @return #GNUNET_YES if the given chennel is the sending channel of the peer | ||
361 | * #GNUNET_NO otherwise | ||
362 | */ | ||
363 | int | ||
364 | Peers_check_channel_role (const struct GNUNET_PeerIdentity *peer, | ||
365 | const struct GNUNET_CADET_Channel *channel, | ||
366 | enum Peers_ChannelRole role); | ||
367 | |||
368 | /** | ||
369 | * @brief Destroy the send channel of a peer e.g. stop indicating a sending | ||
370 | * intention to another peer | ||
371 | * | ||
372 | * If there is also no channel to receive messages from that peer, remove it | ||
373 | * from the peermap. | ||
374 | * | ||
375 | * @peer the peer identity of the peer whose sending channel to destroy | ||
376 | * @return #GNUNET_YES if channel was destroyed | ||
377 | * #GNUNET_NO otherwise | ||
378 | */ | ||
379 | int | ||
380 | Peers_destroy_sending_channel (const struct GNUNET_PeerIdentity *peer); | ||
381 | |||
382 | /** | ||
383 | * This is called when a channel is destroyed. | ||
384 | * | ||
385 | * Removes peer completely from our knowledge if the send_channel was destroyed | ||
386 | * Otherwise simply delete the recv_channel | ||
387 | * | ||
388 | * @param cls The closure | ||
389 | * @param channel The channel being closed | ||
390 | * @param channel_ctx The context associated with this channel | ||
391 | */ | ||
392 | void | ||
393 | Peers_cleanup_destroyed_channel (void *cls, | ||
394 | const struct GNUNET_CADET_Channel *channel); | ||
395 | |||
396 | /** | ||
397 | * @brief Send a message to another peer. | ||
398 | * | ||
399 | * Keeps track about pending messages so they can be properly removed when the | ||
400 | * peer is destroyed. | ||
401 | * | ||
402 | * @param peer receeiver of the message | ||
403 | * @param ev envelope of the message | ||
404 | * @param type type of the message | ||
405 | */ | ||
406 | void | ||
407 | Peers_send_message (const struct GNUNET_PeerIdentity *peer, | ||
408 | struct GNUNET_MQ_Envelope *ev, | ||
409 | const char *type); | ||
410 | |||
411 | /** | ||
412 | * @brief Schedule a operation on given peer | ||
413 | * | ||
414 | * Avoids scheduling an operation twice. | ||
415 | * | ||
416 | * @param peer the peer we want to schedule the operation for once it gets live | ||
417 | * | ||
418 | * @return #GNUNET_YES if the operation was scheduled | ||
419 | * #GNUNET_NO otherwise | ||
420 | */ | ||
421 | int | ||
422 | Peers_schedule_operation (const struct GNUNET_PeerIdentity *peer, | ||
423 | const PeerOp peer_op); | ||
424 | |||
425 | /** | ||
426 | * @brief Get the recv_channel of @a peer. | ||
427 | * Needed to correctly handle (call #GNUNET_CADET_receive_done()) incoming | ||
428 | * messages. | ||
429 | * | ||
430 | * @param peer The peer to get the recv_channel from. | ||
431 | * | ||
432 | * @return The recv_channel. | ||
433 | */ | ||
434 | struct GNUNET_CADET_Channel * | ||
435 | Peers_get_recv_channel (const struct GNUNET_PeerIdentity *peer); | ||
436 | |||
437 | /* end of gnunet-service-rps_peers.h */ | ||