DEV_CLASS_COUNT
} dev_class_t;
+/// Storage policy
+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_policy_t;
+
/// Invitation flags
static const uint32_t MESHLINK_INVITE_LOCAL = 1; // Only use local addresses in the URL
static const uint32_t MESHLINK_INVITE_PUBLIC = 2; // Only use public or canonical addresses in the URL
*/
bool meshlink_open_params_set_storage_key(meshlink_open_params_t *params, const void *key, size_t keylen) __attribute__((__warn_unused_result__));
+/// Set the encryption key MeshLink should use for local storage.
+/** This function changes the open parameters to use the given storage policy.
+ *
+ * @param params A pointer to a meshlink_open_params_t which must have been created earlier with meshlink_open_params_init().
+ * @param policy The storage policy to use.
+ *
+ * @return This function will return true if the open parameters have been successfully updated, false otherwise.
+ */
+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_error_cb(struct meshlink_handle *mesh, meshlink_error_cb_t cb);
+/// A callback for receiving blacklisted conditions encountered by the MeshLink thread.
+/** @param mesh A handle which represents an instance of MeshLink, or NULL.
+ * @param node The node that blacklisted the local node.
+ */
+typedef void (*meshlink_blacklisted_cb_t)(struct meshlink_handle *mesh, struct meshlink_node *node);
+
+/// Set the blacklisted callback.
+/** This functions sets the callback that is called whenever MeshLink detects that it is blacklisted by another node.
+ *
+ * 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_blacklisted_cb(struct meshlink_handle *mesh, meshlink_blacklisted_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
* 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.
* @param mesh A handle which represents an instance of MeshLink.
* @param channel A handle for the channel.
* @param size The desired size for the send buffer.
- * If a NULL pointer is given, the callback will be disabled.
*/
void meshlink_set_channel_sndbuf(struct meshlink_handle *mesh, struct meshlink_channel *channel, size_t size);
* @param mesh A handle which represents an instance of MeshLink.
* @param channel A handle for the channel.
* @param size The desired size for the send buffer.
- * If a NULL pointer is given, the callback will be disabled.
*/
void meshlink_set_channel_rcvbuf(struct meshlink_handle *mesh, struct meshlink_channel *channel, size_t size);
+/// Set the send buffer storage of a channel.
+/** This function provides MeshLink with a send buffer allocated by the application.
+ * The buffer must be valid until the channel is closed or until this function is called again with a NULL pointer for @a buf.
+ *
+ * \memberof meshlink_channel
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param channel A handle for the channel.
+ * @param buf A pointer to the start of the buffer.
+ * If a NULL pointer is given, MeshLink will use its own internal buffer again.
+ * @param size The size of the buffer.
+ */
+void meshlink_set_channel_sndbuf_storage(struct meshlink_handle *mesh, struct meshlink_channel *channel, void *buf, size_t size);
+
+/// Set the receive buffer storage of a channel.
+/** This function provides MeshLink with a receive buffer allocated by the application.
+ * The buffer must be valid until the channel is closed or until this function is called again with a NULL pointer for @a buf.
+ *
+ * \memberof meshlink_channel
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param channel A handle for the channel.
+ * @param buf A pointer to the start of the buffer.
+ * If a NULL pointer is given, MeshLink will use its own internal buffer again.
+ * @param size The size of the buffer.
+ */
+void meshlink_set_channel_rcvbuf_storage(struct meshlink_handle *mesh, struct meshlink_channel *channel, void *buf, size_t size);
+
+/// Set the flags of a channel.
+/** This function allows changing some of the channel flags.
+ * Currently only MESHLINK_CHANNEL_NO_PARTIAL and MESHLINK_CHANNEL_DROP_LATE are supported, other flags are ignored.
+ * These flags only affect the local side of the channel with the peer.
+ * The changes take effect immediately.
+ *
+ * \memberof meshlink_channel
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param channel A handle for the channel.
+ * @param flags A bitwise-or'd combination of flags that set the semantics for this channel.
+ */
+void meshlink_set_channel_flags(struct meshlink_handle *mesh, struct meshlink_channel *channel, uint32_t flags);
+
/// Open a reliable stream channel to another node.
/** This function is called whenever a remote node wants to open a channel to the local node.
* The application then has to decide whether to accept or reject this channel.
*/
void meshlink_set_scheduling_granularity(struct meshlink_handle *mesh, long granularity);
+/// Sets the storage policy used by MeshLink
+/** This sets the policy MeshLink uses when it has new information about nodes.
+ * By default, all udpates will be stored to disk (unless an ephemeral instance has been opened).
+ * Setting the policy to MESHLINK_STORAGE_KEYS_ONLY, only updates that contain new keys for nodes
+ * are stored, as well as blacklist/whitelist settings.
+ * By setting the policy to MESHLINK_STORAGE_DISABLED, no updates will be stored.
+ *
+ * \memberof meshlink_handle
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param policy The storage policy to use.
+ */
+void meshlink_set_storage_policy(struct meshlink_handle *mesh, meshlink_storage_policy_t policy);
+
#ifdef __cplusplus
}
#endif
projects / meshlink / blobdiff