X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=1acd99b0663bd021ba6fc70a4e0ecfcb48ff319a;hb=refs%2Fheads%2Ffeature%2Fmetaconnection-address;hp=3a23eb088b6d38a810b7f821565b00cd6afdfddd;hpb=5a8e05640dfa2db62d3a4afe82d38137355733d4;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index 3a23eb08..1acd99b0 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.