/*
meshlink.h -- MeshLink API
- Copyright (C) 2014-2019 Guus Sliepen <guus@meshlink.io>
+ Copyright (C) 2014-2021 Guus Sliepen <guus@meshlink.io>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
typedef enum {
MESHLINK_STORAGE_ENABLED, ///< Store all updates.
MESHLINK_STORAGE_DISABLED, ///< Don't store any updates.
- MESHLINK_STORAGE_KEYS_ONLY, ///< Only store updates when a node's key has changed.
+ MESHLINK_STORAGE_KEYS_ONLY ///< Only store updates when a node's key has changed.
} meshlink_storage_policy_t;
/// Invitation flags
*/
bool meshlink_open_params_set_storage_policy(meshlink_open_params_t *params, meshlink_storage_policy_t policy) __attribute__((__warn_unused_result__));
+/// Set the filename of the lockfile.
+/** This function changes the path of the lockfile used to ensure only one instance of MeshLink can be open at the same time.
+ * If an application changes this, it must always set it to the same location.
+ *
+ * @param params A pointer to a meshlink_open_params_t which must have been created earlier with meshlink_open_params_init().
+ * @param filename The filename of the lockfile.
+ *
+ * @return This function will return true if the open parameters have been successfully updated, false otherwise.
+ */
+bool meshlink_open_params_set_lock_filename(meshlink_open_params_t *params, const char *filename) __attribute__((__warn_unused_result__));
+
/// Open or create a MeshLink instance.
/** This function opens or creates a MeshLink instance.
* All parameters needed by MeshLink are passed via a meshlink_open_params_t struct,
*/
bool meshlink_destroy(const char *confbase) __attribute__((__warn_unused_result__));
+/// Destroy a MeshLink instance using open parameters.
+/** This function remove all configuration files of a MeshLink instance. It should only be called when the application
+ * does not have an open handle to this instance. Afterwards, a call to meshlink_open() will create a completely
+ * new instance.
+ *
+ * This version expects a pointer to meshlink_open_params_t,
+ * and will use exactly the same settings used for opening a handle to destroy it.
+ *
+ * @param params A pointer to a meshlink_open_params_t which must be filled in by the application.
+ * After the function returns, the application is free to reuse or free @a params.
+ *
+ * @return This function will return true if the MeshLink instance was successfully destroyed, false otherwise.
+ */
+bool meshlink_destroy_ex(const meshlink_open_params_t *params) __attribute__((__warn_unused_result__));
+
/// A callback for receiving data from the mesh.
/** @param mesh A handle which represents an instance of MeshLink.
* @param source A pointer to a struct meshlink_node describing the source of the data.
*/
void meshlink_set_blacklisted_cb(struct meshlink_handle *mesh, meshlink_blacklisted_cb_t cb);
+/// A callback notifying when the MeshLink thread starts and stops.
+/* @param mesh A handle which represents an instance of MeshLink, or NULL.
+ * @param started True if the MeshLink thread has started, false if it is about to stop.
+ */
+typedef void (*meshlink_thread_status_cb_t)(struct meshlink_handle *mesh, bool started);
+
+/// Set the thread status callback.
+/** This functions sets the callback that is called whenever the MeshLink thread has started or is about to stop.
+ *
+ * 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.
+ *
+ * \memberof meshlink_handle
+ * @param mesh A handle which represents an instance of MeshLink, or NULL.
+ * @param cb A pointer to the function which will be called when a serious error is encountered.
+ * If a NULL pointer is given, the callback will be disabled.
+ */
+void meshlink_set_thread_status_cb(struct meshlink_handle *mesh, meshlink_thread_status_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
*/
dev_class_t meshlink_get_node_dev_class(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
+/// Get the node's tiny status.
+/** This function returns true if the given node is a tiny node.
+ * Note that the tiny status of a node will only be known if the node has been reachable at least once.
+ *
+ * \memberof meshlink_node
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param node A pointer to a struct meshlink_node describing the node.
+ *
+ * @return This function returns true if the node is a tiny node.
+ */
+bool meshlink_get_node_tiny(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
+
/// Get the node's blacklist status.
/** This function returns the given node is blacklisted.
*
/// Close a reliable stream channel.
/** This informs the remote node that the local node has finished sending all data on the channel.
* It also causes the local node to stop accepting incoming data from the remote node.
- * It will free the struct meshlink_channel and all associated resources.
* Afterwards, the channel handle is invalid and must not be used any more.
*
* It is allowed to call this function at any time on a valid handle, even inside callback functions.
*/
void meshlink_channel_close(struct meshlink_handle *mesh, struct meshlink_channel *channel);
+/// Abort a reliable stream channel.
+/** This aborts a channel.
+ * Data that was in the send and receive buffers is dropped, so potentially there is some data that
+ * was sent on this channel that will not be received by the peer.
+ * Afterwards, the channel handle is invalid and must not be used any more.
+ *
+ * It is allowed to call this function at any time on a valid handle, even inside callback functions.
+ * If called with a valid handle, this function always succeeds, otherwise the result is undefined.
+ *
+ * \memberof meshlink_channel
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param channel A handle for the channel.
+ */
+void meshlink_channel_abort(struct meshlink_handle *mesh, struct meshlink_channel *channel);
+
/// Transmit data on a channel
/** This queues data to send to the remote node.
*
*/
void meshlink_enable_discovery(struct meshlink_handle *mesh, bool enable);
+/// Inform MeshLink that the local network configuration might have changed
+/** This is intended to be used when there is no way for MeshLink to get notifications of local network changes.
+ * It forces MeshLink to scan all network interfaces for changes in up/down status and new/removed addresses,
+ * and will immediately check if all connections to other nodes are still alive.
+ *
+ * \memberof meshlink_handle
+ * @param mesh A handle which represents an instance of MeshLink.
+ */
+void meshlink_hint_network_change(struct meshlink_handle *mesh);
+
/// Performs key rotation for an encrypted storage
/** This rotates the (master) key for an encrypted storage and discards the old key
* if the call succeeded. This is an atomic call.
projects / meshlink / blobdiff