From: Guus Sliepen <guus@meshlink.io>
Date: Sat, 19 Apr 2014 14:24:48 +0000 (+0200)
Subject: Update the chat example and the public API.
X-Git-Url: http://git.meshlink.io/?p=meshlink;a=commitdiff_plain;h=86eb0cd8327f67354d4265467c1e0796af65b40c

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 84e3dadb..36ffd6b1 100644
--- 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 ca78afd0..42435849 100644
--- 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