X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=e3a7ca942ae3b30de27a8ce18deaa646def9f08e;hb=529b8fab8c21e7ae5af91d742ff202eab38e51f3;hp=dd08436d78fd982957612f59896eed48960712b8;hpb=fe5563f92021618b4a8b41e412c73d8364fcaf6e;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index dd08436d..e3a7ca94 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -712,6 +712,30 @@ extern struct meshlink_node **meshlink_get_all_nodes_by_dev_class(struct meshlin */ extern struct meshlink_node **meshlink_get_all_nodes_by_submesh(struct meshlink_handle *mesh, struct meshlink_submesh *submesh, struct meshlink_node **nodes, size_t *nmemb) __attribute__((__warn_unused_result__)); +/// Get the list of all nodes by time they were last reachable. +/** This function returns a list with handles for all the nodes whose last known reachability time overlaps with the given time range. + * If the range includes 0, it will count nodes that were never online. + * If start is bigger than end, the result will be inverted. + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + * @param start Start time. + * @param end End time. + * @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 that were reachable within the period given by @a start and @a end. + * 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. + */ +extern 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 node's device class. /** This function returns the device class of the given node. * @@ -999,6 +1023,28 @@ extern char *meshlink_export(struct meshlink_handle *mesh) __attribute__((__warn */ extern bool meshlink_import(struct meshlink_handle *mesh, const char *data) __attribute__((__warn_unused_result__)); +/// Forget any information about a node. +/** This function allows the local node to forget any information it has about a node, + * and if possible will remove any data it has stored on disk about the node. + * + * Any open channels to this node must be closed before calling this function. + * + * After this call returns, the node handle is invalid and may no longer be used, regardless + * of the return value of this call. + * + * Note that this function does not prevent MeshLink from actually forgetting about a node, + * or re-learning information about a node at a later point in time. It is merely a hint that + * the application does not care about this node anymore and that any resources kept could be + * cleaned up. + * + * \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 to be forgotten. + * + * @return This function returns true if all currently known data about the node has been forgotten, false otherwise. + */ +extern bool meshlink_forget_node(struct meshlink_handle *mesh, struct meshlink_node *node); + /// Blacklist a node from the mesh. /** This function causes the local node to blacklist another node. * The local node will drop any existing connections to that node, @@ -1012,6 +1058,21 @@ extern bool meshlink_import(struct meshlink_handle *mesh, const char *data) __at */ extern bool meshlink_blacklist(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__)); +/// Blacklist a node from the mesh by name. +/** This function causes the local node to blacklist another node by name. + * The local node will drop any existing connections to that node, + * and will not send data to it nor accept any data received from it any more. + * + * If no node by the given name is known, it is created. + * + * \memberof meshlink_node + * @param mesh A handle which represents an instance of MeshLink. + * @param name The name of the node to blacklist. + * + * @return This function returns true if the node has been blacklisted, false otherwise. + */ +extern bool meshlink_blacklist_by_name(struct meshlink_handle *mesh, const char *name) __attribute__((__warn_unused_result__)); + /// Whitelist a node on the mesh. /** This function causes the local node to whitelist a previously blacklisted node. * The local node will allow connections to and from that node, @@ -1025,6 +1086,22 @@ extern bool meshlink_blacklist(struct meshlink_handle *mesh, struct meshlink_nod */ extern bool meshlink_whitelist(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__)); +/// Whitelist a node on the mesh by name. +/** This function causes the local node to whitelist a node by name. + * The local node will allow connections to and from that node, + * and will send data to it and accept any data received from it. + * + * If no node by the given name is known, it is created. + * This is useful if new nodes are blacklisted by default. + * + * \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 to be whitelisted. + * + * @return This function returns true if the node has been whitelisted, false otherwise. + */ +extern bool meshlink_whitelist_by_name(struct meshlink_handle *mesh, const char *name) __attribute__((__warn_unused_result__)); + /// Set whether new nodes are blacklisted by default. /** This function sets the blacklist behaviour for newly discovered nodes. * If set to true, new nodes will be automatically blacklisted. @@ -1447,6 +1524,17 @@ extern bool meshlink_encrypted_key_rotate(struct meshlink_handle *mesh, const vo */ extern void meshlink_set_dev_class_timeouts(struct meshlink_handle *mesh, dev_class_t devclass, int pinginterval, int pingtimeout); +/// Set device class fast retry period +/** This sets the fast retry period for a given device class. + * During this period after the last time the mesh becomes unreachable, connections are tried once a second. + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + * @param devclass The device class to update + * @param fast_retry_period The period during which fast connection retries are done. The default is 0. + */ +extern void meshlink_set_dev_class_fast_retry_period(struct meshlink_handle *mesh, dev_class_t devclass, int fast_retry_period); + #ifdef __cplusplus } #endif