- 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 df044ad144d3677eff862697aa06189196fa6e7b..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"
 
 /**
@@ -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,14 +138,16 @@ 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);
 
 /**
@@ -160,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);
@@ -194,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);
 
 /**
@@ -212,8 +232,11 @@ GMP_add_path (struct MeshPeer *peer, struct MeshPeerPath *p, int trusted);
  * @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
+struct MeshPeerPath *
 GMP_add_path_to_origin (struct MeshPeer *peer,
                         struct MeshPeerPath *path,
                         int trusted);