aboutsummaryrefslogtreecommitdiff
path: root/src/rps/gnunet-service-rps_peers.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/rps/gnunet-service-rps_peers.h')
-rw-r--r--src/rps/gnunet-service-rps_peers.h437
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 */
34enum 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 */
64enum 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 */
81enum 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 */
100typedef 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 */
111typedef 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 */
124void
125Peers_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 */
134void
135Peers_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 */
146int
147Peers_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 */
162int
163Peers_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 */
175int
176Peers_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 */
191int
192Peers_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 */
201int
202Peers_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 */
210void
211Peers_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 */
219void
220Peers_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 */
231int
232Peers_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 */
241void
242Peers_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 */
250void
251Peers_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 */
262int
263Peers_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 */
273uint32_t *
274Peers_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 */
287int
288Peers_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 */
300int
301Peers_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 */
310void
311Peers_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 */
322int
323Peers_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 */
335void *
336Peers_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 */
348int
349Peers_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 */
363int
364Peers_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 */
379int
380Peers_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 */
392void
393Peers_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 */
406void
407Peers_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 */
421int
422Peers_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 */
434struct GNUNET_CADET_Channel *
435Peers_get_recv_channel (const struct GNUNET_PeerIdentity *peer);
436
437/* end of gnunet-service-rps_peers.h */