src/rps/gnunet-service-rps_peers.h

   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 */