X-Git-Url: http://git.meshlink.io/?p=meshlink;a=blobdiff_plain;f=src%2Fmeshlink.h;h=3a23eb088b6d38a810b7f821565b00cd6afdfddd;hp=f504497562cf723c3e8d4f2a28315b84ea840e7e;hb=5a8e05640dfa2db62d3a4afe82d38137355733d4;hpb=8d4b96efb7955eaa96174af4804597f92e124041

diff --git a/src/meshlink.h b/src/meshlink.h
index f5044975..3a23eb08 100644
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -71,7 +71,7 @@ typedef enum {
 	MESHLINK_EPEER,        ///< A peer caused an error
 	MESHLINK_ENOTSUP,      ///< The operation is not supported in the current configuration of MeshLink
 	MESHLINK_EBUSY,        ///< The MeshLink instance is already in use by another process
-	MESHLINK_EBLACKLISTED, ///< The operation is not allowed because the node is blacklisted
+	MESHLINK_EBLACKLISTED  ///< The operation is not allowed because the node is blacklisted
 } meshlink_errno_t;
 
 /// Device class
@@ -822,7 +822,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 +953,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.
@@ -1158,9 +1161,25 @@ bool meshlink_whitelist_by_name(struct meshlink_handle *mesh, const char *name)
  */
 void meshlink_set_default_blacklist(struct meshlink_handle *mesh, bool blacklist);
 
-/// A callback for accepting incoming channels.
+/// A callback for listening for incoming channels.
 /** 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 callback should only make a decision whether to accept or reject this channel.
+ *  The accept callback should be set to get a handle to the actual channel.
+ *
+ *  The callback is run in MeshLink's own thread.
+ *  It is therefore important that the callback return quickly and uses apprioriate methods (queues, pipes, locking, etc.)
+ *  to hand any data over to the application's thread.
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *  @param node         A handle for the node that wants to open a channel.
+ *  @param port         The port number the peer wishes to connect to.
+ *
+ *  @return             This function should return true if the application accepts the incoming channel, false otherwise.
+ */
+typedef bool (*meshlink_channel_listen_cb_t)(struct meshlink_handle *mesh, struct meshlink_node *node, uint16_t port);
+
+/// A callback for accepting incoming channels.
+/** This function is called whenever a remote node has opened a channel to the local node.
  *
  *  The callback is run in MeshLink's own thread.
  *  It is therefore important that the callback return quickly and uses apprioriate methods (queues, pipes, locking, etc.)
@@ -1210,18 +1229,34 @@ typedef void (*meshlink_channel_receive_cb_t)(struct meshlink_handle *mesh, stru
  */
 typedef void (*meshlink_channel_poll_cb_t)(struct meshlink_handle *mesh, struct meshlink_channel *channel, size_t len);
 
+/// Set the listen callback.
+/** This functions sets the callback that is called whenever another node wants to open a channel to the local node.
+ *  The callback is run in MeshLink's own thread.
+ *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
+ *  to hand the data over to the application's thread.
+ *  The callback should also not block itself and return as quickly as possible.
+ *
+ *  If no listen or accept callbacks are set, incoming channels are rejected.
+ *
+ *  \memberof meshlink_handle
+ *  @param mesh      A handle which represents an instance of MeshLink.
+ *  @param cb        A pointer to the function which will be called when another node want to open a channel.
+ *                   If a NULL pointer is given, the callback will be disabled.
+ */
+void meshlink_set_channel_listen_cb(struct meshlink_handle *mesh, meshlink_channel_listen_cb_t cb);
+
 /// Set the accept callback.
-/** This functions sets the callback that is called whenever another node sends data to the local node.
+/** This functions sets the callback that is called whenever a remote node has opened a channel to the local node.
  *  The callback is run in MeshLink's own thread.
  *  It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
  *  to hand the data over to the application's thread.
  *  The callback should also not block itself and return as quickly as possible.
  *
- *  If no accept callback is set, incoming channels are rejected.
+ *  If no listen or accept callbacks are set, incoming channels are rejected.
  *
  *  \memberof meshlink_handle
  *  @param mesh      A handle which represents an instance of MeshLink.
- *  @param cb        A pointer to the function which will be called when another node sends data to the local node.
+ *  @param cb        A pointer to the function which will be called when a new channel has been opened by a remote node.
  *                   If a NULL pointer is given, the callback will be disabled.
  */
 void meshlink_set_channel_accept_cb(struct meshlink_handle *mesh, meshlink_channel_accept_cb_t cb);
@@ -1589,6 +1624,25 @@ void meshlink_set_dev_class_timeouts(struct meshlink_handle *mesh, dev_class_t d
  */
 void meshlink_set_dev_class_fast_retry_period(struct meshlink_handle *mesh, dev_class_t devclass, int fast_retry_period);
 
+/// Set device class maximum timeout
+/** This sets the maximum timeout for outgoing connection retries for a given device class.
+ *
+ *  \memberof meshlink_handle
+ *  @param mesh          A handle which represents an instance of MeshLink.
+ *  @param devclass      The device class to update
+ *  @param maxtimeout    The maximum timeout between reconnection attempts, in seconds. The default is 900.
+ */
+void meshlink_set_dev_class_maxtimeout(struct meshlink_handle *mesh, dev_class_t devclass, int maxtimeout);
+
+/// Reset all connection timers
+/** This resets all timers related to connections, causing pending outgoing connections to be retried immediately.
+ * It also sends keepalive packets on all active connections immediately.
+ *
+ *  \memberof meshlink_handle
+ *  @param mesh          A handle which represents an instance of MeshLink.
+ */
+void meshlink_reset_timers(struct meshlink_handle *mesh);
+
 /// Set which order invitations are committed
 /** This determines in which order configuration files are written to disk during an invitation.
  *  By default, the invitee saves the configuration to disk first, then the inviter.