2 This file is part of GNUnet.
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.
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.
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.
22 * @file rps/gnunet-service-rps_peers.h
23 * @brief utilities for managing (information about) peers
24 * @author Julius Bünger
26 #include "gnunet_util_lib.h"
28 #include "gnunet_cadet_service.h"
32 * Different flags indicating the status of another peer.
37 * If we are waiting for a reply from that peer (sent a pull request).
39 Peers_PULL_REPLY_PENDING = 0x01,
41 /* IN_OTHER_GOSSIP_LIST = 0x02, unneeded? */
42 /* IN_OWN_SAMPLER_LIST = 0x04, unneeded? */
43 /* IN_OWN_GOSSIP_LIST = 0x08, unneeded? */
46 * We set this bit when we know the peer is online.
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.
55 Peers_TO_DESTROY = 0x40,
59 * Keep track of the status of a channel.
61 * This is needed in order to know what to do with a channel when it's
64 enum Peers_ChannelFlags
67 * We destroyed the channel because the other peer established a second one.
69 Peers_CHANNEL_ESTABLISHED_TWICE = 0x1,
72 * The channel was removed because it was not needed any more. This should be
73 * the sending channel.
75 Peers_CHANNEL_CLEAN = 0x2,
79 * @brief The role of a channel. Sending or receiving.
81 enum Peers_ChannelRole
84 * Channel is used for sending
86 Peers_CHANNEL_ROLE_SENDING = 0x01,
89 * Channel is used for receiving
91 Peers_CHANNEL_ROLE_RECEIVING = 0x02,
95 * @brief Functions of this type can be used to be stored at a peer for later execution.
98 * @param peer peer to execute function on
100 typedef void (* PeerOp) (void *cls, const struct GNUNET_PeerIdentity *peer);
103 * @brief Iterator over valid peers.
106 * @param peer current public peer id
107 * @return #GNUNET_YES if we should continue to
112 (*PeersIterator) (void *cls,
113 const struct GNUNET_PeerIdentity *peer);
116 * @brief Initialise storage of peers
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
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);
132 * @brief Delete storage of peers that was created with #Peers_initialise ()
139 * @brief Get all currently known, valid peer ids.
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
147 Peers_get_valid_peers (PeersIterator iterator,
151 * @brief Add peer to known peers.
153 * This function is called on new peer_ids from 'external' sources
154 * (client seed, cadet get_peers(), ...)
156 * @param peer the new #GNUNET_PeerIdentity
158 * @return #GNUNET_YES if peer was inserted
159 * #GNUNET_NO otherwise (if peer was already known or
160 * peer was #own_identity)
163 Peers_insert_peer (const struct GNUNET_PeerIdentity *peer);
166 * @brief Try connecting to a peer to see whether it is online
168 * If not known yet, insert into known peers
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)
176 Peers_issue_peer_liveliness_check (const struct GNUNET_PeerIdentity *peer);
179 * @brief Check if peer is removable.
182 * - a recv channel exists
183 * - there are pending messages
184 * - there is no pending pull reply
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
192 Peers_check_removable (const struct GNUNET_PeerIdentity *peer);
197 * @param peer the peer to clean
198 * @return #GNUNET_YES if peer was removed
199 * #GNUNET_NO otherwise
202 Peers_remove_peer (const struct GNUNET_PeerIdentity *peer);
205 * @brief set flags on a given peer.
207 * @param peer the peer to set flags on
208 * @param flags the flags
211 Peers_set_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
214 * @brief unset flags on a given peer.
216 * @param peer the peer to unset flags on
217 * @param flags the flags
220 Peers_unset_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
223 * @brief Check whether flags on a peer are set.
225 * @param peer the peer to check the flag of
226 * @param flags the flags to check
228 * @return #GNUNET_YES if all given flags are set
229 * ##GNUNET_NO otherwise
232 Peers_check_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
236 * @brief set flags on a given channel.
238 * @param channel the channel to set flags on
239 * @param flags the flags
242 Peers_set_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
245 * @brief unset flags on a given channel.
247 * @param channel the channel to unset flags on
248 * @param flags the flags
251 Peers_unset_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
254 * @brief Check whether flags on a channel are set.
256 * @param channel the channel to check the flag of
257 * @param flags the flags to check
259 * @return #GNUNET_YES if all given flags are set
260 * #GNUNET_NO otherwise
263 Peers_check_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
266 * @brief Get the flags for the channel in @a role for @a peer.
268 * @param peer Peer to get the channel flags for.
269 * @param role Role of channel to get flags for
274 Peers_get_channel_flag (const struct GNUNET_PeerIdentity *peer,
275 enum Peers_ChannelRole role);
278 * @brief Check whether we have information about the given peer.
280 * FIXME probably deprecated. Make this the new _online.
282 * @param peer peer in question
284 * @return #GNUNET_YES if peer is known
285 * #GNUNET_NO if peer is not knwon
288 Peers_check_peer_known (const struct GNUNET_PeerIdentity *peer);
291 * @brief Check whether @a peer is actually a peer.
293 * A valid peer is a peer that we know exists eg. we were connected to once.
295 * @param peer peer in question
297 * @return #GNUNET_YES if peer is valid
298 * #GNUNET_NO if peer is not valid
301 Peers_check_peer_valid (const struct GNUNET_PeerIdentity *peer);
304 * @brief Indicate that we want to send to the other peer
306 * This establishes a sending channel
308 * @param peer the peer to establish channel to
311 Peers_indicate_sending_intention (const struct GNUNET_PeerIdentity *peer);
314 * @brief Check whether other peer has the intention to send/opened channel
317 * @param peer the peer in question
319 * @return #GNUNET_YES if peer has the intention to send
320 * #GNUNET_NO otherwise
323 Peers_check_peer_send_intention (const struct GNUNET_PeerIdentity *peer);
326 * Handle the channel a peer opens to us.
328 * @param cls The closure
329 * @param channel The channel the peer wants to establish
330 * @param initiator The peer's peer ID
332 * @return initial channel context for the channel
333 * (can be NULL -- that's not an error)
336 Peers_handle_inbound_channel (void *cls,
337 struct GNUNET_CADET_Channel *channel,
338 const struct GNUNET_PeerIdentity *initiator);
341 * @brief Check whether a sending channel towards the given peer exists
343 * @param peer the peer to check for
345 * @return #GNUNET_YES if a sending channel towards that peer exists
346 * #GNUNET_NO otherwise
349 Peers_check_sending_channel_exists (const struct GNUNET_PeerIdentity *peer);
352 * @brief check whether the given channel is the sending channel of the given
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
360 * @return #GNUNET_YES if the given chennel is the sending channel of the peer
361 * #GNUNET_NO otherwise
364 Peers_check_channel_role (const struct GNUNET_PeerIdentity *peer,
365 const struct GNUNET_CADET_Channel *channel,
366 enum Peers_ChannelRole role);
369 * @brief Destroy the send channel of a peer e.g. stop indicating a sending
370 * intention to another peer
372 * If there is also no channel to receive messages from that peer, remove it
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
380 Peers_destroy_sending_channel (const struct GNUNET_PeerIdentity *peer);
383 * This is called when a channel is destroyed.
385 * Removes peer completely from our knowledge if the send_channel was destroyed
386 * Otherwise simply delete the recv_channel
388 * @param cls The closure
389 * @param channel The channel being closed
390 * @param channel_ctx The context associated with this channel
393 Peers_cleanup_destroyed_channel (void *cls,
394 const struct GNUNET_CADET_Channel *channel);
397 * @brief Send a message to another peer.
399 * Keeps track about pending messages so they can be properly removed when the
402 * @param peer receeiver of the message
403 * @param ev envelope of the message
404 * @param type type of the message
407 Peers_send_message (const struct GNUNET_PeerIdentity *peer,
408 struct GNUNET_MQ_Envelope *ev,
412 * @brief Schedule a operation on given peer
414 * Avoids scheduling an operation twice.
416 * @param peer the peer we want to schedule the operation for once it gets live
418 * @return #GNUNET_YES if the operation was scheduled
419 * #GNUNET_NO otherwise
422 Peers_schedule_operation (const struct GNUNET_PeerIdentity *peer,
423 const PeerOp peer_op);
426 * @brief Get the recv_channel of @a peer.
427 * Needed to correctly handle (call #GNUNET_CADET_receive_done()) incoming
430 * @param peer The peer to get the recv_channel from.
432 * @return The recv_channel.
434 struct GNUNET_CADET_Channel *
435 Peers_get_recv_channel (const struct GNUNET_PeerIdentity *peer);
437 /* end of gnunet-service-rps_peers.h */