From 6c8d95b21e5e879bf5760a24dc17b28e489bf2ce Mon Sep 17 00:00:00 2001 From: Guus Sliepen Date: Thu, 6 Jul 2017 21:59:17 +0200 Subject: [PATCH] Document that meshlink_join() and meshlink_get_external_address() are blocking. --- src/meshlink++.h | 10 ++++++++++ src/meshlink.h | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/src/meshlink++.h b/src/meshlink++.h index 6acfe251..258d6cf4 100644 --- a/src/meshlink++.h +++ b/src/meshlink++.h @@ -354,6 +354,10 @@ namespace meshlink { * 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. * + * This function is blocking. It can take several seconds before it returns. + * There is no guarantee it will be able to resolve the external address. + * Failures might be because by temporary network outages. + * * @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 get_external_address() returns, the application is free to overwrite or free this string. @@ -424,6 +428,12 @@ namespace meshlink { * An invitation can only be used if the local node has never connected to other nodes before. * After a succesfully 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. + * + * This function is blocking. It can take several seconds before it returns. + * There is no guarantee it will perform a successful join. + * Failures might be caused by temporary network outages, or by the invitation having expired. + * * @param invitation A string containing the invitation URL. * * @return This function returns true if the local node joined the mesh it was invited to, false otherwise. diff --git a/src/meshlink.h b/src/meshlink.h index 668d8e71..2ecbfff3 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -443,6 +443,10 @@ extern bool meshlink_add_address(meshlink_handle_t *mesh, const char *address); * 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. * + * This function is blocking. It can take several seconds before it returns. + * There is no guarantee it will be able to resolve the external address. + * Failures might be because by temporary network outages. + * * @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, @@ -511,6 +515,12 @@ extern char *meshlink_invite(meshlink_handle_t *mesh, const char *name); * An invitation can only be used if the local node has never connected to other nodes before. * After a succesfully 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. + * + * This function is blocking. It can take several seconds before it returns. + * There is no guarantee it will perform a successful join. + * Failures might be caused by temporary network outages, or by the invitation having expired. + * * @param mesh A handle which represents an instance of MeshLink. * @param invitation A nul-terminated C string containing the invitation URL. * After this function returns, the application is free to overwrite or free @a invitation @a. -- 2.39.5