X-Git-Url: http://git.meshlink.io/?p=meshlink;a=blobdiff_plain;f=src%2Fmeshlink.h;h=13976266652296e67477447ff1dfb1e483a1dc1d;hp=98a34bd651d72f9a25a9a6b6aadc4eb9b2b49bc9;hb=3febbb4453f5c6b0286e7e3c68a5dbcec975b6fd;hpb=42cef01039177f3c762001439c8fb6bbdcd6e159 diff --git a/src/meshlink.h b/src/meshlink.h index 98a34bd6..13976266 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); @@ -758,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. * @@ -794,8 +810,32 @@ extern bool meshlink_verify(struct meshlink_handle *mesh, struct meshlink_node * */ extern bool meshlink_set_canonical_address(struct meshlink_handle *mesh, struct meshlink_node *node, const char *address, const char *port) __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. + * Multiple addresses can be added using multiple calls to this function. + * + * \memberof meshlink_handle + * @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. + * + * @return This function returns true if the address was added, false otherwise. + */ +extern bool meshlink_add_invitation_address(struct meshlink_handle *mesh, const char *address, const char *port) __attribute__((__warn_unused_result__)); + +/// Clears all invitation address for the local node. +/** This function removes all addresses added with meshlink_add_invitation_address(). + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + */ +extern void meshlink_clear_invitation_addresses(struct meshlink_handle *mesh); + /// Add an Address for the local node. /** This function adds an Address for the local node, which will be used for invitation URLs. + * @deprecated This function is deprecated, use meshlink_set_canonical_address() and/or meshlink_add_invitation_address(). * * \memberof meshlink_handle * @param mesh A handle which represents an instance of MeshLink. @@ -803,7 +843,7 @@ extern bool meshlink_set_canonical_address(struct meshlink_handle *mesh, struct * * @return This function returns true if the address was added, false otherwise. */ -extern bool meshlink_add_address(struct meshlink_handle *mesh, const char *address) __attribute__((__warn_unused_result__)); +extern bool meshlink_add_address(struct meshlink_handle *mesh, const char *address) __attribute__((__warn_unused_result__, __deprecated__("use meshlink_set_canonical_address() and/or meshlink_add_invitation_address() instead"))); /// Try to discover the external address for the local node. /** This function performs tries to discover the local node's external address @@ -881,7 +921,7 @@ extern char *meshlink_get_local_address_for_family(struct meshlink_handle *mesh, /// Try to discover the external address for the local node, and add it to its list of addresses. /** This function is equivalent to: * - * meshlink_add_address(mesh, meshlink_get_external_address(mesh)); + * meshlink_set_canonical_address(mesh, meshlink_get_self(mesh), meshlink_get_external_address(mesh), NULL); * * Read the description of meshlink_get_external_address() for the limitations of this function. * @@ -1524,6 +1564,39 @@ 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); + +/// 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. + * By calling this function with @a inviter_commits_first set to true, the order is reversed. + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + * @param inviter_commits_first If true, then the node that invited a peer will commit data to disk first. + */ +extern void meshlink_set_inviter_commits_first(struct meshlink_handle *mesh, bool inviter_commits_first); + +/// Set the URL used to discover the host's external address +/** For generating invitation URLs, MeshLink can look up the externally visible address of the local node. + * It does so by querying an external service. By default, this is http://meshlink.io/host.cgi. + * Only URLs starting with http:// are supported. + * + * \memberof meshlink_handle + * @param mesh A handle which represents an instance of MeshLink. + * @param url The URL to use for external address queries, or NULL to revert back to the default URL. + */ +extern void meshlink_set_external_address_discovery_url(struct meshlink_handle *mesh, const char *url); + #ifdef __cplusplus } #endif