X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=8a3c1a19ab78fef1ee763faa522d48b8e9aa94a7;hb=902446edf822a32383c4fa4b7c13b83a568095ad;hp=dd08436d78fd982957612f59896eed48960712b8;hpb=fe5563f92021618b4a8b41e412c73d8364fcaf6e;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index dd08436d..8a3c1a19 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -173,7 +173,7 @@ extern void meshlink_open_params_free(meshlink_open_params_t *params); * @param params A pointer to a meshlink_open_params_t which must have been created earlier with meshlink_open_params_init(). * @param netns A filedescriptor that must point to a valid network namespace, or -1 to have MeshLink use the same namespace as the calling thread. * - * @return This function will return true if the open parameters have been succesfully updated, false otherwise. + * @return This function will return true if the open parameters have been successfully updated, false otherwise. */ extern bool meshlink_open_params_set_netns(meshlink_open_params_t *params, int netns) __attribute__((__warn_unused_result__)); @@ -184,7 +184,7 @@ extern bool meshlink_open_params_set_netns(meshlink_open_params_t *params, int n * @param key A pointer to a key, or NULL in case no encryption should be used. * @param keylen The length of the given key, or 0 in case no encryption should be used. * - * @return This function will return true if the open parameters have been succesfully updated, false otherwise. + * @return This function will return true if the open parameters have been successfully updated, false otherwise. */ extern bool meshlink_open_params_set_storage_key(meshlink_open_params_t *params, const void *key, size_t keylen) __attribute__((__warn_unused_result__)); @@ -514,7 +514,7 @@ extern void meshlink_set_log_cb(struct meshlink_handle *mesh, meshlink_log_level /// A callback for receiving error conditions encountered by the MeshLink thread. /** @param mesh A handle which represents an instance of MeshLink, or NULL. - * @param errno The error code describing what kind of error occured. + * @param errno The error code describing what kind of error occurred. */ typedef void (*meshlink_error_cb_t)(struct meshlink_handle *mesh, meshlink_errno_t meshlink_errno); @@ -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. * @@ -734,6 +758,22 @@ extern dev_class_t meshlink_get_node_dev_class(struct meshlink_handle *mesh, str */ extern struct meshlink_submesh *meshlink_get_node_submesh(struct meshlink_handle *mesh, struct meshlink_node *node) __attribute__((__warn_unused_result__)); +/// Get a node's reachability status. +/** This function returns the current reachability of a given node, and the times of the last state changes. + * If a given state change never happened, the time returned will be 0. + * + * \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 last_reachable A pointer to a time_t variable that will be filled in with the last time the node became reachable. + * Pass NULL to not have anything written. + * @param last_unreachable A pointer to a time_t variable that will be filled in with the last time the node became unreachable. + * Pass NULL to not have anything written. + * + * @return This function returns true if the node is currently reachable, false otherwise. + */ +extern bool meshlink_get_node_reachability(struct meshlink_handle *mesh, struct meshlink_node *node, time_t *last_reachable, time_t *last_unreachable); + /// Verify the signature generated by another node of a piece of data. /** This function verifies the signature that another node generated for a piece of data. * @@ -999,6 +1039,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 +1074,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 +1102,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 +1540,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