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