X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=86d2587cfc13bbb0ca4ec5040aa4ad8f1a12bf85;hb=104148f04ad25f9f7f62753a11b81090c5b36984;hp=dcafc3bc825fa4090b08c6893e77d8f2b2d46acb;hpb=ae2beb99a42825d3b4fb77c15abfc8bad9bf0923;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index dcafc3bc..86d2587c 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -39,7 +39,7 @@ typedef enum { #ifndef MESHLINK_INTERNAL_H struct meshlink_handle { - meshlink_errno_t errno; /// Code of the last encountered error. + meshlink_errno_t meshlink_errno; /// Code of the last encountered error. const char *errstr; /// Textual representation of most recent error encountered. }; @@ -66,6 +66,9 @@ extern const char *meshlink_strerror(meshlink_errno_t errno); * but it is not a problem if it is run more than once, as long as * the arguments given are the same. * + * This function does not start any network I/O yet. The application should + * first set callbacks, and then call meshlink_start(). + * * @param confbase The directory in which MeshLink will store its configuration files. * @param name The name which this instance of the application will use in the mesh. * @@ -74,22 +77,22 @@ extern const char *meshlink_strerror(meshlink_errno_t errno); extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name); /// Start MeshLink. -/** This function causes MeshLink to create a new thread, which will - * handle all network I/O. +/** This function causes MeshLink to open network sockets, make outgoing connections, and + * create a new thread, which will handle all network I/O. * * @param confbase The directory in which MeshLink will store its configuration files. * * @return This function will return true if MeshLink has succesfully started its thread, false otherwise. */ -extern bool meshlink_start(meshlink_handle_t *handle); +extern bool meshlink_start(meshlink_handle_t *mesh); /// Stop MeshLink. /** This function causes MeshLink to disconnect from all other nodes, - * and shuts down its own thread. + * close all sockets, and shut down its own thread. * * @param handle A handle which represents an instance of MeshLink. */ -extern void meshlink_stop(meshlink_handle_t *handle); +extern void meshlink_stop(meshlink_handle_t *mesh); /// Close the MeshLink handle. /** This function calls meshlink_stop() if necessary, @@ -98,7 +101,7 @@ extern void meshlink_stop(meshlink_handle_t *handle); * * @param handle A handle which represents an instance of MeshLink. */ -extern void meshlink_close(meshlink_handle_t *handle); +extern void meshlink_close(meshlink_handle_t *mesh); /// A callback for receiving data from the mesh. /** @param handle A handle which represents an instance of MeshLink. @@ -106,7 +109,7 @@ extern void meshlink_close(meshlink_handle_t *handle); * @param data A pointer to a buffer containing the data sent by the source. * @param len The length of the received data. */ -typedef void (*meshlink_receive_cb_t)(meshlink_handle_t *handle, meshlink_node_t *source, const void *data, size_t len); +typedef void (*meshlink_receive_cb_t)(meshlink_handle_t *mesh, meshlink_node_t *source, const void *data, size_t len); /// Set the receive callback. /** This functions sets the callback that is called whenever another node sends data to the local node. @@ -118,14 +121,14 @@ typedef void (*meshlink_receive_cb_t)(meshlink_handle_t *handle, meshlink_node_t * @param handle 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. */ -void meshlink_set_receive_cb(meshlink_handle_t *handle, meshlink_receive_cb_t cb); +extern void meshlink_set_receive_cb(meshlink_handle_t *mesh, meshlink_receive_cb_t cb); /// A callback reporting node status changes. /** @param handle A handle which represents an instance of MeshLink. * @param node A pointer to a meshlink_node_t describing the node whose status changed. * @param reachable True if the node is reachable, false otherwise. */ -typedef void (*meshlink_node_status_cb_t)(meshlink_handle_t *handle, meshlink_node_t *node, bool reachable); +typedef void (*meshlink_node_status_cb_t)(meshlink_handle_t *mesh, meshlink_node_t *node, bool reachable); /// Set the node status callback. /** This functions sets the callback that is called whenever another node's status changed. @@ -137,7 +140,7 @@ typedef void (*meshlink_node_status_cb_t)(meshlink_handle_t *handle, meshlink_no * @param handle A handle which represents an instance of MeshLink. * @param cb A pointer to the function which will be called when another node's status changes. */ -void meshlink_set_node_status_cb(meshlink_handle_t *handle, meshlink_node_status_cb_t cb); +extern void meshlink_set_node_status_cb(meshlink_handle_t *mesh, meshlink_node_status_cb_t cb); /// Severity of log messages generated by MeshLink. typedef enum { @@ -153,7 +156,7 @@ typedef enum { * @param level An enum describing the severity level of the message. * @param text A pointer to a string containing the textual log message. */ -typedef void (*meshlink_log_cb_t)(meshlink_handle_t *handle, meshlink_log_level_t level, const char *text); +typedef void (*meshlink_log_cb_t)(meshlink_handle_t *mesh, meshlink_log_level_t level, const char *text); /// Set the log callback. /** This functions sets the callback that is called whenever MeshLink has some information to log. @@ -166,7 +169,7 @@ typedef void (*meshlink_log_cb_t)(meshlink_handle_t *handle, meshlink_log_level_ * @param level An enum describing the minimum severity level. Debugging information with a lower level will not trigger the callback. * @param cb A pointer to the function which will be called when another node sends data to the local node. */ -void meshlink_set_log_cb(meshlink_handle_t *handle, meshlink_log_level_t level, meshlink_receive_cb_t cb); +extern void meshlink_set_log_cb(meshlink_handle_t *mesh, meshlink_log_level_t level, meshlink_log_cb_t cb); /// Send data to another node. /** This functions sends one packet of data to another node in the mesh. @@ -182,7 +185,7 @@ void meshlink_set_log_cb(meshlink_handle_t *handle, meshlink_log_level_t level, * @return This function will return true if MeshLink has queued the message for transmission, and false otherwise. * A return value of true does not guarantee that the message will actually arrive at the destination. */ -extern bool meshlink_send(meshlink_handle_t *handle, meshlink_node_t *destination, const void *data, unsigned int len); +extern bool meshlink_send(meshlink_handle_t *mesh, meshlink_node_t *destination, const void *data, unsigned int len); /// Get a handle for a specific node. /** This function returns a handle for the node with the given name. @@ -193,7 +196,7 @@ extern bool meshlink_send(meshlink_handle_t *handle, meshlink_node_t *destinatio * @return A pointer to a meshlink_node_t which represents the requested node, * or NULL if the requested node does not exist. */ -extern meshlink_node_t *meshlink_get_node(meshlink_handle_t *handle, const char *name); +extern meshlink_node_t *meshlink_get_node(meshlink_handle_t *mesh, const char *name); /// Get a list of all nodes. /** This function returns a list with handles for all known nodes. @@ -204,7 +207,7 @@ extern meshlink_node_t *meshlink_get_node(meshlink_handle_t *handle, const char * * @param return The number of known nodes. This can be larger than nmemb, in which case not all nodes were stored in the nodes array. */ -extern size_t meshlink_get_all_nodes(meshlink_handle_t *handle, meshlink_node_t **nodes, size_t nmemb); +extern size_t meshlink_get_all_nodes(meshlink_handle_t *mesh, meshlink_node_t **nodes, size_t nmemb); /// Sign data using the local node's MeshLink key. /** This function signs data using the local node's MeshLink key. @@ -217,7 +220,7 @@ extern size_t meshlink_get_all_nodes(meshlink_handle_t *handle, meshlink_node_t * @return This function returns a pointer to a string containing the signature, or NULL in case of an error. * The application should call free() after it has finished using the signature. */ -extern char *meshlink_sign(meshlink_handle_t *handle, const char *data, size_t len); +extern char *meshlink_sign(meshlink_handle_t *mesh, const char *data, size_t len); /// 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. @@ -230,7 +233,7 @@ extern char *meshlink_sign(meshlink_handle_t *handle, const char *data, size_t l * * @return This function returns true if the signature is valid, false otherwise. */ -extern bool meshlink_verify(meshlink_handle_t *handle, meshlink_node_t *source, const char *data, size_t len, const char *signature); +extern bool meshlink_verify(meshlink_handle_t *mesh, meshlink_node_t *source, const char *data, size_t len, const char *signature); /// Invite another node into the mesh. /** This function generates an invitation that can be used by another node to join the same mesh as the local node. @@ -244,7 +247,7 @@ extern bool meshlink_verify(meshlink_handle_t *handle, meshlink_node_t *source, * @return This function returns a string that contains the invitation URL. * The application should call free() after it has finished using the URL. */ -extern char *meshlink_invite(meshlink_handle_t *handle, const char *name); +extern char *meshlink_invite(meshlink_handle_t *mesh, const char *name); /// Use an invitation to join a mesh. /** This function allows the local node to join an existing mesh using an invitation URL generated by another node. @@ -256,7 +259,7 @@ extern char *meshlink_invite(meshlink_handle_t *handle, const char *name); * * @return This function returns true if the local node joined the mesh it was invited to, false otherwise. */ -extern bool meshlink_join(meshlink_handle_t *handle, const char *invitation); +extern bool meshlink_join(meshlink_handle_t *mesh, const char *invitation); /// Export the local node's key and addresses. /** This function generates a string that contains the local node's public key and one or more IP addresses. @@ -268,7 +271,7 @@ extern bool meshlink_join(meshlink_handle_t *handle, const char *invitation); * @return This function returns a string that contains the exported key and addresses. * The application should call free() after it has finished using this string. */ -extern char *meshlink_export(meshlink_handle_t *handle); +extern char *meshlink_export(meshlink_handle_t *mesh); /// Import another node's key and addresses. /** This function accepts a string containing the exported public key and addresses of another node. @@ -279,7 +282,7 @@ extern char *meshlink_export(meshlink_handle_t *handle); * * @return This function returns true if the data was valid and the other node has been granted access to the mesh, false otherwise. */ -extern bool meshlink_import(meshlink_handle_t *handle, const char *data); +extern bool meshlink_import(meshlink_handle_t *mesh, const char *data); /// Blacklist a node from the mesh. /** This function causes the local node to blacklist another node. @@ -289,6 +292,6 @@ extern bool meshlink_import(meshlink_handle_t *handle, const char *data); * @param handle A handle which represents an instance of MeshLink. * @param node A pointer to a meshlink_node_t describing the node to be blacklisted. */ -extern void meshlink_blacklist(meshlink_handle_t *handle, meshlink_node_t *node); +extern void meshlink_blacklist(meshlink_handle_t *mesh, meshlink_node_t *node); #endif // MESHLINK_H