- add underlay api implementation

[oweals/gnunet.git] / src / mesh / gnunet-service-mesh_peer.h

diff --git a/src/mesh/gnunet-service-mesh_peer.h b/src/mesh/gnunet-service-mesh_peer.h
index 57eb1c61d9e930cfb953f1c7b7aad65e7b64d5f6..58386c0aa0f71502a6aecab286883dde60f9be13 100644 (file)
--- a/src/mesh/gnunet-service-mesh_peer.h
+++ b/src/mesh/gnunet-service-mesh_peer.h
@@ -45,6 +45,11 @@ extern "C"
  */
 struct MeshPeer;
 
+/**
+ * Struct containing info about a queued transmission to this peer
+ */
+struct MeshPeerQueue;
+
 #include "gnunet-service-mesh_connection.h"
 
 /**
@@ -85,7 +90,7 @@ GMP_shutdown (void);
  * Retrieve the MeshPeer stucture associated with the peer, create one
  * and insert it in the appropriate structures if the peer is not known yet.
  *
- * @param peer Full identity of the peer.
+ * @param peer_id Full identity of the peer.
  *
  * @return Existing or newly created peer structure.
  */
@@ -114,6 +119,16 @@ GMP_get_short (const GNUNET_PEER_Id peer);
 void
 GMP_connect (struct MeshPeer *peer);
 
+/**
+ * Free a transmission that was already queued with all resources
+ * associated to the request.
+ *
+ * @param queue Queue handler to cancel.
+ * @param clear_cls Is it necessary to free associated cls?
+ */
+void
+GMP_queue_destroy (struct MeshPeerQueue *queue, int clear_cls);
+
 /**
  * @brief Queue and pass message to core when possible.
  *
@@ -123,21 +138,24 @@ GMP_connect (struct MeshPeer *peer);
  * @param type Type of the message, 0 for a raw message.
  * @param size Size of the message.
  * @param c Connection this message belongs to (cannot be NULL).
- * @param ch Channel this message belongs to, if applicable (otherwise NULL).
  * @param fwd Is this a message going root->dest? (FWD ACK are NOT FWD!)
  * @param cont Continuation to be called once CORE has taken the message.
  * @param cont_cls Closure for @c cont.
+ *
+ * @return Handle to cancel the message before it is sent. Once cont is called
+ *         message has been sent and therefore the handle is no longer valid.
  */
-void
+struct MeshPeerQueue *
 GMP_queue_add (struct MeshPeer *peer, void *cls, uint16_t type, size_t size,
-               struct MeshConnection *c, struct MeshChannel *ch, int fwd,
+               struct MeshConnection *c, int fwd,
                GMP_sent cont, void *cont_cls);
 
 /**
  * Cancel all queued messages to a peer that belong to a certain connection.
  *
  * @param peer Peer towards whom to cancel.
- * @param c Connection whose queued messages to cancel.
+ * @param c Connection whose queued messages to cancel. Might be destroyed by
+ *          the sent continuation call.
  */
 void
 GMP_queue_cancel (struct MeshPeer *peer, struct MeshConnection *c);
@@ -159,7 +177,7 @@ GMP_set_tunnel (struct MeshPeer *peer, struct MeshTunnel3 *t);
  *
  * @param peer Peer to check.
  *
- * @return GNUNET_YES if there is a direct connection.
+ * @return #GNUNET_YES if there is a direct connection.
  */
 int
 GMP_is_neighbor (const struct MeshPeer *peer);
@@ -193,12 +211,15 @@ GMP_add_connection (struct MeshPeer *peer, struct MeshConnection *c);
  * Add the path to the peer and update the path used to reach it in case this
  * is the shortest.
  *
- * @param peer_info Destination peer to add the path to.
+ * @param peer Destination peer to add the path to.
  * @param path New path to add. Last peer must be the peer in arg 1.
  *             Path will be either used of freed if already known.
  * @param trusted Do we trust that this path is real?
+ *
+ * @return path if path was taken, pointer to existing duplicate if exists
+ *         NULL on error.
  */
-void
+struct MeshPeerPath *
 GMP_add_path (struct MeshPeer *peer, struct MeshPeerPath *p, int trusted);
 
 /**
@@ -207,13 +228,16 @@ GMP_add_path (struct MeshPeer *peer, struct MeshPeerPath *p, int trusted);
  * The path is given in peer_info -> destination, therefore we turn the path
  * upside down first.
  *
- * @param peer_info Peer to add the path to, being the origin of the path.
+ * @param peer Peer to add the path to, being the origin of the path.
  * @param path New path to add after being inversed.
  *             Path will be either used or freed.
  * @param trusted Do we trust that this path is real?
+ *
+ * @return path if path was taken, pointer to existing duplicate if exists
+ *         NULL on error.
  */
-void
-GMP_add_path_to_origin (struct MeshPeer *peer_info,
+struct MeshPeerPath *
+GMP_add_path_to_origin (struct MeshPeer *peer,
                         struct MeshPeerPath *path,
                         int trusted);
 
@@ -237,9 +261,21 @@ GMP_add_path_to_all (const struct MeshPeerPath *p, int confirmed);
 int
 GMP_remove_connection (struct MeshPeer *peer, const struct MeshConnection *c);
 
+/**
+ * Start the DHT search for new paths towards the peer: we don't have
+ * enough good connections.
+ *
+ * @param peer Destination peer.
+ */
 void
 GMP_start_search (struct MeshPeer *peer);
 
+/**
+ * Stop the DHT search for new paths towards the peer: we already have
+ * enough good connections.
+ *
+ * @param peer Destination peer.
+ */
 void
 GMP_stop_search (struct MeshPeer *peer);
 
@@ -263,6 +299,16 @@ GMP_get_id (const struct MeshPeer *peer);
 GNUNET_PEER_Id
 GMP_get_short_id (const struct MeshPeer *peer);
 
+/**
+ * Get the tunnel towards a peer.
+ *
+ * @param peer Peer to get from.
+ *
+ * @return Tunnel towards peer.
+ */
+struct MeshTunnel3 *
+GMP_get_tunnel (const struct MeshPeer *peer);
+
 /**
  * Get the static string for a peer ID.
  *