*/
#ifndef MESHLINK_H
+#define MESHLINK_H
#include <stdbool.h>
#include <stddef.h>
/// A handle for a MeshLink node.
typedef struct meshlink_node meshlink_node_t;
+/// Code of most recent error encountered.
+typedef enum {
+ MESHLINK_OK, // Everything is fine
+ MESHLINK_ENOMEM, // Out of memory
+ MESHLINK_ENOENT, // Node is not known
+} meshlink_errno_t;
+
+#ifndef MESHLINK_INTERNAL_H
+
+struct meshlink_handle {
+ meshlink_errno_t errno; /// Code of the last encountered error.
+ const char *errstr; /// Textual representation of most recent error encountered.
+};
+
+struct meshlink_node {
+ const char *name; // Textual name of this node.
+ void *priv; // Private pointer which the application can set at will.
+};
+
+#endif // MESHLINK_INTERNAL_H
+
+/// Get the text for the given MeshLink error code.
+/** This function returns a pointer to the string containing the description of the given error code.
+ *
+ * @param errno An error code returned by MeshLink.
+ *
+ * @return A pointer to a string containing the description of the error code.
+ */
+extern const char *meshlink_strerror(meshlink_errno_t errno);
+
/// Initialize MeshLink's configuration directory.
/** This function causes MeshLink to initialize its configuration directory,
* if it hasn't already been initialized.
*
* @param confbase The directory in which MeshLink will store its configuration files.
* @param name The name which this instance of the application will use in the mesh.
+ *
* @return This function will return true if MeshLink has succesfully set up its configuration files, false otherwise.
*/
-extern bool meshlink_setup(const char *confbase, const char *name);
+extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name);
/// Start MeshLink.
/** This function causes MeshLink to create a new thread, which will
* handle all network I/O.
*
* @param confbase The directory in which MeshLink will store its configuration files.
- * @return A handle which represents this instance of MeshLink,
- * or NULL in case of an error.
+ *
+ * @return This function will return true if MeshLink has succesfully started its thread, false otherwise.
*/
-extern meshlink_handle_t *meshlink_start(const char *confbase);
+extern bool meshlink_start(meshlink_handle_t *handle);
/// Stop MeshLink.
/** This function causes MeshLink to disconnect from all other nodes,
- * and shuts down its own thread. Afterwards, the handle and any
- * pointers to a struct meshlink_node are invalid.
+ * and shuts down its own thread.
+ *
+ * @param handle A handle which represents an instance of MeshLink.
+ */
+extern void meshlink_stop(meshlink_handle_t *handle);
+
+/// Close the MeshLink handle.
+/** This function calls meshlink_stop() if necessary,
+ * and frees all memory allocated by MeshLink.
+ * Afterwards, the handle and any pointers to a struct meshlink_node are invalid.
*
* @param handle A handle which represents an instance of MeshLink.
*/
-extern void meshlink_stop(meshlink_handle *handle);
+extern void meshlink_close(meshlink_handle_t *handle);
/// A callback for receiving data from the mesh.
/** @param handle A handle which represents an instance of MeshLink.
*/
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
projects / meshlink / blobdiff