X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=e0164b7fd7e8bae111743d65484c21d35a40790b;hb=HEAD;hp=3be94710309da0a13c36b231578456156279b8fc;hpb=afea9096fa708b2a2e6e24c308c0f1a80eefa5cc;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index 3be94710..903bab36 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -3,7 +3,7 @@ /* meshlink.h -- MeshLink API - Copyright (C) 2014-2019 Guus Sliepen + Copyright (C) 2014-2021 Guus Sliepen 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 @@ -87,7 +87,7 @@ typedef enum { 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 @@ -206,6 +206,17 @@ bool meshlink_open_params_set_storage_key(meshlink_open_params_t *params, const */ 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, @@ -379,6 +390,21 @@ void meshlink_close(struct meshlink_handle *mesh); */ 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. @@ -585,6 +611,27 @@ typedef void (*meshlink_blacklisted_cb_t)(struct meshlink_handle *mesh, struct m */ 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 @@ -809,6 +856,18 @@ struct meshlink_node **meshlink_get_all_nodes_by_blacklisted(struct meshlink_han */ 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. * @@ -1106,6 +1165,7 @@ char *meshlink_invite(struct meshlink_handle *mesh, struct meshlink_submesh *sub * After a successfully accepted invitation, the name of the local node may have changed. * * This function may only be called on a mesh that has not been started yet and which is not already part of an existing mesh. + * It is not valid to call this function when the storage policy set to MESHLINK_STORAGE_DISABLED. * * This function is blocking. It can take several seconds before it returns. * There is no guarantee it will perform a successful join. @@ -1504,7 +1564,6 @@ void meshlink_channel_shutdown(struct meshlink_handle *mesh, struct meshlink_cha /// 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. @@ -1516,6 +1575,21 @@ void meshlink_channel_shutdown(struct meshlink_handle *mesh, struct meshlink_cha */ 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. * @@ -1708,6 +1782,16 @@ void meshlink_hint_address(struct meshlink_handle *mesh, struct meshlink_node *n */ 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.