src/cadet/gnunet-service-cadet_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.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  * Calculate how desirable a path is for @a cp if
  64  * @a cp is at offset @a off in the path.
  65  *
  66  * @param cp a peer reachable via a path
  67  * @param off offset of @a cp in a path
  68  * @return score how useful a path is to reach @a cp,
  69  *         positive scores mean path is more desirable
  70  */
  71 double
  72 GCP_get_desirability_of_path (struct CadetPeer *cp,
  73                               unsigned int off);
  74
  75
  76 /**
  77  * Obtain the peer identity for a `struct CadetPeer`.
  78  *
  79  * @param cp our peer handle
  80  * @return the peer identity
  81  */
  82 const struct GNUNET_PeerIdentity *
  83 GCP_get_id (struct CadetPeer *cp);
  84
  85
  86 /**
  87  * Iterate over all known peers.
  88  *
  89  * @param iter Iterator.
  90  * @param cls Closure for @c iter.
  91  */
  92 void
  93 GCP_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter,
  94                  void *cls);
  95
  96
  97 /**
  98  * Count the number of known paths toward the peer.
  99  *
 100  * @param cp Peer to get path info.
 101  * @return Number of known paths.
 102  */
 103 unsigned int
 104 GCP_count_paths (const struct CadetPeer *cp);
 105
 106
 107 /**
 108  * Drop all paths owned by this peer, and do not
 109  * allow new ones to be added: We are shutting down.
 110  *
 111  * @param cp peer to drop paths to
 112  */
 113 void
 114 GCP_drop_owned_paths (struct CadetPeer *cp);
 115
 116
 117 /**
 118  * Peer path iterator.
 119  *
 120  * @param cls Closure.
 121  * @param path Path itself
 122  * @param off offset of the target peer in @a path
 123  * @return #GNUNET_YES if should keep iterating.
 124  *         #GNUNET_NO otherwise.
 125  */
 126 typedef int
 127 (*GCP_PathIterator) (void *cls,
 128                      struct CadetPeerPath *path,
 129                      unsigned int off);
 130
 131
 132 /**
 133  * Iterate over the paths to a peer.
 134  *
 135  * @param cp Peer to get path info.
 136  * @param callback Function to call for every path.
 137  * @param callback_cls Closure for @a callback.
 138  * @return Number of iterated paths.
 139  */
 140 unsigned int
 141 GCP_iterate_paths (struct CadetPeer *cp,
 142                    GCP_PathIterator callback,
 143                    void *callback_cls);
 144
 145
 146 /**
 147  * Iterate over the paths to @a peer where
 148  * @a peer is at distance @a dist from us.
 149  *
 150  * @param cp Peer to get path info.
 151  * @param dist desired distance of @a peer to us on the path
 152  * @param callback Function to call for every path.
 153  * @param callback_cls Closure for @a callback.
 154  * @return Number of iterated paths.
 155  */
 156 unsigned int
 157 GCP_iterate_paths_at (struct CadetPeer *cp,
 158                       unsigned int dist,
 159                       GCP_PathIterator callback,
 160                       void *callback_cls);
 161
 162
 163 /**
 164  * Remove an entry from the DLL of all of the paths that this peer is on.
 165  *
 166  * @param cp peer to modify
 167  * @param entry an entry on a path
 168  * @param off offset of this peer on the path
 169  */
 170 void
 171 GCP_path_entry_remove (struct CadetPeer *cp,
 172                        struct CadetPeerPathEntry *entry,
 173                        unsigned int off);
 174
 175
 176 /**
 177  * Add an entry to the DLL of all of the paths that this peer is on.
 178  *
 179  * @param cp peer to modify
 180  * @param entry an entry on a path
 181  * @param off offset of this peer on the path
 182  */
 183 void
 184 GCP_path_entry_add (struct CadetPeer *cp,
 185                     struct CadetPeerPathEntry *entry,
 186                     unsigned int off);
 187
 188
 189 /**
 190  * Get the tunnel towards a peer.
 191  *
 192  * @param cp Peer to get from.
 193  * @param create #GNUNET_YES to create a tunnel if we do not have one
 194  * @return Tunnel towards peer.
 195  */
 196 struct CadetTunnel *
 197 GCP_get_tunnel (struct CadetPeer *cp,
 198                 int create);
 199
 200
 201 /**
 202  * The tunnel to the given peer no longer exists, remove it from our
 203  * data structures, and possibly clean up the peer itself.
 204  *
 205  * @param cp the peer affected
 206  * @param t the dead tunnel
 207  */
 208 void
 209 GCP_drop_tunnel (struct CadetPeer *cp,
 210                  struct CadetTunnel *t);
 211
 212
 213 /**
 214  * Try adding a @a path to this @a cp.  If the peer already
 215  * has plenty of paths, return NULL.
 216  *
 217  * @param cp peer to which the @a path leads to
 218  * @param path a path looking for an owner; may not be fully initialized yet!
 219  * @param off offset of @a cp in @a path
 220  * @param force for attaching the path
 221  * @return NULL if this peer does not care to become a new owner,
 222  *         otherwise the node in the peer's path heap for the @a path.
 223  */
 224 struct GNUNET_CONTAINER_HeapNode *
 225 GCP_attach_path (struct CadetPeer *cp,
 226                  struct CadetPeerPath *path,
 227                  unsigned int off,
 228                  int force);
 229
 230
 231 /**
 232  * This peer can no longer own @a path as the path
 233  * has been extended and a peer further down the line
 234  * is now the new owner.
 235  *
 236  * @param cp old owner of the @a path
 237  * @param path path where the ownership is lost
 238  * @param hn note in @a cp's path heap that must be deleted
 239  */
 240 void
 241 GCP_detach_path (struct CadetPeer *cp,
 242                  struct CadetPeerPath *path,
 243                  struct GNUNET_CONTAINER_HeapNode *hn);
 244
 245
 246 /**
 247  * Add a @a connection to this @a cp.
 248  *
 249  * @param cp peer via which the @a connection goes
 250  * @param cc the connection to add
 251  */
 252 void
 253 GCP_add_connection (struct CadetPeer *cp,
 254                     struct CadetConnection *cc);
 255
 256
 257 /**
 258  * Remove a @a connection that went via this @a cp.
 259  *
 260  * @param cp peer via which the @a connection went
 261  * @param cc the connection to remove
 262  */
 263 void
 264 GCP_remove_connection (struct CadetPeer *cp,
 265                        struct CadetConnection *cc);
 266
 267
 268 /**
 269  * We got a HELLO for a @a cp, remember it, and possibly
 270  * trigger adequate actions (like trying to connect).
 271  *
 272  * @param cp the peer we got a HELLO for
 273  * @param hello the HELLO to remember
 274  */
 275 void
 276 GCP_set_hello (struct CadetPeer *cp,
 277                const struct GNUNET_HELLO_Message *hello);
 278
 279
 280 /**
 281  * Clean up all entries about all peers.
 282  * Must only be called after all tunnels, CORE-connections and
 283  * connections are down.
 284  */
 285 void
 286 GCP_destroy_all_peers (void);
 287
 288
 289 /**
 290  * Data structure used to track whom we have to notify about changes
 291  * in our ability to transmit to a given peer.
 292  *
 293  * All queue managers will be given equal chance for sending messages
 294  * to @a cp.  This construct this guarantees fairness for access to @a
 295  * cp among the different message queues.  Each connection or route
 296  * will have its respective message queue managers for each direction.
 297  */
 298 struct GCP_MessageQueueManager;
 299
 300
 301 /**
 302  * Function to call with updated message queue object.
 303  *
 304  * @param cls closure
 305  * @param available #GNUNET_YES if sending is now possible,
 306  *                  #GNUNET_NO if sending is no longer possible
 307  *                  #GNUNET_SYSERR if sending is no longer possible
 308  *                                 and the last envelope was discarded
 309  */
 310 typedef void
 311 (*GCP_MessageQueueNotificationCallback)(void *cls,
 312                                         int available);
 313
 314
 315 /**
 316  * Start message queue change notifications.  Will create a new slot
 317  * to manage the message queue to the given @a cp.
 318  *
 319  * @param cp peer to notify for
 320  * @param cb function to call if mq becomes available or unavailable
 321  * @param cb_cls closure for @a cb
 322  * @return handle to cancel request
 323  */
 324 struct GCP_MessageQueueManager *
 325 GCP_request_mq (struct CadetPeer *cp,
 326                 GCP_MessageQueueNotificationCallback cb,
 327                 void *cb_cls);
 328
 329
 330 /**
 331  * Test if @a cp has a core-level connection
 332  *
 333  * @param cp peer to test
 334  * @return #GNUNET_YES if @a cp has a core-level connection
 335  */
 336 int
 337 GCP_has_core_connection (struct CadetPeer *cp);
 338
 339
 340 /**
 341  * Send the message in @a env via a @a mqm.  Must only be called at
 342  * most once after the respective
 343  * #GCP_MessageQueueNotificationCallback was called with `available`
 344  * set to #GNUNET_YES, and not after the callback was called with
 345  * `available` set to #GNUNET_NO or #GNUNET_SYSERR.
 346  *
 347  * @param mqm message queue manager for the transmission
 348  * @param env envelope with the message to send; must NOT
 349  *            yet have a #GNUNET_MQ_notify_sent() callback attached to it
 350  */
 351 void
 352 GCP_send (struct GCP_MessageQueueManager *mqm,
 353           struct GNUNET_MQ_Envelope *env);
 354
 355
 356 /**
 357  * Send the message in @a env to @a cp, overriding queueing logic.
 358  * This function should only be used to send error messages outside
 359  * of flow and congestion control, similar to ICMP.  Note that
 360  * the envelope may be silently discarded as well.
 361  *
 362  * @param cp peer to send the message to
 363  * @param env envelope with the message to send
 364  */
 365 void
 366 GCP_send_ooo (struct CadetPeer *cp,
 367               struct GNUNET_MQ_Envelope *env);
 368
 369
 370 /**
 371  * Stops message queue change notifications and sends a last message.
 372  * In practice, this is implemented by sending that @a last_env
 373  * message immediately (if any), ignoring queue order.
 374  *
 375  * @param mqm handle matching request to cancel
 376  * @param last_env final message to transmit, or NULL
 377  */
 378 void
 379 GCP_request_mq_cancel (struct GCP_MessageQueueManager *mqm,
 380                        struct GNUNET_MQ_Envelope *last_env);
 381
 382
 383 /**
 384  * Set the message queue to @a mq for peer @a cp and notify watchers.
 385  *
 386  * @param cp peer to modify
 387  * @param mq message queue to set (can be NULL)
 388  */
 389 void
 390 GCP_set_mq (struct CadetPeer *cp,
 391             struct GNUNET_MQ_Handle *mq);
 392
 393
 394 #endif