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 can be sure the other peer is/was live.
  47    */
  48   Peers_VALID                = 0x10,
  49
  50   /**
  51    * We set this bit when we know the peer is online.
  52    */
  53   Peers_ONLINE               = 0x20,
  54
  55   /**
  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.
  59    */
  60   Peers_TO_DESTROY           = 0x40,
  61 };
  62
  63 /**
  64  * Keep track of the status of a channel.
  65  *
  66  * This is needed in order to know what to do with a channel when it's
  67  * destroyed.
  68  */
  69 enum Peers_ChannelFlags
  70 {
  71   /**
  72    * We destroyed the channel because the other peer established a second one.
  73    */
  74   Peers_CHANNEL_ESTABLISHED_TWICE = 0x1,
  75
  76   /**
  77    * The channel was removed because it was not needed any more. This should be
  78    * the sending channel.
  79    */
  80   Peers_CHANNEL_CLEAN = 0x2,
  81 };
  82
  83 /**
  84  * @brief The role of a channel. Sending or receiving.
  85  */
  86 enum Peers_ChannelRole
  87 {
  88   /**
  89    * Channel is used for sending
  90    */
  91   Peers_CHANNEL_ROLE_SENDING   = 0x01,
  92
  93   /**
  94    * Channel is used for receiving
  95    */
  96   Peers_CHANNEL_ROLE_RECEIVING = 0x02,
  97 };
  98
  99 /**
 100  * @brief Functions of this type can be used to be stored at a peer for later execution.
 101  *
 102  * @param cls closure
 103  * @param peer peer to execute function on
 104  */
 105 typedef void (* PeerOp) (void *cls, const struct GNUNET_PeerIdentity *peer);
 106
 107 /**
 108  * @brief Initialise storage of peers
 109  *
 110  * @param cadet_h cadet handle
 111  * @param own_id own peer identity
 112  */
 113 void
 114 Peers_initialise (struct GNUNET_CADET_Handle *cadet_h,
 115                   const struct GNUNET_PeerIdentity *own_id);
 116
 117 /**
 118  * @brief Delete storage of peers that was created with #Peers_initialise ()
 119  */
 120 void
 121 Peers_terminate ();
 122
 123 /**
 124  * @brief Add peer to known peers.
 125  *
 126  * This function is called on new peer_ids from 'external' sources
 127  * (client seed, cadet get_peers(), ...)
 128  *
 129  * @param peer the new #GNUNET_PeerIdentity
 130  *
 131  * @return #GNUNET_YES if peer was inserted
 132  *         #GNUNET_NO  if peer was already known
 133  */
 134 int
 135 Peers_insert_peer (const struct GNUNET_PeerIdentity *peer);
 136
 137 /**
 138  * @brief Add peer to known peers and check for liveliness.
 139  *
 140  * This function is called on new peer_ids from 'external' sources
 141  * (client seed, cadet get_peers(), ...)
 142  *
 143  * @param peer the new #GNUNET_PeerIdentity
 144  *
 145  * @return #GNUNET_YES if peer was inserted
 146  *         #GNUNET_NO  if peer was already known
 147  */
 148 int
 149 Peers_insert_peer_check_liveliness (const struct GNUNET_PeerIdentity *peer);
 150
 151 /**
 152  * @brief Remove unecessary data
 153  *
 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).
 157  *
 158  * @param peer the peer to clean
 159  * @return #GNUNET_YES if peer was removed
 160  *         #GNUNET_NO  otherwise
 161  */
 162 int
 163 Peers_clean_peer (const struct GNUNET_PeerIdentity *peer);
 164
 165 /**
 166  * @brief Remove peer
 167  *
 168  * @param peer the peer to clean
 169  * @return #GNUNET_YES if peer was removed
 170  *         #GNUNET_NO  otherwise
 171  */
 172 int
 173 Peers_remove_peer (const struct GNUNET_PeerIdentity *peer);
 174
 175 /**
 176  * @brief set flags on a given peer.
 177  *
 178  * @param peer the peer to set flags on
 179  * @param flags the flags
 180  */
 181 void
 182 Peers_set_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
 183
 184 /**
 185  * @brief unset flags on a given peer.
 186  *
 187  * @param peer the peer to unset flags on
 188  * @param flags the flags
 189  */
 190 void
 191 Peers_unset_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
 192
 193 /**
 194  * @brief Check whether flags on a peer are set.
 195  *
 196  * @param peer the peer to check the flag of
 197  * @param flags the flags to check
 198  *
 199  * @return #GNUNET_YES if all given flags are set
 200  *         ##GNUNET_NO  otherwise
 201  */
 202 int
 203 Peers_check_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
 204
 205
 206 /**
 207  * @brief set flags on a given channel.
 208  *
 209  * @param channel the channel to set flags on
 210  * @param flags the flags
 211  */
 212 void
 213 Peers_set_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
 214
 215 /**
 216  * @brief unset flags on a given channel.
 217  *
 218  * @param channel the channel to unset flags on
 219  * @param flags the flags
 220  */
 221 void
 222 Peers_unset_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
 223
 224 /**
 225  * @brief Check whether flags on a channel are set.
 226  *
 227  * @param channel the channel to check the flag of
 228  * @param flags the flags to check
 229  *
 230  * @return #GNUNET_YES if all given flags are set
 231  *         #GNUNET_NO  otherwise
 232  */
 233 int
 234 Peers_check_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
 235
 236 /**
 237  * @brief Check whether we have information about the given peer.
 238  *
 239  * @param peer peer in question
 240  *
 241  * @return #GNUNET_YES if peer is known
 242  *         #GNUNET_NO  if peer is not knwon
 243  */
 244 int
 245 Peers_check_peer_known (const struct GNUNET_PeerIdentity *peer);
 246
 247 /**
 248  * @brief Indicate that we want to send to the other peer
 249  *
 250  * This establishes a sending channel
 251  *
 252  * @param peer the peer to establish channel to
 253  */
 254 void
 255 Peers_indicate_sending_intention (const struct GNUNET_PeerIdentity *peer);
 256
 257 /**
 258  * @brief Check whether other peer has the intention to send/opened channel
 259  *        towars us
 260  *
 261  * @param peer the peer in question
 262  *
 263  * @return #GNUNET_YES if peer has the intention to send
 264  *         #GNUNET_NO  otherwise
 265  */
 266 int
 267 Peers_check_peer_send_intention (const struct GNUNET_PeerIdentity *peer);
 268
 269 /**
 270  * Handle the channel a peer opens to us.
 271  *
 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
 277  *
 278  * @return initial channel context for the channel
 279  *         (can be NULL -- that's not an error)
 280  */
 281 void *
 282 Peers_handle_inbound_channel (void *cls,
 283                               struct GNUNET_CADET_Channel *channel,
 284                               const struct GNUNET_PeerIdentity *initiator,
 285                               uint32_t port,
 286                               enum GNUNET_CADET_ChannelOption options);
 287
 288 /**
 289  * @brief Check whether a sending channel towards the given peer exists
 290  *
 291  * @param peer the peer to check for
 292  *
 293  * @return #GNUNET_YES if a sending channel towards that peer exists
 294  *         #GNUNET_NO  otherwise
 295  */
 296 int
 297 Peers_check_sending_channel_exists (const struct GNUNET_PeerIdentity *peer);
 298
 299 /**
 300  * @brief check whether the given channel is the sending channel of the given
 301  *        peer
 302  *
 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
 307  *
 308  * @return #GNUNET_YES if the given chennel is the sending channel of the peer
 309  *         #GNUNET_NO  otherwise
 310  */
 311 int
 312 Peers_check_channel_role (const struct GNUNET_PeerIdentity *peer,
 313                           const struct GNUNET_CADET_Channel *channel,
 314                           enum Peers_ChannelRole role);
 315
 316 /**
 317  * @brief Destroy the send channel of a peer e.g. stop indicating a sending
 318  *        intention to another peer
 319  *
 320  * If there is also no channel to receive messages from that peer, remove it
 321  * from the peermap.
 322  *
 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
 326  */
 327 int
 328 Peers_destroy_sending_channel (const struct GNUNET_PeerIdentity *peer);
 329
 330 /**
 331  * This is called when a channel is destroyed.
 332  *
 333  * Removes peer completely from our knowledge if the send_channel was destroyed
 334  * Otherwise simply delete the recv_channel
 335  *
 336  * @param cls The closure
 337  * @param channel The channel being closed
 338  * @param channel_ctx The context associated with this channel
 339  */
 340 void
 341 Peers_cleanup_destroyed_channel (void *cls,
 342                                  const struct GNUNET_CADET_Channel *channel,
 343                                  void *channel_ctx);
 344
 345 /**
 346  * @brief Issue a check whether peer is live
 347  *
 348  * This tries to establish a channel to the given peer. Once the channel is
 349  * established successfully, we know the peer is live.
 350  *
 351  * @param peer the peer to check liveliness
 352  */
 353 void
 354 Peers_issue_peer_liveliness_check (const struct GNUNET_PeerIdentity *peer);
 355
 356 /**
 357  * @brief Send a message to another peer.
 358  *
 359  * Keeps track about pending messages so they can be properly removed when the
 360  * peer is destroyed.
 361  *
 362  * @param peer receeiver of the message
 363  * @param ev envelope of the message
 364  * @param type type of the message
 365  */
 366 void
 367 Peers_send_message (const struct GNUNET_PeerIdentity *peer,
 368                     struct GNUNET_MQ_Envelope *ev,
 369                     const char *type);
 370
 371 /**
 372  * @brief Schedule a operation on given peer
 373  *
 374  * Avoids scheduling an operation twice.
 375  *
 376  * @param peer the peer we want to schedule the operation for once it gets live
 377  *
 378  * @return #GNUNET_YES if the operation was scheduled
 379  *         #GNUNET_NO  otherwise
 380  */
 381 int
 382 Peers_schedule_operation (const struct GNUNET_PeerIdentity *peer,
 383                           const PeerOp peer_op);
 384
 385 /* end of gnunet-service-rps_peers.h */