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 can be sure the other peer is/was live.
51 * We set this bit when we know the peer is online.
56 * We set this bit when we are going to destroy the channel to this peer.
57 * When cleanup_channel is called, we know that we wanted to destroy it.
58 * Otherwise the channel to the other peer was destroyed.
60 Peers_TO_DESTROY = 0x40,
64 * Keep track of the status of a channel.
66 * This is needed in order to know what to do with a channel when it's
69 enum Peers_ChannelFlags
72 * We destroyed the channel because the other peer established a second one.
74 Peers_CHANNEL_ESTABLISHED_TWICE = 0x1,
77 * The channel was removed because it was not needed any more. This should be
78 * the sending channel.
80 Peers_CHANNEL_CLEAN = 0x2,
84 * @brief The role of a channel. Sending or receiving.
86 enum Peers_ChannelRole
89 * Channel is used for sending
91 Peers_CHANNEL_ROLE_SENDING = 0x01,
94 * Channel is used for receiving
96 Peers_CHANNEL_ROLE_RECEIVING = 0x02,
100 * @brief Functions of this type can be used to be stored at a peer for later execution.
103 * @param peer peer to execute function on
105 typedef void (* PeerOp) (void *cls, const struct GNUNET_PeerIdentity *peer);
108 * @brief Initialise storage of peers
110 * @param cadet_h cadet handle
111 * @param own_id own peer identity
114 Peers_initialise (struct GNUNET_CADET_Handle *cadet_h,
115 const struct GNUNET_PeerIdentity *own_id);
118 * @brief Delete storage of peers that was created with #Peers_initialise ()
124 * @brief Add peer to known peers.
126 * This function is called on new peer_ids from 'external' sources
127 * (client seed, cadet get_peers(), ...)
129 * @param peer the new #GNUNET_PeerIdentity
131 * @return #GNUNET_YES if peer was inserted
132 * #GNUNET_NO if peer was already known
135 Peers_insert_peer (const struct GNUNET_PeerIdentity *peer);
138 * @brief Add peer to known peers and check for liveliness.
140 * This function is called on new peer_ids from 'external' sources
141 * (client seed, cadet get_peers(), ...)
143 * @param peer the new #GNUNET_PeerIdentity
145 * @return #GNUNET_YES if peer was inserted
146 * #GNUNET_NO if peer was already known
149 Peers_insert_peer_check_liveliness (const struct GNUNET_PeerIdentity *peer);
152 * @brief Remove unecessary data
154 * If the other peer is not intending to send messages, we have messages pending
155 * to be sent to this peer and we are not waiting for a reply, remove the
156 * information about it (its #PeerContext).
158 * @param peer the peer to clean
159 * @return #GNUNET_YES if peer was removed
160 * #GNUNET_NO otherwise
163 Peers_clean_peer (const struct GNUNET_PeerIdentity *peer);
168 * @param peer the peer to clean
169 * @return #GNUNET_YES if peer was removed
170 * #GNUNET_NO otherwise
173 Peers_remove_peer (const struct GNUNET_PeerIdentity *peer);
176 * @brief set flags on a given peer.
178 * @param peer the peer to set flags on
179 * @param flags the flags
182 Peers_set_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
185 * @brief unset flags on a given peer.
187 * @param peer the peer to unset flags on
188 * @param flags the flags
191 Peers_unset_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
194 * @brief Check whether flags on a peer are set.
196 * @param peer the peer to check the flag of
197 * @param flags the flags to check
199 * @return #GNUNET_YES if all given flags are set
200 * ##GNUNET_NO otherwise
203 Peers_check_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
207 * @brief set flags on a given channel.
209 * @param channel the channel to set flags on
210 * @param flags the flags
213 Peers_set_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
216 * @brief unset flags on a given channel.
218 * @param channel the channel to unset flags on
219 * @param flags the flags
222 Peers_unset_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
225 * @brief Check whether flags on a channel are set.
227 * @param channel the channel to check the flag of
228 * @param flags the flags to check
230 * @return #GNUNET_YES if all given flags are set
231 * #GNUNET_NO otherwise
234 Peers_check_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
237 * @brief Check whether we have information about the given peer.
239 * @param peer peer in question
241 * @return #GNUNET_YES if peer is known
242 * #GNUNET_NO if peer is not knwon
245 Peers_check_peer_known (const struct GNUNET_PeerIdentity *peer);
248 * @brief Indicate that we want to send to the other peer
250 * This establishes a sending channel
252 * @param peer the peer to establish channel to
255 Peers_indicate_sending_intention (const struct GNUNET_PeerIdentity *peer);
258 * @brief Check whether other peer has the intention to send/opened channel
261 * @param peer the peer in question
263 * @return #GNUNET_YES if peer has the intention to send
264 * #GNUNET_NO otherwise
267 Peers_check_peer_send_intention (const struct GNUNET_PeerIdentity *peer);
270 * Handle the channel a peer opens to us.
272 * @param cls The closure
273 * @param channel The channel the peer wants to establish
274 * @param initiator The peer's peer ID
275 * @param port The port the channel is being established over
276 * @param options Further options
278 * @return initial channel context for the channel
279 * (can be NULL -- that's not an error)
282 Peers_handle_inbound_channel (void *cls,
283 struct GNUNET_CADET_Channel *channel,
284 const struct GNUNET_PeerIdentity *initiator,
286 enum GNUNET_CADET_ChannelOption options);
289 * @brief Check whether a sending channel towards the given peer exists
291 * @param peer the peer to check for
293 * @return #GNUNET_YES if a sending channel towards that peer exists
294 * #GNUNET_NO otherwise
297 Peers_check_sending_channel_exists (const struct GNUNET_PeerIdentity *peer);
300 * @brief check whether the given channel is the sending channel of the given
303 * @param peer the peer in question
304 * @param channel the channel to check for
305 * @param role either #Peers_CHANNEL_ROLE_SENDING, or
306 * #Peers_CHANNEL_ROLE_RECEIVING
308 * @return #GNUNET_YES if the given chennel is the sending channel of the peer
309 * #GNUNET_NO otherwise
312 Peers_check_channel_role (const struct GNUNET_PeerIdentity *peer,
313 const struct GNUNET_CADET_Channel *channel,
314 enum Peers_ChannelRole role);
317 * @brief Destroy the send channel of a peer e.g. stop indicating a sending
318 * intention to another peer
320 * If there is also no channel to receive messages from that peer, remove it
323 * @peer the peer identity of the peer whose sending channel to destroy
324 * @return #GNUNET_YES if channel was destroyed
325 * #GNUNET_NO otherwise
328 Peers_destroy_sending_channel (const struct GNUNET_PeerIdentity *peer);
331 * This is called when a channel is destroyed.
333 * Removes peer completely from our knowledge if the send_channel was destroyed
334 * Otherwise simply delete the recv_channel
336 * @param cls The closure
337 * @param channel The channel being closed
338 * @param channel_ctx The context associated with this channel
341 Peers_cleanup_destroyed_channel (void *cls,
342 const struct GNUNET_CADET_Channel *channel,
346 * @brief Issue a check whether peer is live
348 * This tries to establish a channel to the given peer. Once the channel is
349 * established successfully, we know the peer is live.
351 * @param peer the peer to check liveliness
354 Peers_issue_peer_liveliness_check (const struct GNUNET_PeerIdentity *peer);
357 * @brief Send a message to another peer.
359 * Keeps track about pending messages so they can be properly removed when the
362 * @param peer receeiver of the message
363 * @param ev envelope of the message
364 * @param type type of the message
367 Peers_send_message (const struct GNUNET_PeerIdentity *peer,
368 struct GNUNET_MQ_Envelope *ev,
372 * @brief Schedule a operation on given peer
374 * Avoids scheduling an operation twice.
376 * @param peer the peer we want to schedule the operation for once it gets live
378 * @return #GNUNET_YES if the operation was scheduled
379 * #GNUNET_NO otherwise
382 Peers_schedule_operation (const struct GNUNET_PeerIdentity *peer,
383 const PeerOp peer_op);
385 /* end of gnunet-service-rps_peers.h */