src/cadet/gnunet-service-cadet-new_peer.h

   1
   2 /*
   3      This file is part of GNUnet.
   4      Copyright (C) 2001-2017 GNUnet e.V.
   5
   6      GNUnet is free software; you can redistribute it and/or modify
   7      it under the terms of the GNU General Public License as published
   8      by the Free Software Foundation; either version 3, or (at your
   9      option) any later version.
  10
  11      GNUnet is distributed in the hope that it will be useful, but
  12      WITHOUT ANY WARRANTY; without even the implied warranty of
  13      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14      General Public License for more details.
  15
  16      You should have received a copy of the GNU General Public License
  17      along with GNUnet; see the file COPYING.  If not, write to the
  18      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19      Boston, MA 02110-1301, USA.
  20 */
  21
  22 /**
  23  * @file cadet/gnunet-service-cadet-new_peer.h
  24  * @brief Information we track per peer.
  25  * @author Bartlomiej Polot
  26  * @author Christian Grothoff
  27  */
  28 #ifndef GNUNET_SERVICE_CADET_PEER_H
  29 #define GNUNET_SERVICE_CADET_PEER_H
  30
  31 #include "gnunet-service-cadet-new.h"
  32 #include "gnunet_hello_lib.h"
  33
  34
  35 /**
  36  * Get the static string for a peer ID.
  37  *
  38  * @param peer Peer.
  39  *
  40  * @return Static string for it's ID.
  41  */
  42 const char *
  43 GCP_2s (const struct CadetPeer *peer);
  44
  45
  46 /**
  47  * Retrieve the CadetPeer stucture associated with the
  48  * peer. Optionally create one and insert it in the appropriate
  49  * structures if the peer is not known yet.
  50  *
  51  * @param peer_id Full identity of the peer.
  52  * @param create #GNUNET_YES if a new peer should be created if unknown.
  53  *               #GNUNET_NO to return NULL if peer is unknown.
  54  * @return Existing or newly created peer structure.
  55  *         NULL if unknown and not requested @a create
  56  */
  57 struct CadetPeer *
  58 GCP_get (const struct GNUNET_PeerIdentity *peer_id,
  59          int create);
  60
  61
  62 /**
  63  * Obtain the peer identity for a `struct CadetPeer`.
  64  *
  65  * @param cp our peer handle
  66  * @param[out] peer_id where to write the peer identity
  67  */
  68 void
  69 GCP_id (struct CadetPeer *cp,
  70         struct GNUNET_PeerIdentity *peer_id);
  71
  72
  73 /**
  74  * Iterate over all known peers.
  75  *
  76  * @param iter Iterator.
  77  * @param cls Closure for @c iter.
  78  */
  79 void
  80 GCP_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter,
  81                  void *cls);
  82
  83
  84 /**
  85  * Count the number of known paths toward the peer.
  86  *
  87  * @param peer Peer to get path info.
  88  * @return Number of known paths.
  89  */
  90 unsigned int
  91 GCP_count_paths (const struct CadetPeer *peer);
  92
  93
  94 /**
  95  * Peer path iterator.
  96  *
  97  * @param cls Closure.
  98  * @param peer Peer this path is towards.
  99  * @param path Path itself
 100  * @return #GNUNET_YES if should keep iterating.
 101  *         #GNUNET_NO otherwise.
 102  *
 103  * FIXME: peer argument should be redundant; remove!
 104  */
 105 typedef int
 106 (*GCP_PathIterator) (void *cls,
 107                      struct CadetPeer *peer,
 108                      struct CadetPeerPath *path);
 109
 110
 111 /**
 112  * Iterate over the paths to a peer.
 113  *
 114  * @param peer Peer to get path info.
 115  * @param callback Function to call for every path.
 116  * @param callback_cls Closure for @a callback.
 117  * @return Number of iterated paths.
 118  */
 119 unsigned int
 120 GCP_iterate_paths (struct CadetPeer *peer,
 121                    GCP_PathIterator callback,
 122                    void *callback_cls);
 123
 124
 125 /**
 126  * Remove an entry from the DLL of all of the paths that this peer is on.
 127  *
 128  * @param cp peer to modify
 129  * @param entry an entry on a path
 130  * @param off offset of this peer on the path
 131  */
 132 void
 133 GCP_path_entry_remove (struct CadetPeer *cp,
 134                        struct CadetPeerPathEntry *entry,
 135                        unsigned int off);
 136
 137
 138 /**
 139  * Add an entry to the DLL of all of the paths that this peer is on.
 140  *
 141  * @param cp peer to modify
 142  * @param entry an entry on a path
 143  * @param off offset of this peer on the path
 144  */
 145 void
 146 GCP_path_entry_add (struct CadetPeer *cp,
 147                     struct CadetPeerPathEntry *entry,
 148                     unsigned int off);
 149
 150
 151 /**
 152  * Get the tunnel towards a peer.
 153  *
 154  * @param peer Peer to get from.
 155  * @param create #GNUNET_YES to create a tunnel if we do not have one
 156  * @return Tunnel towards peer.
 157  */
 158 struct CadetTunnel *
 159 GCP_get_tunnel (struct CadetPeer *peer,
 160                 int create);
 161
 162
 163 /**
 164  * The tunnel to the given peer no longer exists, remove it from our
 165  * data structures, and possibly clean up the peer itself.
 166  *
 167  * @param peer the peer affected
 168  * @param t the dead tunnel
 169  */
 170 void
 171 GCP_drop_tunnel (struct CadetPeer *peer,
 172                  struct CadetTunnel *t);
 173
 174
 175 /**
 176  * We got a HELLO for a @a peer, remember it, and possibly
 177  * trigger adequate actions (like trying to connect).
 178  *
 179  * @param peer the peer we got a HELLO for
 180  * @param hello the HELLO to remember
 181  */
 182 void
 183 GCP_set_hello (struct CadetPeer *peer,
 184                const struct GNUNET_HELLO_Message *hello);
 185
 186
 187 /**
 188  * Clean up all entries about all peers.
 189  * Must only be called after all tunnels, CORE-connections and
 190  * connections are down.
 191  */
 192 void
 193 GCP_destroy_all_peers (void);
 194
 195
 196 #endif