src/cadet/gnunet-service-cadet_peer.h

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