2 This file is part of GNUnet.
3 Copyright (C) 2001 - 2013 GNUnet e.V.
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.
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.
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.
22 * @file cadet/cadet_path.h
23 * @brief Path handling functions
24 * @author Bartlomiej Polot
33 #if 0 /* keep Emacsens' auto-indent happy */
39 /******************************************************************************/
40 /************************ DATA STRUCTURES ****************************/
41 /******************************************************************************/
44 * Information regarding a possible path to reach a single peer
52 struct CadetPeerPath *next;
53 struct CadetPeerPath *prev;
56 * List of all the peers that form the path from origin to target.
58 GNUNET_PEER_Id *peers;
61 * Number of peers (hops) in the path
66 * User defined data store.
68 struct CadetConnection *c;
71 * Path's score, how reliable is the path.
76 * Task to delete the path.
77 * We tried it, it didn't work, don't try again in a while.
79 struct GNUNET_SCHEDULER_Task * path_delete;
83 /******************************************************************************/
84 /************************* FUNCTIONS *****************************/
85 /******************************************************************************/
90 * @param length How many hops will the path have.
92 * @return A newly allocated path with a peer array of the specified length.
94 struct CadetPeerPath *
95 path_new (unsigned int length);
101 * @param path The path to invert.
104 path_invert (struct CadetPeerPath *path);
108 * Duplicate a path, incrementing short peer's rc.
110 * @param path The path to duplicate.
112 struct CadetPeerPath *
113 path_duplicate (const struct CadetPeerPath *path);
117 * Get the length of a path.
119 * @param path The path to measure, with the local peer at any point of it.
121 * @return Number of hops to reach destination.
122 * UINT_MAX in case the peer is not in the path.
125 path_get_length (struct CadetPeerPath *path);
128 * Mark path as invalid: keep it aroud for a while to avoid trying it in a loop.
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.
133 * @param p Path to invalidate.
136 path_invalidate (struct CadetPeerPath *p);
139 * Test if two paths are equivalent (equal or revese of each other).
141 * @param p1 First path
142 * @param p2 Second path
144 * @return GNUNET_YES if both paths are equivalent
145 * GNUNET_NO otherwise
148 path_equivalent (const struct CadetPeerPath *p1,
149 const struct CadetPeerPath *p2);
152 * Test if a path is valid (or at least not known to be invalid).
154 * @param path Path to test.
156 * @return #GNUNET_YES If the path is valid or unknown,
157 * #GNUNET_NO If the path is known to be invalid.
160 path_is_valid (const struct CadetPeerPath *path);
163 * Destroy the path and free any allocated resources linked to it
165 * @param p the path to destroy
167 * @return GNUNET_OK on success
170 path_destroy (struct CadetPeerPath *p);
175 * @param p1 First path.
176 * @param p2 Second path.
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.
183 path_cmp (const struct CadetPeerPath *p1, const struct CadetPeerPath *p2);
186 * Builds a path from a PeerIdentity array.
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.
193 * @return Fixed and shortened path.
195 struct CadetPeerPath *
196 path_build_from_peer_ids (struct GNUNET_PeerIdentity *peers,
199 unsigned int *own_pos);
202 * Path -> allocated one line string. Caller must free.
207 path_2s (struct CadetPeerPath *p);
210 * Print info about the path for debug.
212 * @param p Path to debug.
215 path_debug (struct CadetPeerPath *p);
217 #if 0 /* keep Emacsens' auto-indent happy */
225 /* ifndef CADET_PATH_H */