src/mesh/gnunet-service-mesh_peer.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 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 mesh/gnunet-service-mesh_peer.h
  23  * @brief mesh service; dealing with remote peers
  24  * @author Bartlomiej Polot
  25  *
  26  * All functions in this file should use the prefix GMP (Gnunet Mesh Peer)
  27  */
  28
  29 #ifndef GNUNET_SERVICE_MESH_PEER_H
  30 #define GNUNET_SERVICE_MESH_PEER_H
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "platform.h"
  41 #include "gnunet_util_lib.h"
  42
  43 /**
  44  * Struct containing all information regarding a given peer
  45  */
  46 struct MeshPeer;
  47
  48 /**
  49  * Struct containing info about a queued transmission to this peer
  50  */
  51 struct MeshPeerQueue;
  52
  53 #include "gnunet-service-mesh_connection.h"
  54
  55 /**
  56  * Callback called when a queued message is sent.
  57  *
  58  * @param cls Closure.
  59  * @param c Connection this message was on.
  60  * @param sent Was it really sent? (Could have been canceled)
  61  * @param type Type of message sent.
  62  * @param fwd Was this a FWD going message?
  63  * @param size Size of the message.
  64  * @param wait Time spent waiting for core (only the time for THIS message)
  65  */
  66 typedef void (*GMP_sent) (void *cls,
  67                           struct MeshConnection *c, int sent,
  68                           uint16_t type, int fwd, size_t size,
  69                           struct GNUNET_TIME_Relative wait);
  70
  71 /******************************************************************************/
  72 /********************************    API    ***********************************/
  73 /******************************************************************************/
  74
  75 /**
  76  * Initialize peer subsystem.
  77  *
  78  * @param c Configuration.
  79  */
  80 void
  81 GMP_init (const struct GNUNET_CONFIGURATION_Handle *c);
  82
  83 /**
  84  * Shut down the peer subsystem.
  85  */
  86 void
  87 GMP_shutdown (void);
  88
  89
  90 /**
  91  * Retrieve the MeshPeer stucture associated with the peer, create one
  92  * and insert it in the appropriate structures if the peer is not known yet.
  93  *
  94  * @param peer_id Full identity of the peer.
  95  *
  96  * @return Existing or newly created peer structure.
  97  */
  98 struct MeshPeer *
  99 GMP_get (const struct GNUNET_PeerIdentity *peer_id);
 100
 101
 102 /**
 103  * Retrieve the MeshPeer stucture associated with the peer, create one
 104  * and insert it in the appropriate structures if the peer is not known yet.
 105  *
 106  * @param peer Short identity of the peer.
 107  *
 108  * @return Existing or newly created peer structure.
 109  */
 110 struct MeshPeer *
 111 GMP_get_short (const GNUNET_PEER_Id peer);
 112
 113 /**
 114  * Try to establish a new connection to this peer (in its tunnel).
 115  * If the peer doesn't have any path to it yet, try to get one.
 116  * If the peer already has some path, send a CREATE CONNECTION towards it.
 117  *
 118  * @param peer Peer to connect to.
 119  */
 120 void
 121 GMP_connect (struct MeshPeer *peer);
 122
 123 /**
 124  * Free a transmission that was already queued with all resources
 125  * associated to the request.
 126  *
 127  * @param queue Queue handler to cancel.
 128  * @param clear_cls Is it necessary to free associated cls?
 129  * @param sent Was it really sent? (Could have been canceled)
 130  */
 131 void
 132 GMP_queue_destroy (struct MeshPeerQueue *queue, int clear_cls, int sent);
 133
 134 /**
 135  * @brief Queue and pass message to core when possible.
 136  *
 137  * @param peer Peer towards which to queue the message.
 138  * @param cls Closure (@c type dependant). It will be used by queue_send to
 139  *            build the message to be sent if not already prebuilt.
 140  * @param type Type of the message, 0 for a raw message.
 141  * @param size Size of the message.
 142  * @param c Connection this message belongs to (cannot be NULL).
 143  * @param fwd Is this a message going root->dest? (FWD ACK are NOT FWD!)
 144  * @param cont Continuation to be called once CORE has taken the message.
 145  * @param cont_cls Closure for @c cont.
 146  *
 147  * @return Handle to cancel the message before it is sent. Once cont is called
 148  *         message has been sent and therefore the handle is no longer valid.
 149  */
 150 struct MeshPeerQueue *
 151 GMP_queue_add (struct MeshPeer *peer, void *cls, uint16_t type, size_t size,
 152                struct MeshConnection *c, int fwd,
 153                GMP_sent cont, void *cont_cls);
 154
 155 /**
 156  * Cancel all queued messages to a peer that belong to a certain connection.
 157  *
 158  * @param peer Peer towards whom to cancel.
 159  * @param c Connection whose queued messages to cancel. Might be destroyed by
 160  *          the sent continuation call.
 161  */
 162 void
 163 GMP_queue_cancel (struct MeshPeer *peer, struct MeshConnection *c);
 164
 165 /**
 166  * Get the first message for a connection and unqueue it.
 167  *
 168  * @param peer Neighboring peer.
 169  * @param c Connection.
 170  *
 171  * @return First message for this connection.
 172  */
 173 struct GNUNET_MessageHeader *
 174 GMP_connection_pop (struct MeshPeer *peer, struct MeshConnection *c);
 175
 176 void
 177 GMP_queue_unlock (struct MeshPeer *peer, struct MeshConnection *c);
 178
 179 /**
 180  * Set tunnel.
 181  *
 182  * @param peer Peer.
 183  * @param t Tunnel.
 184  */
 185 void
 186 GMP_set_tunnel (struct MeshPeer *peer, struct MeshTunnel3 *t);
 187
 188 /**
 189  * Check whether there is a direct (core level)  connection to peer.
 190  *
 191  * @param peer Peer to check.
 192  *
 193  * @return #GNUNET_YES if there is a direct connection.
 194  */
 195 int
 196 GMP_is_neighbor (const struct MeshPeer *peer);
 197
 198 /**
 199  * Create and initialize a new tunnel towards a peer, in case it has none.
 200  *
 201  * Does not generate any traffic, just creates the local data structures.
 202  *
 203  * @param peer Peer towards which to create the tunnel.
 204  */
 205 void
 206 GMP_add_tunnel (struct MeshPeer *peer);
 207
 208 /**
 209  * Add a connection to a neighboring peer.
 210  *
 211  * Store that the peer is the first hop of the connection in one
 212  * direction and that on peer disconnect the connection must be
 213  * notified and destroyed, for it will no longer be valid.
 214  *
 215  * @param peer Peer to add connection to.
 216  * @param c Connection to add.
 217  *
 218  * @return GNUNET_OK on success.
 219  */
 220 int
 221 GMP_add_connection (struct MeshPeer *peer, struct MeshConnection *c);
 222
 223 /**
 224  * Add the path to the peer and update the path used to reach it in case this
 225  * is the shortest.
 226  *
 227  * @param peer Destination peer to add the path to.
 228  * @param path New path to add. Last peer must be the peer in arg 1.
 229  *             Path will be either used of freed if already known.
 230  * @param trusted Do we trust that this path is real?
 231  *
 232  * @return path if path was taken, pointer to existing duplicate if exists
 233  *         NULL on error.
 234  */
 235 struct MeshPeerPath *
 236 GMP_add_path (struct MeshPeer *peer, struct MeshPeerPath *p, int trusted);
 237
 238 /**
 239  * Add the path to the origin peer and update the path used to reach it in case
 240  * this is the shortest.
 241  * The path is given in peer_info -> destination, therefore we turn the path
 242  * upside down first.
 243  *
 244  * @param peer Peer to add the path to, being the origin of the path.
 245  * @param path New path to add after being inversed.
 246  *             Path will be either used or freed.
 247  * @param trusted Do we trust that this path is real?
 248  *
 249  * @return path if path was taken, pointer to existing duplicate if exists
 250  *         NULL on error.
 251  */
 252 struct MeshPeerPath *
 253 GMP_add_path_to_origin (struct MeshPeer *peer,
 254                         struct MeshPeerPath *path,
 255                         int trusted);
 256
 257 /**
 258  * Adds a path to the info of all the peers in the path
 259  *
 260  * @param p Path to process.
 261  * @param confirmed Whether we know if the path works or not.
 262  */
 263 void
 264 GMP_add_path_to_all (const struct MeshPeerPath *p, int confirmed);
 265
 266 /**
 267  * Remove any path to the peer that has the extact same peers as the one given.
 268  *
 269  * @param peer Peer to remove the path from.
 270  * @param path Path to remove. Is always destroyed .
 271  */
 272 void
 273 GMP_remove_path (struct MeshPeer *peer, struct MeshPeerPath *path);
 274
 275 /**
 276  * Remove a connection from a neighboring peer.
 277  *
 278  * @param peer Peer to remove connection from.
 279  * @param c Connection to remove.
 280  *
 281  * @return GNUNET_OK on success.
 282  */
 283 int
 284 GMP_remove_connection (struct MeshPeer *peer, const struct MeshConnection *c);
 285
 286 /**
 287  * Start the DHT search for new paths towards the peer: we don't have
 288  * enough good connections.
 289  *
 290  * @param peer Destination peer.
 291  */
 292 void
 293 GMP_start_search (struct MeshPeer *peer);
 294
 295 /**
 296  * Stop the DHT search for new paths towards the peer: we already have
 297  * enough good connections.
 298  *
 299  * @param peer Destination peer.
 300  */
 301 void
 302 GMP_stop_search (struct MeshPeer *peer);
 303
 304 /**
 305  * Get the Full ID of a peer.
 306  *
 307  * @param peer Peer to get from.
 308  *
 309  * @return Full ID of peer.
 310  */
 311 const struct GNUNET_PeerIdentity *
 312 GMP_get_id (const struct MeshPeer *peer);
 313
 314 /**
 315  * Get the Short ID of a peer.
 316  *
 317  * @param peer Peer to get from.
 318  *
 319  * @return Short ID of peer.
 320  */
 321 GNUNET_PEER_Id
 322 GMP_get_short_id (const struct MeshPeer *peer);
 323
 324 /**
 325  * Get the tunnel towards a peer.
 326  *
 327  * @param peer Peer to get from.
 328  *
 329  * @return Tunnel towards peer.
 330  */
 331 struct MeshTunnel3 *
 332 GMP_get_tunnel (const struct MeshPeer *peer);
 333
 334 /**
 335  * Set the hello message.
 336  *
 337  * @param peer Peer whose message to set.
 338  * @param hello Hello message.
 339  */
 340 void
 341 GMP_set_hello (struct MeshPeer *peer, const struct GNUNET_HELLO_Message *hello);
 342
 343 /**
 344  * Get the hello message.
 345  *
 346  * @param peer Peer whose message to get.
 347  *
 348  * @return Hello message.
 349  */
 350 struct GNUNET_HELLO_Message *
 351 GMP_get_hello (struct MeshPeer *peer);
 352
 353
 354 /**
 355  * Try to connect to a peer on TRANSPORT level.
 356  *
 357  * @param peer Peer to whom to connect.
 358  */
 359 void
 360 GMP_try_connect (struct MeshPeer *peer);
 361
 362 /**
 363  * Notify a peer that a link between two other peers is broken. If any path
 364  * used that link, eliminate it.
 365  *
 366  * @param peer Peer affected by the change.
 367  * @param peer1 Peer whose link is broken.
 368  * @param peer2 Peer whose link is broken.
 369  */
 370 void
 371 GMP_notify_broken_link (struct MeshPeer *peer,
 372                         struct GNUNET_PeerIdentity *peer1,
 373                         struct GNUNET_PeerIdentity *peer2);
 374
 375 /**
 376  * Count the number of known paths toward the peer.
 377  *
 378  * @param peer Peer to get path info.
 379  *
 380  * @return Number of known paths.
 381  */
 382 unsigned int
 383 GMP_count_paths (const struct MeshPeer *peer);
 384
 385 /**
 386  * Iterate all known peers.
 387  *
 388  * @param iter Iterator.
 389  * @param cls Closure for @c iter.
 390  */
 391 void
 392 GMP_iterate_all (GNUNET_CONTAINER_PeerMapIterator iter, void *cls);
 393
 394 /**
 395  * Get the static string for a peer ID.
 396  *
 397  * @param peer Peer.
 398  *
 399  * @return Static string for it's ID.
 400  */
 401 const char *
 402 GMP_2s (const struct MeshPeer *peer);
 403
 404
 405 #if 0                           /* keep Emacsens' auto-indent happy */
 406 {
 407 #endif
 408 #ifdef __cplusplus
 409 }
 410 #endif
 411
 412 /* ifndef GNUNET_MESH_SERVICE_PEER_H */
 413 #endif
 414 /* end of gnunet-mesh-service_peer.h */