src/cadet/cadet_path.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001 - 2013 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, 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 #include "gnunet-service-cadet_connection.h"
  39
  40
  41 /******************************************************************************/
  42 /************************      DATA STRUCTURES     ****************************/
  43 /******************************************************************************/
  44
  45 /**
  46  * Information regarding a possible path to reach a single peer
  47  */
  48 struct CadetPeerPath
  49 {
  50
  51     /**
  52      * Linked list
  53      */
  54   struct CadetPeerPath *next;
  55   struct CadetPeerPath *prev;
  56
  57     /**
  58      * List of all the peers that form the path from origin to target.
  59      */
  60   GNUNET_PEER_Id *peers;
  61
  62     /**
  63      * Number of peers (hops) in the path
  64      */
  65   unsigned int length;
  66
  67     /**
  68      * User defined data store.
  69      */
  70   struct CadetConnection *c;
  71
  72     /**
  73      * Path's score, how reliable is the path.
  74      */
  75 //   int score;
  76
  77   /**
  78    * Task to delete the path.
  79    * We tried it, it didn't work, don't try again in a while.
  80    */
  81   GNUNET_SCHEDULER_TaskIdentifier path_delete;
  82
  83 };
  84
  85 /******************************************************************************/
  86 /*************************        FUNCTIONS       *****************************/
  87 /******************************************************************************/
  88
  89 /**
  90  * Create a new path.
  91  *
  92  * @param length How many hops will the path have.
  93  *
  94  * @return A newly allocated path with a peer array of the specified length.
  95  */
  96 struct CadetPeerPath *
  97 path_new (unsigned int length);
  98
  99
 100 /**
 101  * Invert the path.
 102  *
 103  * @param path The path to invert.
 104  */
 105 void
 106 path_invert (struct CadetPeerPath *path);
 107
 108
 109 /**
 110  * Duplicate a path, incrementing short peer's rc.
 111  *
 112  * @param path The path to duplicate.
 113  */
 114 struct CadetPeerPath *
 115 path_duplicate (const struct CadetPeerPath *path);
 116
 117
 118 /**
 119  * Get the length of a path.
 120  *
 121  * @param path The path to measure, with the local peer at any point of it.
 122  *
 123  * @return Number of hops to reach destination.
 124  *         UINT_MAX in case the peer is not in the path.
 125  */
 126 unsigned int
 127 path_get_length (struct CadetPeerPath *path);
 128
 129 /**
 130  * Mark path as invalid: keep it aroud for a while to avoid trying it in a loop.
 131  *
 132  * DHT_get sometimes returns bad cached results, for instance, on a locally
 133  * cached result where the PUT followed a path that is no longer current.
 134  *
 135  * @param p Path to invalidate.
 136  */
 137 void
 138 path_invalidate (struct CadetPeerPath *p);
 139
 140 /**
 141  * Test if a path is valid (or at least not known to be invalid).
 142  *
 143  * @param path Path to test.
 144  *
 145  * @return #GNUNET_YES If the path is valid or unknown,
 146  *         #GNUNET_NO If the path is known to be invalid.
 147  */
 148 int
 149 path_is_valid (const struct CadetPeerPath *path);
 150
 151 /**
 152  * Destroy the path and free any allocated resources linked to it
 153  *
 154  * @param p the path to destroy
 155  *
 156  * @return GNUNET_OK on success
 157  */
 158 int
 159 path_destroy (struct CadetPeerPath *p);
 160
 161 /**
 162  * Builds a path from a PeerIdentity array.
 163  *
 164  * @param peers PeerIdentity array.
 165  * @param size Size of the @c peers array.
 166  * @param myid ID of local peer, to find @c own_pos.
 167  * @param own_pos Output parameter: own position in the path.
 168  *
 169  * @return Fixed and shortened path.
 170  */
 171 struct CadetPeerPath *
 172 path_build_from_peer_ids (struct GNUNET_PeerIdentity *peers,
 173                           unsigned int size,
 174                           GNUNET_PEER_Id myid,
 175                           unsigned int *own_pos);
 176
 177 /**
 178  * Path -> allocated one line string. Caller must free.
 179  *
 180  * @param p Path.
 181  */
 182 char *
 183 path_2s (struct CadetPeerPath *p);
 184
 185 /**
 186  * Print info about the path for debug.
 187  *
 188  * @param p Path to debug.
 189  */
 190 void
 191 path_debug (struct CadetPeerPath *p);
 192
 193 #if 0                           /* keep Emacsens' auto-indent happy */
 194 {
 195   #endif
 196   #ifdef __cplusplus
 197 }
 198 #endif
 199
 200
 201 /* ifndef CADET_PATH_H */
 202 #endif