Remove debug messages incorrectly marked as warnings.

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index 1f4bb7262e6b3780e9fac55cea784fde8dd1bca1..7e82cb0dfcc508bd1ed78a145a60cd4220327eb4 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -196,6 +196,18 @@ extern void meshlink_stop(meshlink_handle_t *mesh);
  */
 extern void meshlink_close(meshlink_handle_t *mesh);
 
+/// Destroy a MeshLink instance.
+/** 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.
+ *
+ *  @param confbase The directory in which MeshLink stores its configuration files.
+ *                  After the function returns, the application is free to overwrite or free @a confbase @a.
+ *
+ *  @return         This function will return true if the MeshLink instance was succesfully destroyed, false otherwise.
+ */
+extern bool meshlink_destroy(const char *confbase);
+
 /// A callback for receiving data from the mesh.
 /** @param mesh      A handle which represents an instance of MeshLink.
  *  @param source    A pointer to a meshlink_node_t describing the source of the data.
@@ -317,6 +329,16 @@ extern bool meshlink_send(meshlink_handle_t *mesh, meshlink_node_t *destination,
  */
 extern ssize_t meshlink_get_pmtu(meshlink_handle_t *mesh, meshlink_node_t *destination);
 
+/// Get a handle for our own node.
+/** This function returns a handle for the local node.
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *
+ *  @return             A pointer to a meshlink_node_t which represents the local node.
+ *                      The pointer is guaranteed to be valid until meshlink_close() is called.
+ */
+extern meshlink_node_t *meshlink_get_self(meshlink_handle_t *mesh);
+
 /// Get a handle for a specific node.
 /** This function returns a handle for the node with the given name.
  *
@@ -402,6 +424,65 @@ extern bool meshlink_verify(meshlink_handle_t *mesh, meshlink_node_t *source, co
  */
 extern bool meshlink_add_address(meshlink_handle_t *mesh, const char *address);
 
+/// Try to discover the external address for the local node.
+/** This function performs tries to discover the local node's external address
+ *  by contacting the meshlink.io server. If a reverse lookup of the address works,
+ *  the FQDN associated with the address will be returned.
+ *
+ *  Please note that this is function only returns a single address,
+ *  even if the local node might have more than one external address.
+ *  In that case, there is no control over which address will be selected.
+ *  Also note that if you have a dynamic IP address, or are behind carrier-grade NAT,
+ *  there is no guarantee that the external address will be valid for an extended period of time.
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *
+ *  @return             This function returns a pointer to a C string containing the discovered external address,
+ *                      or NULL if there was an error looking up the address.
+ *                      After meshlink_get_external_address() returns, the application is free to overwrite or free this string.
+ */
+extern char *meshlink_get_external_address(meshlink_handle_t *mesh);
+
+/// Try to discover the external address for the local node, and add it to its list of addresses.
+/** This function is equivalent to:
+ *
+ *    meshlink_add_address(mesh, meshlink_get_external_address(mesh));
+ *
+ *  Read the description of meshlink_get_external_address() for the limitations of this function.
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *
+ *  @return             This function returns true if the address was added, false otherwise.
+ */
+extern bool meshlink_add_external_address(meshlink_handle_t *mesh);
+
+/// Get the network port used by the local node.
+/** This function returns the network port that the local node is listening on.
+ *
+ *  @param mesh          A handle which represents an instance of MeshLink.
+ *
+ *  @return              This function returns the port number, or -1 in case of an error.
+ */
+extern int meshlink_get_port(meshlink_handle_t *mesh);
+
+/// Set the network port used by the local node.
+/** This function sets the network port that the local node is listening on.
+ *  It may only be called when the mesh is not running.
+ *  If unsure, call meshlink_stop() before calling this function.
+ *  Also note that if your node is already part of a mesh with other nodes,
+ *  that the other nodes may no longer be able to initiate connections to the local node,
+ *  since they will try to connect to the previously configured port.
+ *
+ *  @param mesh          A handle which represents an instance of MeshLink.
+ *  @param port          The port number to listen on. This must be between 0 and 65535.
+ *                       If the port is set to 0, then MeshLink will listen on a port
+ *                       that is randomly assigned by the operating system every time meshlink_open() is called.
+ *
+ *  @return              This function returns true if the port was succesfully changed, false otherwise.
+ */
+
+extern bool meshlink_set_port(meshlink_handle_t *mesh, int port);
+
 /// Invite another node into the mesh.
 /** This function generates an invitation that can be used by another node to join the same mesh as the local node.
  *  The generated invitation is a string containing a URL.