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