X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=822e314b68929a5186eb3cbbd046517b8576bb70;hb=0fdc99b6a501992b8c1dea2d1a909363b5564d0d;hp=25a52d19dd43b6430627aecdaaa396434b3030a4;hpb=9506ae59be6efde85bc1b8dd1fe0ebbe009fb1f1;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index 25a52d19..822e314b 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -547,6 +547,27 @@ typedef void (*meshlink_error_cb_t)(struct meshlink_handle *mesh, meshlink_errno */ 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 @@ -739,17 +760,49 @@ struct meshlink_node **meshlink_get_all_nodes_by_submesh(struct meshlink_handle */ 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. * @@ -801,6 +854,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 +868,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 +888,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 +1019,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 +1227,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 +1295,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); @@ -1264,7 +1365,6 @@ void meshlink_set_channel_poll_cb(struct meshlink_handle *mesh, struct meshlink_ * @param mesh A handle which represents an instance of MeshLink. * @param channel A handle for the channel. * @param size The desired size for the send buffer. - * If a NULL pointer is given, the callback will be disabled. */ void meshlink_set_channel_sndbuf(struct meshlink_handle *mesh, struct meshlink_channel *channel, size_t size); @@ -1276,10 +1376,48 @@ void meshlink_set_channel_sndbuf(struct meshlink_handle *mesh, struct meshlink_c * @param mesh A handle which represents an instance of MeshLink. * @param channel A handle for the channel. * @param size The desired size for the send buffer. - * If a NULL pointer is given, the callback will be disabled. */ void meshlink_set_channel_rcvbuf(struct meshlink_handle *mesh, struct meshlink_channel *channel, size_t size); +/// Set the send buffer storage of a channel. +/** This function provides MeshLink with a send buffer allocated by the application. + * The buffer must be valid until the channel is closed or until this function is called again with a NULL pointer for @a buf. + * + * \memberof meshlink_channel + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel. + * @param buf A pointer to the start of the buffer. + * If a NULL pointer is given, MeshLink will use its own internal buffer again. + * @param size The size of the buffer. + */ +void meshlink_set_channel_sndbuf_storage(struct meshlink_handle *mesh, struct meshlink_channel *channel, void *buf, size_t size); + +/// Set the receive buffer storage of a channel. +/** This function provides MeshLink with a receive buffer allocated by the application. + * The buffer must be valid until the channel is closed or until this function is called again with a NULL pointer for @a buf. + * + * \memberof meshlink_channel + * @param mesh A handle which represents an instance of MeshLink. + * @param channel A handle for the channel. + * @param buf A pointer to the start of the buffer. + * If a NULL pointer is given, MeshLink will use its own internal buffer again. + * @param size The size of the buffer. + */ +void meshlink_set_channel_rcvbuf_storage(struct meshlink_handle *mesh, struct meshlink_channel *channel, void *buf, 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. @@ -1589,6 +1727,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.