X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=75c4932715b6e23eaed4f373cc0b6e0c6c8dfb86;hb=ccab719af183f8d28fd3380f03b0ec5f494d55ae;hp=17545ed289b4c464dadc9e0ba53ca7108a74348b;hpb=ed545c8ca7b674b5e851567f2b6630ed3e4bfac0;p=meshlink

diff --git a/src/meshlink.h b/src/meshlink.h
index 17545ed2..75c49327 100644
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -180,6 +180,7 @@ extern bool meshlink_start(meshlink_handle_t *mesh);
  *  close all sockets, and shut down its own thread.
  *
  *  This function always succeeds. It is allowed to call meshlink_stop() even if MeshLink is already stopped or has never been started.
+ *  Channels that are still open will remain valid, but any communication via channels will stop as well.
  *
  *  @param mesh     A handle which represents an instance of MeshLink.
  */
@@ -187,7 +188,7 @@ extern void meshlink_stop(meshlink_handle_t *mesh);
 
 /// Close the MeshLink handle.
 /** This function calls meshlink_stop() if necessary,
- *  and frees the struct meshlink_handle and all associacted memory allocated by MeshLink.
+ *  and frees the struct meshlink_handle and all associacted memory allocated by MeshLink, including all channels.
  *  Afterwards, the handle and any pointers to a struct meshlink_node or struct meshlink_channel are invalid.
  *
  *  It is allowed to call this function at any time on a valid handle, except inside callback functions.
@@ -478,9 +479,21 @@ extern void meshlink_blacklist(meshlink_handle_t *mesh, meshlink_node_t *node);
  *  and will send data to it and accept any data received from it.
  *
  *  @param mesh         A handle which represents an instance of MeshLink.
- *  @param node         A pointer to a meshlink_node_t describing the node to be blacklisted.
+ *  @param node         A pointer to a meshlink_node_t describing the node to be whitelisted.
  */
-extern void meshlink_blacklist(meshlink_handle_t *mesh, meshlink_node_t *node);
+extern void meshlink_whitelist(meshlink_handle_t *mesh, meshlink_node_t *node);
+
+/// Set whether new nodes are blacklisted by default.
+/** This function sets the blacklist behaviour for newly discovered nodes.
+ *  If set to true, new nodes will be automatically blacklisted.
+ *  If set to false, which is the default, new nodes are automatically whitelisted.
+ *  The whitelist/blacklist status of a node may be changed afterwards with the
+ *  meshlink_whitelist() and meshlink_blacklist() functions.
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *  @param blacklist    True if new nodes are to be blacklisted, false if whitelisted.
+ */
+extern void meshlink_set_default_blacklist(meshlink_handle_t *mesh, bool blacklist);
 
 /// A callback for accepting incoming channels.
 /** This function is called whenever a remote node wants to open a channel to the local node.
@@ -524,6 +537,15 @@ typedef bool (*meshlink_channel_accept_cb_t)(meshlink_handle_t *mesh, meshlink_c
  */
 typedef void (*meshlink_channel_receive_cb_t)(meshlink_handle_t *mesh, meshlink_channel_t *channel, const void *data, size_t len);
 
+/// A callback informing the application when data can be sent on a channel.
+/** This function is called whenever there is enough free buffer space so a call to meshlink_channel_send() will succeed.
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *  @param channel      A handle for the channel.
+ *  @param len          The maximum amount of data that is guaranteed to be accepted by meshlink_channel_send().
+ */
+typedef void (*meshlink_channel_poll_cb_t)(meshlink_handle_t *mesh, meshlink_channel_t *channel, size_t len);
+
 /// Set the accept callback.
 /** This functions sets the callback that is called whenever another node sends data to the local node.
  *  The callback is run in MeshLink's own thread.
@@ -553,6 +575,20 @@ extern void meshlink_set_channel_accept_cb(meshlink_handle_t *mesh, meshlink_cha
  */
 extern void meshlink_set_channel_receive_cb(meshlink_handle_t *mesh, meshlink_channel_t *channel, meshlink_channel_receive_cb_t cb);
 
+/// Set the poll callback.
+/** This functions sets the callback that is called whenever data can be sent to another node.
+ *  The callback is run in MeshLink's own thread.
+ *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
+ *  to pass data to or from the application's thread.
+ *  The callback should also not block itself and return as quickly as possible.
+ *
+ *  @param mesh      A handle which represents an instance of MeshLink.
+ *  @param channel   A handle for the channel.
+ *  @param cb        A pointer to the function which will be called when data can be sent to another node.
+ *                   If a NULL pointer is given, the callback will be disabled.
+ */
+extern void meshlink_set_channel_poll_cb(meshlink_handle_t *mesh, meshlink_channel_t *channel, meshlink_channel_poll_cb_t cb);
+
 /// Open a reliable stream channel to another node.
 /** This function is called whenever a remote node wants to open a channel to the local node.
  *  The application then has to decide whether to accept or reject this channel.