Update the chat example and the public API.

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index ca78afd082cc17bf53f7d2e3be347c3285ff7ab4..424358492bff674708aee847d2e6dd1d7982a2f1 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -18,18 +18,22 @@
 */
 
 #ifndef MESHLINK_H
+#define MESHLINK_H
 
 #include <stdbool.h>
 #include <stddef.h>
 
-#ifndef MESHLINK_INTERNAL_H
-
 /// A handle for an instance of MeshLink.
 typedef struct meshlink_handle meshlink_handle_t;
 
+typedef struct meshlink_node meshlink_node_t;
+
+#ifndef MESHLINK_INTERNAL_H
+
 /// A handle for a MeshLink node.
 typedef struct meshlink_node {
-       const char *name;
+       const char *name; // Textual name of this node.
+       void *priv;       // Private pointer which the application can set at will.
 } meshlink_node_t;
 
 #endif // MESHLINK_INTERNAL_H
@@ -116,6 +120,54 @@ typedef void (*meshlink_receive_cb_t)(meshlink_handle_t *handle, meshlink_node_t
  */
 void meshlink_set_receive_cb(meshlink_handle_t *handle, meshlink_receive_cb_t cb);
 
+/// A callback reporting node status changes.
+/** @param handle     A handle which represents an instance of MeshLink.
+ *  @param node       A pointer to a meshlink_node_t describing the node whose status changed.
+ *  @param reachable  True if the node is reachable, false otherwise.
+ */
+typedef void (*meshlink_node_status_cb_t)(meshlink_handle_t *handle, meshlink_node_t *node, bool reachable);
+
+/// Set the node status callback.
+/** This functions sets the callback that is called whenever another node's status changed.
+ *  The callback is run in MeshLink's own thread.
+ *  It is therefore 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.
+ *
+ *  @param handle    A handle which represents an instance of MeshLink.
+ *  @param cb        A pointer to the function which will be called when another node's status changes.
+ */
+void meshlink_set_node_status_cb(meshlink_handle_t *handle, meshlink_node_status_cb_t cb);
+
+/// Severity of log messages generated by MeshLink.
+typedef enum {
+       MESHLINK_DEBUG,    // Internal debugging messages. Only useful during application development.
+       MESHLINK_INFO,     // Informational messages.
+       MESHLINK_WARNING,  // Warnings which might indicate problems, but which are not real errors.
+       MESHLINK_ERROR,    // Errors which hamper correct functioning of MeshLink, without causing it to fail completely.
+       MESHLINK_CRITICAL, // Critical errors which cause MeshLink to fail completely.
+} meshlink_log_level_t;
+
+/// A callback for receiving log messages generated by MeshLink.
+/** @param handle    A handle which represents an instance of MeshLink.
+ *  @param level     An enum describing the severity level of the message.
+ *  @param text      A pointer to a string containing the textual log message.
+ */
+typedef void (*meshlink_log_cb_t)(meshlink_handle_t *handle, meshlink_log_level_t level, const char *text);
+
+/// Set the log callback.
+/** This functions sets the callback that is called whenever MeshLink has some information to log.
+ *  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.
+ *
+ *  @param handle    A handle which represents an instance of MeshLink.
+ *  @param level     An enum describing the minimum severity level. Debugging information with a lower level will not trigger the callback.
+ *  @param cb        A pointer to the function which will be called when another node sends data to the local node.
+ */
+void meshlink_set_log_cb(meshlink_handle_t *handle, meshlink_log_level_t level, meshlink_receive_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