X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=86d2587cfc13bbb0ca4ec5040aa4ad8f1a12bf85;hb=5cb0c2139905daffee975b20dc6cb2d2faf29078;hp=9ed903795fa39ef63b2f1f070f268dd409fdb70b;hpb=2f56ac658df99ebf87639e00d289c9533fcb8cb0;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index 9ed90379..86d2587c 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -18,6 +18,7 @@ */ #ifndef MESHLINK_H +#define MESHLINK_H #include #include @@ -28,6 +29,36 @@ typedef struct meshlink_handle meshlink_handle_t; /// A handle for a MeshLink node. typedef struct meshlink_node meshlink_node_t; +/// Code of most recent error encountered. +typedef enum { + MESHLINK_OK, // Everything is fine + MESHLINK_ENOMEM, // Out of memory + MESHLINK_ENOENT, // Node is not known +} meshlink_errno_t; + +#ifndef MESHLINK_INTERNAL_H + +struct meshlink_handle { + meshlink_errno_t meshlink_errno; /// Code of the last encountered error. + const char *errstr; /// Textual representation of most recent error encountered. +}; + +struct meshlink_node { + const char *name; // Textual name of this node. + void *priv; // Private pointer which the application can set at will. +}; + +#endif // MESHLINK_INTERNAL_H + +/// Get the text for the given MeshLink error code. +/** This function returns a pointer to the string containing the description of the given error code. + * + * @param errno An error code returned by MeshLink. + * + * @return A pointer to a string containing the description of the error code. + */ +extern const char *meshlink_strerror(meshlink_errno_t errno); + /// Initialize MeshLink's configuration directory. /** This function causes MeshLink to initialize its configuration directory, * if it hasn't already been initialized. @@ -35,30 +66,42 @@ typedef struct meshlink_node meshlink_node_t; * 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. + * * @return This function will return true if MeshLink has succesfully set up its configuration files, false otherwise. */ -extern bool meshlink_setup(const char *confbase, const char *name); +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 A handle which represents this instance of MeshLink, - * or NULL in case of an error. + * + * @return This function will return true if MeshLink has succesfully started its thread, false otherwise. */ -extern meshlink_handle_t *meshlink_start(const char *confbase); +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. Afterwards, the handle and any - * pointers to a struct meshlink_node are invalid. + * 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 *handle); +extern void meshlink_stop(meshlink_handle_t *mesh); + +/// Close the MeshLink handle. +/** This function calls meshlink_stop() if necessary, + * and frees all memory allocated by MeshLink. + * Afterwards, the handle and any pointers to a struct meshlink_node are invalid. + * + * @param handle A handle which represents an instance of MeshLink. + */ +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. @@ -66,7 +109,7 @@ extern void meshlink_stop(meshlink_handle *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. @@ -78,7 +121,55 @@ 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 *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. + * The callback is run in MeshLink's own thread. + * It is therefore 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. + * + * @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. + */ +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 { + MESHLINK_DEBUG, // Internal debugging messages. Only useful during application development. + MESHLINK_INFO, // Informational messages. + MESHLINK_WARNING, // Warnings which might indicate problems, but which are not real errors. + MESHLINK_ERROR, // Errors which hamper correct functioning of MeshLink, without causing it to fail completely. + MESHLINK_CRITICAL, // Critical errors which cause MeshLink to fail completely. +} meshlink_log_level_t; + +/// A callback for receiving log messages generated by MeshLink. +/** @param handle A handle which represents an instance of MeshLink. + * @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 *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. + * 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. + * + * @param handle A handle which represents an instance of MeshLink. + * @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. + */ +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. @@ -94,7 +185,7 @@ void meshlink_set_receive_cb(meshlink_handle_t *handle, meshlink_receive_cb_t cb * @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. @@ -105,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. @@ -116,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. @@ -129,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. @@ -142,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. @@ -156,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. @@ -168,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. @@ -180,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. @@ -191,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. @@ -201,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