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 Remove unecessary data
 139  *
 140  * If the other peer is not intending to send messages, we have messages pending
 141  * to be sent to this peer and we are not waiting for a reply, remove the
 142  * information about it (its #PeerContext).
 143  *
 144  * @param peer the peer to clean
 145  * @return #GNUNET_YES if peer was removed
 146  *         #GNUNET_NO  otherwise
 147  */
 148 int
 149 Peers_clean_peer (const struct GNUNET_PeerIdentity *peer);
 150
 151 /**
 152  * @brief Remove peer
 153  *
 154  * @param peer the peer to clean
 155  * @return #GNUNET_YES if peer was removed
 156  *         #GNUNET_NO  otherwise
 157  */
 158 int
 159 Peers_remove_peer (const struct GNUNET_PeerIdentity *peer);
 160
 161 /**
 162  * @brief set flags on a given peer.
 163  *
 164  * @param peer the peer to set flags on
 165  * @param flags the flags
 166  */
 167 void
 168 Peers_set_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
 169
 170 /**
 171  * @brief unset flags on a given peer.
 172  *
 173  * @param peer the peer to unset flags on
 174  * @param flags the flags
 175  */
 176 void
 177 Peers_unset_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
 178
 179 /**
 180  * @brief Check whether flags on a peer are set.
 181  *
 182  * @param peer the peer to check the flag of
 183  * @param flags the flags to check
 184  *
 185  * @return #GNUNET_YES if all given flags are set
 186  *         ##GNUNET_NO  otherwise
 187  */
 188 int
 189 Peers_check_peer_flag (const struct GNUNET_PeerIdentity *peer, enum Peers_PeerFlags flags);
 190
 191
 192 /**
 193  * @brief set flags on a given channel.
 194  *
 195  * @param channel the channel to set flags on
 196  * @param flags the flags
 197  */
 198 void
 199 Peers_set_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
 200
 201 /**
 202  * @brief unset flags on a given channel.
 203  *
 204  * @param channel the channel to unset flags on
 205  * @param flags the flags
 206  */
 207 void
 208 Peers_unset_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
 209
 210 /**
 211  * @brief Check whether flags on a channel are set.
 212  *
 213  * @param channel the channel to check the flag of
 214  * @param flags the flags to check
 215  *
 216  * @return #GNUNET_YES if all given flags are set
 217  *         #GNUNET_NO  otherwise
 218  */
 219 int
 220 Peers_check_channel_flag (uint32_t *channel_flags, enum Peers_ChannelFlags flags);
 221
 222 /**
 223  * @brief Check whether we have information about the given peer.
 224  *
 225  * @param peer peer in question
 226  *
 227  * @return #GNUNET_YES if peer is known
 228  *         #GNUNET_NO  if peer is not knwon
 229  */
 230 int
 231 Peers_check_peer_known (const struct GNUNET_PeerIdentity *peer);
 232
 233 /**
 234  * @brief Indicate that we want to send to the other peer
 235  *
 236  * This establishes a sending channel
 237  *
 238  * @param peer the peer to establish channel to
 239  */
 240 void
 241 Peers_indicate_sending_intention (const struct GNUNET_PeerIdentity *peer);
 242
 243 /**
 244  * @brief Check whether other peer has the intention to send/opened channel
 245  *        towars us
 246  *
 247  * @param peer the peer in question
 248  *
 249  * @return #GNUNET_YES if peer has the intention to send
 250  *         #GNUNET_NO  otherwise
 251  */
 252 int
 253 Peers_check_peer_send_intention (const struct GNUNET_PeerIdentity *peer);
 254
 255 /**
 256  * Handle the channel a peer opens to us.
 257  *
 258  * @param cls The closure
 259  * @param channel The channel the peer wants to establish
 260  * @param initiator The peer's peer ID
 261  * @param port The port the channel is being established over
 262  * @param options Further options
 263  *
 264  * @return initial channel context for the channel
 265  *         (can be NULL -- that's not an error)
 266  */
 267 void *
 268 Peers_handle_inbound_channel (void *cls,
 269                               struct GNUNET_CADET_Channel *channel,
 270                               const struct GNUNET_PeerIdentity *initiator,
 271                               uint32_t port,
 272                               enum GNUNET_CADET_ChannelOption options);
 273
 274 /**
 275  * @brief Check whether a sending channel towards the given peer exists
 276  *
 277  * @param peer the peer to check for
 278  *
 279  * @return #GNUNET_YES if a sending channel towards that peer exists
 280  *         #GNUNET_NO  otherwise
 281  */
 282 int
 283 Peers_check_sending_channel_exists (const struct GNUNET_PeerIdentity *peer);
 284
 285 /**
 286  * @brief check whether the given channel is the sending channel of the given
 287  *        peer
 288  *
 289  * @param peer the peer in question
 290  * @param channel the channel to check for
 291  * @param role either #Peers_CHANNEL_ROLE_SENDING, or
 292  *                    #Peers_CHANNEL_ROLE_RECEIVING
 293  *
 294  * @return #GNUNET_YES if the given chennel is the sending channel of the peer
 295  *         #GNUNET_NO  otherwise
 296  */
 297 int
 298 Peers_check_channel_role (const struct GNUNET_PeerIdentity *peer,
 299                           const struct GNUNET_CADET_Channel *channel,
 300                           enum Peers_ChannelRole role);
 301
 302 /**
 303  * @brief Destroy the send channel of a peer e.g. stop indicating a sending
 304  *        intention to another peer
 305  *
 306  * If there is also no channel to receive messages from that peer, remove it
 307  * from the peermap.
 308  *
 309  * @peer the peer identity of the peer whose sending channel to destroy
 310  * @return #GNUNET_YES if channel was destroyed
 311  *         #GNUNET_NO  otherwise
 312  */
 313 int
 314 Peers_destroy_sending_channel (const struct GNUNET_PeerIdentity *peer);
 315
 316 /**
 317  * This is called when a channel is destroyed.
 318  *
 319  * Removes peer completely from our knowledge if the send_channel was destroyed
 320  * Otherwise simply delete the recv_channel
 321  *
 322  * @param cls The closure
 323  * @param channel The channel being closed
 324  * @param channel_ctx The context associated with this channel
 325  */
 326 void
 327 Peers_cleanup_destroyed_channel (void *cls,
 328                                  const struct GNUNET_CADET_Channel *channel,
 329                                  void *channel_ctx);
 330
 331 /**
 332  * @brief Issue a check whether peer is live
 333  *
 334  * This tries to establish a channel to the given peer. Once the channel is
 335  * established successfully, we know the peer is live.
 336  *
 337  * @param peer the peer to check liveliness
 338  */
 339 void
 340 Peers_issue_peer_liveliness_check (const struct GNUNET_PeerIdentity *peer);
 341
 342 /**
 343  * @brief Send a message to another peer.
 344  *
 345  * Keeps track about pending messages so they can be properly removed when the
 346  * peer is destroyed.
 347  *
 348  * @param peer receeiver of the message
 349  * @param ev envelope of the message
 350  * @param type type of the message
 351  */
 352 void
 353 Peers_send_message (const struct GNUNET_PeerIdentity *peer,
 354                     struct GNUNET_MQ_Envelope *ev,
 355                     const char *type);
 356
 357 /**
 358  * @brief Schedule a operation on given peer
 359  *
 360  * Avoids scheduling an operation twice.
 361  *
 362  * @param peer the peer we want to schedule the operation for once it gets live
 363  *
 364  * @return #GNUNET_YES if the operation was scheduled
 365  *         #GNUNET_NO  otherwise
 366  */
 367 int
 368 Peers_schedule_operation (const struct GNUNET_PeerIdentity *peer,
 369                           const PeerOp peer_op);
 370
 371 /* end of gnunet-service-rps_peers.h */