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