src/mesh/mesh_tunnel_tree.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001 - 2011 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 mesh/mesh_tunnel_tree.h
  23  * @brief Tunnel tree handling functions
  24  * @author Bartlomiej Polot
  25  */
  26
  27 #include "mesh.h"
  28
  29
  30 /**
  31  * Invert the path
  32  *
  33  * @param p the path to invert
  34  */
  35 void
  36 path_invert (struct MeshPeerPath *path);
  37
  38
  39
  40 /**
  41  * Destroy the path and free any allocated resources linked to it
  42  *
  43  * @param p the path to destroy
  44  *
  45  * @return GNUNET_OK on success
  46  */
  47 int
  48 path_destroy (struct MeshPeerPath *p);
  49
  50
  51 /**
  52  * Find the first peer whom to send a packet to go down this path
  53  *
  54  * @param t The tunnel to use
  55  * @param peer The peerinfo of the peer we are trying to reach
  56  *
  57  * @return peerinfo of the peer who is the first hop in the tunnel
  58  *         NULL on error
  59  */
  60 struct GNUNET_PeerIdentity *
  61 path_get_first_hop (struct MeshTunnel *t, struct MeshPeerInfo *peer);
  62
  63
  64 /**
  65  * Get the length of a path
  66  *
  67  * @param path The path to measure, with the local peer at any point of it
  68  *
  69  * @return Number of hops to reach destination
  70  *         UINT_MAX in case the peer is not in the path
  71  */
  72 unsigned int
  73 path_get_length (struct MeshPeerPath *path);
  74
  75
  76 /**
  77  * Get the cost of the path relative to the already built tunnel tree
  78  *
  79  * @param t The tunnel to which compare
  80  * @param path The individual path to reach a peer
  81  *
  82  * @return Number of hops to reach destination, UINT_MAX in case the peer is not
  83  * in the path
  84  */
  85 unsigned int
  86 path_get_cost (struct MeshTunnel *t, struct MeshPeerPath *path);
  87
  88 /**
  89  * Add the path to the peer and update the path used to reach it in case this
  90  * is the shortest.
  91  *
  92  * @param peer_info Destination peer to add the path to.
  93  * @param path New path to add. Last peer must be the peer in arg 1.
  94  *             Path will be either used of freed if already known.
  95  */
  96 void
  97 path_add_to_peer (struct MeshPeerInfo *peer_info, struct MeshPeerPath *path);
  98
  99
 100 /**
 101  * Send keepalive packets for a peer
 102  *
 103  * @param cls unused
 104  * @param tc unused
 105  */
 106 void
 107 path_refresh (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
 108
 109
 110 /**
 111  * Recursively find the given peer in the tree.
 112  *
 113  * @param t Tunnel where to look for the peer.
 114  * @param peer Peer to find
 115  *
 116  * @return Pointer to the node of the peer. NULL if not found.
 117  */
 118 struct MeshTunnelPathNode *
 119 tunnel_find_peer (struct MeshTunnelPathNode *root, GNUNET_PEER_Id peer_id);
 120
 121
 122 /**
 123  * Recusively mark peer and children as disconnected, notify client
 124  *
 125  * @param parent Node to be clean, potentially with children
 126  * @param nc Notification context to use to alert the client
 127  */
 128 void
 129 tunnel_mark_peers_disconnected (struct MeshTunnelPathNode *parent,
 130                                 struct GNUNET_SERVER_NotificationContext *nc);
 131
 132
 133 /**
 134  * Delete the current path to the peer, including all now unused relays.
 135  * The destination peer is NOT destroyed, it is returned in order to either set
 136  * a new path to it or destroy it explicitly, taking care of it's child nodes.
 137  *
 138  * @param t Tunnel where to delete the path from.
 139  * @param peer Destination peer whose path we want to remove.
 140  * @param nc Notification context to alert the client of disconnected peers.
 141  *
 142  * @return pointer to the pathless node, NULL on error
 143  */
 144 struct MeshTunnelPathNode *
 145 tunnel_del_path (struct MeshTunnel *t, GNUNET_PEER_Id peer_id,
 146                  struct GNUNET_SERVER_NotificationContext *nc);
 147
 148
 149 /**
 150  * Return a newly allocated individual path to reach a peer from the local peer,
 151  * according to the path tree of some tunnel.
 152  *
 153  * @param t Tunnel from which to read the path tree
 154  * @param peer_info Destination peer to whom we want a path
 155  *
 156  * @return A newly allocated individual path to reach the destination peer.
 157  *         Path must be destroyed afterwards.
 158  */
 159 struct MeshPeerPath *
 160 tunnel_get_path_to_peer(struct MeshTunnel *t, struct MeshPeerInfo *peer_info);
 161
 162
 163 /**
 164  * Integrate a stand alone path into the tunnel tree.
 165  *
 166  * @param t Tunnel where to add the new path.
 167  * @param p Path to be integrated.
 168  * @param nc Notification context to alert clients of peers
 169  *           temporarily disconnected
 170  *
 171  * @return GNUNET_OK in case of success.
 172  *         GNUNET_SYSERR in case of error.
 173  */
 174 int
 175 tunnel_add_path (struct MeshTunnel *t, const struct MeshPeerPath *p);
 176
 177
 178 /**
 179  * Add a peer to a tunnel, accomodating paths accordingly and initializing all
 180  * needed rescources.
 181  *
 182  * @param t Tunnel we want to add a new peer to
 183  * @param peer PeerInfo of the peer being added
 184  *
 185  */
 186 void
 187 tunnel_add_peer (struct MeshTunnel *t, struct MeshPeerInfo *peer);