src/cadet/gnunet-service-cadet_paths.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-new_paths.h
  23  * @brief Information we track per path.
  24  * @author Bartlomiej Polot
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_SERVICE_CADET_PATHS_H
  28 #define GNUNET_SERVICE_CADET_PATHS_H
  29
  30 #include "gnunet_util_lib.h"
  31 #include "gnunet-service-cadet.h"
  32
  33 /**
  34  * Create a peer path based on the result of a DHT lookup.  If we
  35  * already know this path, or one that is longer, simply return NULL.
  36  * Otherwise, we try to extend an existing path, or create a new one
  37  * if applicable.
  38  *
  39  * @param get_path path of the get request
  40  * @param get_path_length lenght of @a get_path
  41  * @param put_path path of the put request
  42  * @param put_path_length length of the @a put_path
  43  */
  44 void
  45 GCPP_try_path_from_dht (const struct GNUNET_PeerIdentity *get_path,
  46                         unsigned int get_path_length,
  47                         const struct GNUNET_PeerIdentity *put_path,
  48                         unsigned int put_path_length);
  49
  50
  51 /**
  52  * We got an incoming connection, obtain the corresponding path.
  53  *
  54  * @param path_length number of segments on the @a path
  55  * @param path through the network, in reverse order (we are at the end!)
  56  * @return corresponding path object
  57  */
  58 struct CadetPeerPath *
  59 GCPP_get_path_from_route (unsigned int path_length,
  60                           const struct GNUNET_PeerIdentity *pids);
  61
  62
  63 /**
  64  * Return the length of the path.  Excludes one end of the
  65  * path, so the loopback path has length 0.
  66  *
  67  * @param path path to return the length for
  68  * @return number of peers on the path
  69  */
  70 unsigned int
  71 GCPP_get_length (struct CadetPeerPath *path);
  72
  73
  74 /**
  75  * Return connection to @a destination using @a path, or return
  76  * NULL if no such connection exists.
  77  *
  78  * @param path path to traverse
  79  * @param destination destination node to get to, must be on path
  80  * @param off offset of @a destination on @a path
  81  * @return NULL if we have no existing connection
  82  *         otherwise connection from us to @a destination via @a path
  83  */
  84 struct CadetConnection *
  85 GCPP_get_connection (struct CadetPeerPath *path,
  86                      struct CadetPeer *destination,
  87                      unsigned int off);
  88
  89
  90 /**
  91  * Notify @a path that it is used for connection @a cc
  92  * which ends at the path's offset @a off.
  93  *
  94  * @param path the path to remember the @a cc
  95  * @param off the offset where the @a cc ends
  96  * @param cc the connection to remember
  97  */
  98 void
  99 GCPP_add_connection (struct CadetPeerPath *path,
 100                      unsigned int off,
 101                      struct CadetConnection *cc);
 102
 103
 104 /**
 105  * Notify @a path that it is no longer used for connection @a cc which
 106  * ended at the path's offset @a off.
 107  *
 108  * @param path the path to forget the @a cc
 109  * @param off the offset where the @a cc ended
 110  * @param cc the connection to forget
 111  */
 112 void
 113 GCPP_del_connection (struct CadetPeerPath *path,
 114                      unsigned int off,
 115                      struct CadetConnection *cc);
 116
 117
 118 /**
 119  * Find peer's offset on path.
 120  *
 121  * @param path path to search
 122  * @param cp peer to look for
 123  * @return offset of @a cp on @a path, or UINT_MAX if not found
 124  */
 125 unsigned int
 126 GCPP_find_peer (struct CadetPeerPath *path,
 127                 struct CadetPeer *cp);
 128
 129
 130 /**
 131  * Return how much we like keeping the path.  This is an aggregate
 132  * score based on various factors, including the age of the path
 133  * (older == better), and the value of this path to all of its ajacent
 134  * peers.  For example, long paths that end at a peer that we have no
 135  * shorter way to reach are very desirable, while long paths that end
 136  * at a peer for which we have a shorter way as well are much less
 137  * desirable.  Higher values indicate more valuable paths.  The
 138  * returned value should be used to decide which paths to remember.
 139  *
 140  * @param path path to return the length for
 141  * @return desirability of the path, larger is more desirable
 142  */
 143 GNUNET_CONTAINER_HeapCostType
 144 GCPP_get_desirability (const struct CadetPeerPath *path);
 145
 146
 147 /**
 148  * The given peer @a cp used to own this @a path.  However, it is no
 149  * longer interested in maintaining it, so the path should be
 150  * discarded or shortened (in case a previous peer on the path finds
 151  * the path desirable).
 152  *
 153  * @param path the path that is being released
 154  */
 155 void
 156 GCPP_release (struct CadetPeerPath *path);
 157
 158
 159 /**
 160  * Obtain the peer at offset @a off in @a path.
 161  *
 162  * @param path peer path to inspect
 163  * @param off offset to return, must be smaller than path length
 164  * @return peer at offset @a off
 165  */
 166 struct CadetPeer *
 167 GCPP_get_peer_at_offset (struct CadetPeerPath *path,
 168                          unsigned int off);
 169
 170
 171 /**
 172  * Convert a path to a human-readable string.
 173  *
 174  * @param path path to convert
 175  * @return string, statically allocated
 176  */
 177 const char *
 178 GCPP_2s (struct CadetPeerPath *p);
 179
 180
 181 #endif