Silence warnings about printing function pointers.

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index 7960d31051426dc927bc53aaf308a1b272916895..a6c5b4b9401a2233808b34914f8d692aa59bb71c 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -3,7 +3,7 @@
 
 /*
     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
@@ -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.
@@ -1505,7 +1531,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.
@@ -1517,6 +1542,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.
  *
@@ -1709,6 +1749,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.