Document that meshlink_join() and meshlink_get_external_address() are blocking.

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index 26c7edb575953aa0fe010d78024fa4accb4b7e2e..2ecbfff339c73903c40c9d683ae5a8c875cd9689 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -77,6 +77,14 @@ typedef enum {
        _DEV_CLASS_MAX = 3
 } dev_class_t;
 
+/// Channel flags
+static const uint32_t MESHLINK_CHANNEL_RELIABLE = 1;   // Data is retransmitted when packets are lost.
+static const uint32_t MESHLINK_CHANNEL_ORDERED = 2;    // Data is delivered in-order to the application.
+static const uint32_t MESHLINK_CHANNEL_FRAMED = 4;     // Data is delivered in chunks of the same length as data was originally sent.
+static const uint32_t MESHLINK_CHANNEL_DROP_LATE = 8;  // When packets are reordered, late packets are ignored.
+static const uint32_t MESHLINK_CHANNEL_TCP = 3;        // Select TCP semantics.
+static const uint32_t MESHLINK_CHANNEL_UDP = 0;        // Select UDP semantics.
+
 /// A variable holding the last encountered error from MeshLink.
 /** This is a thread local variable that contains the error code of the most recent error
  *  encountered by a MeshLink API function called in the current thread.
@@ -435,8 +443,11 @@ 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.
- *  @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.
@@ -504,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.
@@ -668,6 +685,29 @@ extern void meshlink_set_channel_receive_cb(meshlink_handle_t *mesh, meshlink_ch
  */
 extern void meshlink_set_channel_poll_cb(meshlink_handle_t *mesh, meshlink_channel_t *channel, meshlink_channel_poll_cb_t cb);
 
+/// Open a reliable stream channel to another node.
+/** This function is called whenever a remote node wants to open a channel to the local node.
+ *  The application then has to decide whether to accept or reject this channel.
+ *
+ *  This function returns a pointer to a struct meshlink_channel that will be allocated by MeshLink.
+ *  When the application does no longer need to use this channel, it must call meshlink_close()
+ *  to free its resources.
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *  @param node         The node to which this channel is being initiated.
+ *  @param port         The port number the peer wishes to connect to.
+ *  @param cb           A pointer to the function which will be called when the remote node sends data to the local node.
+ *                      The pointer may be NULL, in which case incoming data is ignored.
+ *  @param data         A pointer to a buffer containing data to already queue for sending, or NULL if there is no data to send.
+ *                      After meshlink_send() returns, the application is free to overwrite or free this buffer.
+ *  @param len          The length of the data, or 0 if there is no data to send.
+ *  @param flags       A bitwise-or'd combination of flags that set the semantics for this channel.
+ *
+ *  @return             A handle for the channel, or NULL in case of an error.
+ *                      The handle is valid until meshlink_channel_close() is called.
+ */
+extern meshlink_channel_t *meshlink_channel_open_ex(meshlink_handle_t *mesh, meshlink_node_t *node, uint16_t port, meshlink_channel_receive_cb_t cb, const void *data, size_t len, uint32_t flags);
+
 /// Open a reliable stream channel to another node.
 /** This function is called whenever a remote node wants to open a channel to the local node.
  *  The application then has to decide whether to accept or reject this channel.
@@ -730,6 +770,16 @@ extern void meshlink_channel_close(meshlink_handle_t *mesh, meshlink_channel_t *
  */
 extern ssize_t meshlink_channel_send(meshlink_handle_t *mesh, meshlink_channel_t *channel, const void *data, size_t len);
 
+/// Get channel flags.
+/** This returns the flags used when opening this channel.
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *  @param channel      A handle for the channel.
+ *
+ *  @return             The flags set for this channel.
+ */
+extern uint32_t meshlink_channel_get_flags(meshlink_handle_t *mesh, meshlink_channel_t *channel);
+
 /// Hint that a hostname may be found at an address
 /** This function indicates to meshlink that the given hostname is likely found
  *  at the given IP address and port.