src/cadet/cadet_path.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2001 - 2013 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @file cadet/cadet_path.h
  23  * @brief Path handling functions
  24  * @author Bartlomiej Polot
  25  */
  26
  27 #ifndef CADET_PATH_H_
  28 #define CADET_PATH_H_
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33   #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38
  39 /******************************************************************************/
  40 /************************      DATA STRUCTURES     ****************************/
  41 /******************************************************************************/
  42
  43 /**
  44  * Information regarding a possible path to reach a single peer
  45  */
  46 struct CadetPeerPath
  47 {
  48
  49     /**
  50      * Linked list
  51      */
  52   struct CadetPeerPath *next;
  53   struct CadetPeerPath *prev;
  54
  55     /**
  56      * List of all the peers that form the path from origin to target.
  57      */
  58   GNUNET_PEER_Id *peers;
  59
  60     /**
  61      * Number of peers (hops) in the path
  62      */
  63   unsigned int length;
  64
  65     /**
  66      * User defined data store.
  67      */
  68   struct CadetConnection *c;
  69
  70     /**
  71      * Path's score, how reliable is the path.
  72      */
  73 //   int score;
  74
  75   /**
  76    * Task to delete the path.
  77    * We tried it, it didn't work, don't try again in a while.
  78    */
  79   struct GNUNET_SCHEDULER_Task * path_delete;
  80
  81 };
  82
  83 /******************************************************************************/
  84 /*************************        FUNCTIONS       *****************************/
  85 /******************************************************************************/
  86
  87 /**
  88  * Create a new path.
  89  *
  90  * @param length How many hops will the path have.
  91  *
  92  * @return A newly allocated path with a peer array of the specified length.
  93  */
  94 struct CadetPeerPath *
  95 path_new (unsigned int length);
  96
  97
  98 /**
  99  * Invert the path.
 100  *
 101  * @param path The path to invert.
 102  */
 103 void
 104 path_invert (struct CadetPeerPath *path);
 105
 106
 107 /**
 108  * Duplicate a path, incrementing short peer's rc.
 109  *
 110  * @param path The path to duplicate.
 111  */
 112 struct CadetPeerPath *
 113 path_duplicate (const struct CadetPeerPath *path);
 114
 115
 116 /**
 117  * Get the length of a path.
 118  *
 119  * @param path The path to measure, with the local peer at any point of it.
 120  *
 121  * @return Number of hops to reach destination.
 122  *         UINT_MAX in case the peer is not in the path.
 123  */
 124 unsigned int
 125 path_get_length (struct CadetPeerPath *path);
 126
 127 /**
 128  * Mark path as invalid: keep it aroud for a while to avoid trying it in a loop.
 129  *
 130  * DHT_get sometimes returns bad cached results, for instance, on a locally
 131  * cached result where the PUT followed a path that is no longer current.
 132  *
 133  * @param p Path to invalidate.
 134  */
 135 void
 136 path_invalidate (struct CadetPeerPath *p);
 137
 138 /**
 139  * Test if two paths are equivalent (equal or revese of each other).
 140  *
 141  * @param p1 First path
 142  * @param p2 Second path
 143  *
 144  * @return GNUNET_YES if both paths are equivalent
 145  *         GNUNET_NO otherwise
 146  */
 147 int
 148 path_equivalent (const struct CadetPeerPath *p1,
 149                  const struct CadetPeerPath *p2);
 150
 151 /**
 152  * Test if a path is valid (or at least not known to be invalid).
 153  *
 154  * @param path Path to test.
 155  *
 156  * @return #GNUNET_YES If the path is valid or unknown,
 157  *         #GNUNET_NO If the path is known to be invalid.
 158  */
 159 int
 160 path_is_valid (const struct CadetPeerPath *path);
 161
 162 /**
 163  * Destroy the path and free any allocated resources linked to it
 164  *
 165  * @param p the path to destroy
 166  *
 167  * @return GNUNET_OK on success
 168  */
 169 int
 170 path_destroy (struct CadetPeerPath *p);
 171
 172 /**
 173  * Compare two paths.
 174  *
 175  * @param p1 First path.
 176  * @param p2 Second path.
 177  *
 178  * @return > 0 if p1 is longer, or the first differing PEER_Id is higher on p1.
 179  *         < 0 if p2 is longer, or the first differing PEER_Id is higher on p2.
 180  *         0 if they are identical.
 181  */
 182 int
 183 path_cmp (const struct CadetPeerPath *p1, const struct CadetPeerPath *p2);
 184
 185 /**
 186  * Builds a path from a PeerIdentity array.
 187  *
 188  * @param peers PeerIdentity array.
 189  * @param size Size of the @c peers array.
 190  * @param myid ID of local peer, to find @c own_pos.
 191  * @param own_pos Output parameter: own position in the path.
 192  *
 193  * @return Fixed and shortened path.
 194  */
 195 struct CadetPeerPath *
 196 path_build_from_peer_ids (struct GNUNET_PeerIdentity *peers,
 197                           unsigned int size,
 198                           GNUNET_PEER_Id myid,
 199                           unsigned int *own_pos);
 200
 201 /**
 202  * Path -> allocated one line string. Caller must free.
 203  *
 204  * @param p Path.
 205  */
 206 char *
 207 path_2s (struct CadetPeerPath *p);
 208
 209 /**
 210  * Print info about the path for debug.
 211  *
 212  * @param p Path to debug.
 213  */
 214 void
 215 path_debug (struct CadetPeerPath *p);
 216
 217 #if 0                           /* keep Emacsens' auto-indent happy */
 218 {
 219   #endif
 220   #ifdef __cplusplus
 221 }
 222 #endif
 223
 224
 225 /* ifndef CADET_PATH_H */
 226 #endif