Never automatically try to bind to ports >= 32768.

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index cc18bec037841b54bcc253c0ce0c873749c98595..903bab36db1d1481035667b11ac90f046169a104 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -87,7 +87,7 @@ typedef enum {
 typedef enum {
        MESHLINK_STORAGE_ENABLED,    ///< Store all updates.
        MESHLINK_STORAGE_DISABLED,   ///< Don't store any updates.
-       MESHLINK_STORAGE_KEYS_ONLY,  ///< Only store updates when a node's key has changed.
+       MESHLINK_STORAGE_KEYS_ONLY   ///< Only store updates when a node's key has changed.
 } meshlink_storage_policy_t;
 
 /// Invitation flags
@@ -611,6 +611,27 @@ typedef void (*meshlink_blacklisted_cb_t)(struct meshlink_handle *mesh, struct m
  */
 void meshlink_set_blacklisted_cb(struct meshlink_handle *mesh, meshlink_blacklisted_cb_t cb);
 
+/// A callback notifying when the MeshLink thread starts and stops.
+/*  @param mesh      A handle which represents an instance of MeshLink, or NULL.
+ *  @param started   True if the MeshLink thread has started, false if it is about to stop.
+ */
+typedef void (*meshlink_thread_status_cb_t)(struct meshlink_handle *mesh, bool started);
+
+/// Set the thread status callback.
+/** This functions sets the callback that is called whenever the MeshLink thread has started or is about to stop.
+ *
+ *  The callback is run in MeshLink's own thread.
+ *  It is important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
+ *  to hand the data over to the application's thread.
+ *  The callback should also not block itself and return as quickly as possible.
+ *
+ *  \memberof meshlink_handle
+ *  @param mesh      A handle which represents an instance of MeshLink, or NULL.
+ *  @param cb        A pointer to the function which will be called when a serious error is encountered.
+ *                   If a NULL pointer is given, the callback will be disabled.
+ */
+void meshlink_set_thread_status_cb(struct meshlink_handle *mesh, meshlink_thread_status_cb_t cb);
+
 /// Send data to another node.
 /** This functions sends one packet of data to another node in the mesh.
  *  The packet is sent using UDP semantics, which means that
@@ -835,6 +856,18 @@ struct meshlink_node **meshlink_get_all_nodes_by_blacklisted(struct meshlink_han
  */
 dev_class_t meshlink_get_node_dev_class(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
 
+/// Get the node's tiny status.
+/** This function returns true if the given node is a tiny node.
+ *  Note that the tiny status of a node will only be known if the node has been reachable at least once.
+ *
+ *  \memberof meshlink_node
+ *  @param mesh          A handle which represents an instance of MeshLink.
+ *  @param node          A pointer to a struct meshlink_node describing the node.
+ *
+ *  @return              This function returns true if the node is a tiny node.
+ */
+bool meshlink_get_node_tiny(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
+
 /// Get the node's blacklist status.
 /** This function returns the given node is blacklisted.
  *
@@ -1531,7 +1564,6 @@ void meshlink_channel_shutdown(struct meshlink_handle *mesh, struct meshlink_cha
 /// Close a reliable stream channel.
 /** This informs the remote node that the local node has finished sending all data on the channel.
  *  It also causes the local node to stop accepting incoming data from the remote node.
- *  It will free the struct meshlink_channel and all associated resources.
  *  Afterwards, the channel handle is invalid and must not be used any more.
  *
  *  It is allowed to call this function at any time on a valid handle, even inside callback functions.
@@ -1543,6 +1575,21 @@ void meshlink_channel_shutdown(struct meshlink_handle *mesh, struct meshlink_cha
  */
 void meshlink_channel_close(struct meshlink_handle *mesh, struct meshlink_channel *channel);
 
+/// Abort a reliable stream channel.
+/** This aborts a channel.
+ *  Data that was in the send and receive buffers is dropped, so potentially there is some data that
+ *  was sent on this channel that will not be received by the peer.
+ *  Afterwards, the channel handle is invalid and must not be used any more.
+ *
+ *  It is allowed to call this function at any time on a valid handle, even inside callback functions.
+ *  If called with a valid handle, this function always succeeds, otherwise the result is undefined.
+ *
+ *  \memberof meshlink_channel
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *  @param channel      A handle for the channel.
+ */
+void meshlink_channel_abort(struct meshlink_handle *mesh, struct meshlink_channel *channel);
+
 /// Transmit data on a channel
 /** This queues data to send to the remote node.
  *