Update the chat example and the public API.

In particular, add a callback for notifying the application of node status
changes, and one for passing log messages.

diff --git a/examples/chat.c b/examples/chat.c
index 84e3dadb6930ffc128ed6254739298b0f691102a..36ffd6b1cc2d92703de850be483ce8e285d06a1c 100644 (file)
--- a/examples/chat.c
+++ b/examples/chat.c
@@ -3,6 +3,11 @@
 #include <string.h>
 #include "../src/meshlink.h"
 
+static void log(meshlink_handle_t *mesh, meshlink_log_level_t level, const char *text) {
+       const char *levelstr[] = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"};
+       fprintf(stderr, "%s: %s\n", levelstr[level], text);
+}
+
 static void receive(meshlink_handle_t *mesh, meshlink_node_t *source, const char *data, size_t len) {
        if(!len || data[len - 1]) {
                fprintf(stderr, "Received invalid data from %s\n", source->name);
@@ -142,14 +147,15 @@ int main(int argc, char *argv[]) {
        if(argc > 2)
                nick = argv[2];
 
-       mesh = meshlink_open(confbase, nick);
+       meshlink_handle_t *mesh = meshlink_open(confbase, nick);
        if(!mesh) {
                fprintf(stderr, "Could not open MeshLink: %s\n", meshlink_errstr);
                return 1;
        }
 
-       meshlink_set_receive_cb(receive);
-       meshlink_set_node_status_cb(node_changed);
+       meshlink_set_receive_cb(mesh, receive);
+       meshlink_set_node_status_cb(mesh, node_changed);
+       meshlink_set_log_cb(mesh, MESHLINK_INFO, log);
 
        if(!meshlink_start(mesh)) {
                fprintf(stderr, "Could not start MeshLink: %s\n", meshlink_errstr);

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