From 86eb0cd8327f67354d4265467c1e0796af65b40c Mon Sep 17 00:00:00 2001 From: Guus Sliepen Date: Sat, 19 Apr 2014 16:24:48 +0200 Subject: [PATCH] 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. --- examples/chat.c | 12 +++++++--- src/meshlink.h | 58 ++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 64 insertions(+), 6 deletions(-) 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 #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 #include -#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 -- 2.39.5