*/
void meshlink_set_error_cb(struct meshlink_handle *mesh, meshlink_error_cb_t cb);
+/// A callback for receiving blacklisted conditions encountered by the MeshLink thread.
+/** @param mesh A handle which represents an instance of MeshLink, or NULL.
+ * @param node The node that blacklisted the local node.
+ */
+typedef void (*meshlink_blacklisted_cb_t)(struct meshlink_handle *mesh, struct meshlink_node *node);
+
+/// Set the blacklisted callback.
+/** This functions sets the callback that is called whenever MeshLink detects that it is blacklisted by another node.
+ *
+ * The callback is run in MeshLink's own thread.
+ * It is 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.
+ *
+ * \memberof meshlink_handle
+ * @param mesh A handle which represents an instance of MeshLink, or NULL.
+ * @param cb A pointer to the function which will be called when a serious error is encountered.
+ * If a NULL pointer is given, the callback will be disabled.
+ */
+void meshlink_set_blacklisted_cb(struct meshlink_handle *mesh, meshlink_blacklisted_cb_t cb);
+
/// Send data to another node.
/** This functions sends one packet of data to another node in the mesh.
* The packet is sent using UDP semantics, which means that
*/
struct meshlink_node **meshlink_get_all_nodes_by_last_reachable(struct meshlink_handle *mesh, time_t start, time_t end, struct meshlink_node **nodes, size_t *nmemb) __attribute__((__warn_unused_result__));
+/// Get the list of all nodes by blacklist status.
+/** This function returns a list with handles for all the nodes who were either blacklisted or whitelisted.
+ *
+ * \memberof meshlink_handle
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param blacklisted If true, a list of blacklisted nodes will be returned, otherwise whitelisted nodes.
+ * @param nodes A pointer to a previously allocated array of pointers to struct meshlink_node, or NULL in which case MeshLink will allocate a new array.
+ * The application can supply an array it allocated itself with malloc, or the return value from the previous call to this function (which is the preferred way).
+ * The application is allowed to call free() on the array whenever it wishes.
+ * The pointers in the array are valid until meshlink_close() is called.
+ * @param nmemb A pointer to a variable holding the number of nodes that were reachable within the period given by @a start and @a end.
+ * In case the @a nodes argument is not NULL, MeshLink might call realloc() on the array to change its size.
+ * The contents of this variable will be changed to reflect the new size of the array.
+ *
+ * @return A pointer to an array containing pointers to all known nodes with the given blacklist status.
+ * If the @a nodes argument was not NULL, then the return value can either be the same value or a different value.
+ * If it is a new value, the old value of @a nodes should not be used anymore.
+ * If the new value is NULL, then the old array will have been freed by MeshLink.
+ */
+struct meshlink_node **meshlink_get_all_nodes_by_blacklisted(struct meshlink_handle *mesh, bool blacklisted, struct meshlink_node **nodes, size_t *nmemb) __attribute__((__warn_unused_result__));
+
/// Get the node's device class.
/** This function returns the device class of the given 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.
+ * @param node A pointer to a struct meshlink_node describing the node.
*
* @return This function returns the device class of the @a node, or -1 in case of an error.
*/
dev_class_t meshlink_get_node_dev_class(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
+/// Get the node's blacklist status.
+/** This function returns the given node is blacklisted.
+ *
+ * \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 node is blacklisted, false otherwise.
+ */
+bool meshlink_get_node_blacklisted(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__));
+
/// Get the node's submesh handle.
/** This function returns the submesh handle of the given node.
*
*
* 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.
*/
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.
* @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.
*/
* 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.
*/
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.)
*/
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);
*/
void meshlink_set_channel_rcvbuf(struct meshlink_handle *mesh, struct meshlink_channel *channel, size_t size);
+/// Set the flags of a channel.
+/** This function allows changing some of the channel flags.
+ * Currently only MESHLINK_CHANNEL_NO_PARTIAL and MESHLINK_CHANNEL_DROP_LATE are supported, other flags are ignored.
+ * These flags only affect the local side of the channel with the peer.
+ * The changes take effect immediately.
+ *
+ * \memberof meshlink_channel
+ * @param mesh A handle which represents an instance of MeshLink.
+ * @param channel A handle for the channel.
+ * @param flags A bitwise-or'd combination of flags that set the semantics for this channel.
+ */
+void meshlink_set_channel_flags(struct meshlink_handle *mesh, struct meshlink_channel *channel, 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.
*/
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.
projects / meshlink / blobdiff