X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;f=src%2Fmeshlink.h;h=fdf0896e3e51786612ff47b5f61529786bc8c981;hb=a230bea6a2fc33876ff46478449e466a6407c09d;hp=ca78afd082cc17bf53f7d2e3be347c3285ff7ab4;hpb=1d91eecd5611005de957d4821b8bb205000ed57f;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index ca78afd0..fdf0896e 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -18,21 +18,20 @@ */ #ifndef MESHLINK_H +#define MESHLINK_H #include #include -#ifndef MESHLINK_INTERNAL_H +#ifdef __cplusplus +extern "C" { +#endif /// A handle for an instance of MeshLink. typedef struct meshlink_handle meshlink_handle_t; /// A handle for a MeshLink node. -typedef struct meshlink_node { - const char *name; -} meshlink_node_t; - -#endif // MESHLINK_INTERNAL_H +typedef struct meshlink_node meshlink_node_t; /// Code of most recent error encountered. typedef enum { @@ -41,10 +40,19 @@ typedef enum { MESHLINK_ENOENT, // Node is not known } meshlink_errno_t; -extern meshlink_errno_t meshlink_errno; +#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. +}; -/// Textual representation of most recent error encountered. -const char *meshlink_errstr; +#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. @@ -62,6 +70,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. * @@ -70,22 +81,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, @@ -94,7 +105,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. @@ -102,7 +113,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. @@ -114,7 +125,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. @@ -130,7 +189,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. @@ -141,7 +200,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. @@ -152,7 +211,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. @@ -165,7 +224,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. @@ -178,7 +237,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. @@ -192,7 +251,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. @@ -204,7 +263,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. @@ -216,7 +275,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. @@ -227,7 +286,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. @@ -237,6 +296,10 @@ 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); + +#ifdef __cplusplus +} +#endif #endif // MESHLINK_H