Add meshlink_get_external_address() and meshlink_add_external_address().

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index 651f05c8bd355f54002c90881322f029d303337d..1c1e7af4d3a051706bd6f212b5ec9e64a193fab5 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -424,6 +424,39 @@ 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.
+ *  @param address      A nul-terminated C string containing the address, which can be either in numeric format or a hostname.
+ *
+ *  @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);
+
 /// 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.