Use the canonical address exclusively for making outgoing meta-connections.

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index 09a0028d9bd0799e0ecca585db9dea4d1caf2ce9..738f8647e5071d3ca815558d942229447fbc3884 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -801,6 +801,8 @@ bool meshlink_verify(struct meshlink_handle *mesh, struct meshlink_node *source,
  *
  *  If a canonical Address is set for the local node,
  *  it will be used for the hostname part of generated invitation URLs.
+ *  If a canonical Address is set for a remote node,
+ *  it is used exclusively for creating outgoing connections to that node.
  *
  *  \memberof meshlink_node
  *  @param mesh         A handle which represents an instance of MeshLink.
@@ -813,6 +815,17 @@ bool meshlink_verify(struct meshlink_handle *mesh, struct meshlink_node *source,
  */
 bool meshlink_set_canonical_address(struct meshlink_handle *mesh, struct meshlink_node *node, const char *address, const char *port) __attribute__((__warn_unused_result__));
 
+/// Clear the canonical Address for a node.
+/** This function clears the canonical Address for a node.
+ *
+ *  \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 address was removed, false otherwise.
+ */
+bool meshlink_clear_canonical_address(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
+
 /// Add an invitation address for the local node.
 /** This function adds an address for the local node, which will be used only for invitation URLs.
  *  This address is not stored permanently.
@@ -822,7 +835,7 @@ bool meshlink_set_canonical_address(struct meshlink_handle *mesh, struct meshlin
  *  @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.
  *  @param port         A nul-terminated C string containing the port, which can be either in numeric or symbolic format.
- *                      If it is NULL, the listening port's number will be used.
+ *                      If it is NULL, the current listening port's number will be used.
  *
  *  @return             This function returns true if the address was added, false otherwise.
  */
@@ -953,6 +966,9 @@ int meshlink_get_port(struct meshlink_handle *mesh) __attribute__((__warn_unused
  *  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.
  *
+ *  Note that if a canonical address has been set for the local node,
+ *  you might need to call meshlink_set_canonical_address() again to ensure it includes the new port number.
+ *
  *  \memberof meshlink_handle
  *  @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.