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  * @return the peer identity
  67  */
  68 const struct GNUNET_PeerIdentity *
  69 GCP_get_id (struct CadetPeer *cp);
  70
  71
  72 /**
  73  * Iterate over all known peers.
  74  *
  75  * @param iter Iterator.
  76  * @param cls Closure for @c iter.
  77  */
  78 void
  79 GCP_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter,
  80                  void *cls);
  81
  82
  83 /**
  84  * Count the number of known paths toward the peer.
  85  *
  86  * @param cp Peer to get path info.
  87  * @return Number of known paths.
  88  */
  89 unsigned int
  90 GCP_count_paths (const struct CadetPeer *cp);
  91
  92
  93 /**
  94  * Peer path iterator.
  95  *
  96  * @param cls Closure.
  97  * @param path Path itself
  98  * @param off offset of the target peer in @a path
  99  * @return #GNUNET_YES if should keep iterating.
 100  *         #GNUNET_NO otherwise.
 101  */
 102 typedef int
 103 (*GCP_PathIterator) (void *cls,
 104                      struct CadetPeerPath *path,
 105                      unsigned int off);
 106
 107
 108 /**
 109  * Iterate over the paths to a peer.
 110  *
 111  * @param cp Peer to get path info.
 112  * @param callback Function to call for every path.
 113  * @param callback_cls Closure for @a callback.
 114  * @return Number of iterated paths.
 115  */
 116 unsigned int
 117 GCP_iterate_paths (struct CadetPeer *cp,
 118                    GCP_PathIterator callback,
 119                    void *callback_cls);
 120
 121
 122 /**
 123  * Iterate over the paths to @a peer where
 124  * @a peer is at distance @a dist from us.
 125  *
 126  * @param peer Peer to get path info.
 127  * @param dist desired distance of @a peer to us on the path
 128  * @param callback Function to call for every path.
 129  * @param callback_cls Closure for @a callback.
 130  * @return Number of iterated paths.
 131  */
 132 unsigned int
 133 GCP_iterate_paths_at (struct CadetPeer *peer,
 134                       unsigned int dist,
 135                       GCP_PathIterator callback,
 136                       void *callback_cls);
 137
 138
 139 /**
 140  * Remove an entry from the DLL of all of the paths that this peer is on.
 141  *
 142  * @param cp peer to modify
 143  * @param entry an entry on a path
 144  * @param off offset of this peer on the path
 145  */
 146 void
 147 GCP_path_entry_remove (struct CadetPeer *cp,
 148                        struct CadetPeerPathEntry *entry,
 149                        unsigned int off);
 150
 151
 152 /**
 153  * Add an entry to the DLL of all of the paths that this peer is on.
 154  *
 155  * @param cp peer to modify
 156  * @param entry an entry on a path
 157  * @param off offset of this peer on the path
 158  */
 159 void
 160 GCP_path_entry_add (struct CadetPeer *cp,
 161                     struct CadetPeerPathEntry *entry,
 162                     unsigned int off);
 163
 164
 165 /**
 166  * Get the tunnel towards a peer.
 167  *
 168  * @param cp Peer to get from.
 169  * @param create #GNUNET_YES to create a tunnel if we do not have one
 170  * @return Tunnel towards peer.
 171  */
 172 struct CadetTunnel *
 173 GCP_get_tunnel (struct CadetPeer *cp,
 174                 int create);
 175
 176
 177 /**
 178  * The tunnel to the given peer no longer exists, remove it from our
 179  * data structures, and possibly clean up the peer itself.
 180  *
 181  * @param cp the peer affected
 182  * @param t the dead tunnel
 183  */
 184 void
 185 GCP_drop_tunnel (struct CadetPeer *cp,
 186                  struct CadetTunnel *t);
 187
 188
 189 /**
 190  * Try adding a @a path to this @a cp.  If the peer already
 191  * has plenty of paths, return NULL.
 192  *
 193  * @param cp peer to which the @a path leads to
 194  * @param path a path looking for an owner; may not be fully initialized yet!
 195  * @param off offset of @a cp in @a path
 196  * @return NULL if this peer does not care to become a new owner,
 197  *         otherwise the node in the peer's path heap for the @a path.
 198  */
 199 struct GNUNET_CONTAINER_HeapNode *
 200 GCP_attach_path (struct CadetPeer *cp,
 201                  struct CadetPeerPath *path,
 202                  unsigned int off);
 203
 204
 205 /**
 206  * This peer can no longer own @a path as the path
 207  * has been extended and a peer further down the line
 208  * is now the new owner.
 209  *
 210  * @param cp old owner of the @a path
 211  * @param path path where the ownership is lost
 212  * @param hn note in @a cp's path heap that must be deleted
 213  */
 214 void
 215 GCP_detach_path (struct CadetPeer *cp,
 216                  struct CadetPeerPath *path,
 217                  struct GNUNET_CONTAINER_HeapNode *hn);
 218
 219
 220 /**
 221  * Add a @a connection to this @a cp.
 222  *
 223  * @param cp peer via which the @a connection goes
 224  * @param cc the connection to add
 225  */
 226 void
 227 GCP_add_connection (struct CadetPeer *cp,
 228                     struct CadetConnection *cc);
 229
 230
 231 /**
 232  * Remove a @a connection that went via this @a cp.
 233  *
 234  * @param cp peer via which the @a connection went
 235  * @param cc the connection to remove
 236  */
 237 void
 238 GCP_remove_connection (struct CadetPeer *cp,
 239                        struct CadetConnection *cc);
 240
 241
 242 /**
 243  * We got a HELLO for a @a cp, remember it, and possibly
 244  * trigger adequate actions (like trying to connect).
 245  *
 246  * @param cp the peer we got a HELLO for
 247  * @param hello the HELLO to remember
 248  */
 249 void
 250 GCP_set_hello (struct CadetPeer *cp,
 251                const struct GNUNET_HELLO_Message *hello);
 252
 253
 254 /**
 255  * Clean up all entries about all peers.
 256  * Must only be called after all tunnels, CORE-connections and
 257  * connections are down.
 258  */
 259 void
 260 GCP_destroy_all_peers (void);
 261
 262
 263 /**
 264  * Data structure used to track whom we have to notify about changes
 265  * to our message queue.
 266  */
 267 struct GCP_MessageQueueManager;
 268
 269
 270 /**
 271  * Function to call with updated message queue object.
 272  *
 273  * @param cls closure
 274  * @param mq NULL if MQ is gone, otherwise an active message queue
 275  */
 276 typedef void
 277 (*GCP_MessageQueueNotificationCallback)(void *cls,
 278                                         struct GNUNET_MQ_Handle *mq);
 279
 280
 281 /**
 282  * Start message queue change notifications.
 283  *
 284  * @param cp peer to notify for
 285  * @param cb function to call if mq becomes available or unavailable
 286  * @param cb_cls closure for @a cb
 287  * @return handle to cancel request
 288  */
 289 struct GCP_MessageQueueManager *
 290 GCP_request_mq (struct CadetPeer *cp,
 291                 GCP_MessageQueueNotificationCallback cb,
 292                 void *cb_cls);
 293
 294
 295 /**
 296  * Stops message queue change notifications.
 297  *
 298  * @param mqm handle matching request to cancel
 299  */
 300 void
 301 GCP_request_mq_cancel (struct GCP_MessageQueueManager *mqm);
 302
 303
 304 /**
 305  * Set the message queue to @a mq for peer @a cp and notify watchers.
 306  *
 307  * @param cp peer to modify
 308  * @param mq message queue to set (can be NULL)
 309  */
 310 void
 311 GCP_set_mq (struct CadetPeer *cp,
 312             struct GNUNET_MQ_Handle *mq);
 313
 314
 315 /**
 316  * Get the message queue for peer @a cp.
 317  *
 318  * @param cp peer to modify
 319  * @return message queue (can be NULL)
 320  */
 321 struct GNUNET_MQ_Handle *
 322 GCP_get_mq (struct CadetPeer *cp);
 323
 324
 325 /**
 326  * Send the message in @a env to @a cp.
 327  *
 328  * @param cp the peer
 329  * @param env envelope with the message to send
 330  */
 331 void
 332 GCP_send (struct CadetPeer *cp,
 333           struct GNUNET_MQ_Envelope *env);
 334
 335
 336 #endif