X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=3d12af6b87b40e4679b426a2015ab1fc1567622f;hb=91501d27480bf37881b6872cf63462c50de197f3;hp=da5cc131e33b8d3917b3cc4d4dd52464b304f489;hpb=a7faa4515301e976d0fa87bdd096f12696ba8fce;p=meshlink

diff --git a/src/meshlink.h b/src/meshlink.h
index da5cc131..3d12af6b 100644
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -59,18 +59,19 @@ typedef struct meshlink_submesh meshlink_submesh_t;
 
 /// Code of most recent error encountered.
 typedef enum {
-	MESHLINK_OK,        ///< Everything is fine
-	MESHLINK_EINVAL,    ///< Invalid parameter(s) to function call
-	MESHLINK_ENOMEM,    ///< Out of memory
-	MESHLINK_ENOENT,    ///< Node is not known
-	MESHLINK_EEXIST,    ///< Node already exists
-	MESHLINK_EINTERNAL, ///< MeshLink internal error
-	MESHLINK_ERESOLV,   ///< MeshLink could not resolve a hostname
-	MESHLINK_ESTORAGE,  ///< MeshLink could not load or write data from/to disk
-	MESHLINK_ENETWORK,  ///< MeshLink encountered a network error
-	MESHLINK_EPEER,     ///< A peer caused an error
-	MESHLINK_ENOTSUP,   ///< The operation is not supported in the current configuration of MeshLink
-	MESHLINK_EBUSY      ///< The MeshLink instance is already in use by another process
+	MESHLINK_OK,           ///< Everything is fine
+	MESHLINK_EINVAL,       ///< Invalid parameter(s) to function call
+	MESHLINK_ENOMEM,       ///< Out of memory
+	MESHLINK_ENOENT,       ///< Node is not known
+	MESHLINK_EEXIST,       ///< Node already exists
+	MESHLINK_EINTERNAL,    ///< MeshLink internal error
+	MESHLINK_ERESOLV,      ///< MeshLink could not resolve a hostname
+	MESHLINK_ESTORAGE,     ///< MeshLink could not load or write data from/to disk
+	MESHLINK_ENETWORK,     ///< MeshLink encountered a network error
+	MESHLINK_EPEER,        ///< A peer caused an error
+	MESHLINK_ENOTSUP,      ///< The operation is not supported in the current configuration of MeshLink
+	MESHLINK_EBUSY,        ///< The MeshLink instance is already in use by another process
+	MESHLINK_EBLACKLISTED, ///< The operation is not allowed because the node is blacklisted
 } meshlink_errno_t;
 
 /// Device class
@@ -511,6 +512,38 @@ typedef void (*meshlink_log_cb_t)(struct meshlink_handle *mesh, meshlink_log_lev
  */
 extern void meshlink_set_log_cb(struct meshlink_handle *mesh, meshlink_log_level_t level, meshlink_log_cb_t cb);
 
+/// A callback for receiving error conditions encountered by the MeshLink thread.
+/** @param mesh      A handle which represents an instance of MeshLink, or NULL.
+ *  @param errno     The error code describing what kind of error occured.
+ */
+typedef void (*meshlink_error_cb_t)(struct meshlink_handle *mesh, meshlink_errno_t meshlink_errno);
+
+/// Set the error callback.
+/** This functions sets the callback that is called whenever the MeshLink thread encounters a serious error.
+ *
+ *  While most API functions report an error directly to the caller in case something went wrong,
+ *  MeshLink also runs a background thread which can encounter error conditions.
+ *  Most of them will be dealt with automatically, however there can be errors that will prevent MeshLink from
+ *  working correctly. When the callback is called, it means that MeshLink is no longer functioning
+ *  as expected. The application should then present an error message and shut down, or perform any other
+ *  action it deems appropriate.
+ *
+ *  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.
+ *
+ *  Even though the callback signals a serious error inside MeshLink, all open handles are still valid,
+ *  and the application should close handles in exactly the same it would have to do if the callback
+ *  was not called. This must not be done inside the callback itself.
+ *
+ *  \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.
+ */
+extern void meshlink_set_error_cb(struct meshlink_handle *mesh, meshlink_error_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
@@ -1139,6 +1172,7 @@ extern void meshlink_set_channel_rcvbuf(struct meshlink_handle *mesh, struct mes
  *                      The pointer may be NULL, in which case incoming data is ignored.
  *  @param data         A pointer to a buffer containing data to already queue for sending, or NULL if there is no data to send.
  *                      After meshlink_send() returns, the application is free to overwrite or free this buffer.
+ *                      If len is 0, the data pointer is copied into the channel's priv member.
  *  @param len          The length of the data, or 0 if there is no data to send.
  *  @param flags        A bitwise-or'd combination of flags that set the semantics for this channel.
  *
@@ -1167,6 +1201,7 @@ extern struct meshlink_channel *meshlink_channel_open_ex(struct meshlink_handle
  *  @param data         A pointer to a buffer containing data to already queue for sending, or NULL if there is no data to send.
  *                      After meshlink_send() returns, the application is free to overwrite or free this buffer.
  *  @param len          The length of the data, or 0 if there is no data to send.
+ *                      If len is 0, the data pointer is copied into the channel's priv member.
  *
  *  @return             A handle for the channel, or NULL in case of an error.
  *                      The handle is valid until meshlink_channel_close() is called.
@@ -1348,6 +1383,18 @@ extern size_t meshlink_channel_get_sendq(struct meshlink_handle *mesh, struct me
  */
 extern size_t meshlink_channel_get_recvq(struct meshlink_handle *mesh, struct meshlink_channel *channel);
 
+/// Set the connection timeout used for channels to the given node.
+/** This sets the timeout after which unresponsive channels will be reported as closed.
+ *  The timeout is set for all current and future channels to the given node.
+ *
+ *  \memberof meshlink_node
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *  @param channel      A handle for the channel.
+ *  @param timeout      The timeout in seconds after which unresponsive channels will be reported as closed.
+ *                      The default is 60 seconds.
+ */
+extern void meshlink_set_node_channel_timeout(struct meshlink_handle *mesh, struct meshlink_node *node, int timeout);
+
 /// Hint that a hostname may be found at an address
 /** This function indicates to meshlink that the given hostname is likely found
  *  at the given IP address and port.