X-Git-Url: http://git.meshlink.io/?a=blobdiff_plain;ds=sidebyside;f=src%2Fmeshlink.h;h=6e03343bfc6997558f1b91ec4a2808b1bf8145fa;hb=ed1f31db1e8840ffd6849b48bcad93e9975a24bb;hp=74ebae5d71e4eb5771312f57bbe5a08e663a2130;hpb=1a7277c64d74ae5ae18c48ebe09a522ffe7c696b;p=meshlink diff --git a/src/meshlink.h b/src/meshlink.h index 74ebae5d..6e03343b 100644 --- a/src/meshlink.h +++ b/src/meshlink.h @@ -51,6 +51,12 @@ typedef struct meshlink_node meshlink_node_t; /// A handle for a MeshLink channel. typedef struct meshlink_channel meshlink_channel_t; +/// A struct containing all parameters used for opening a mesh. +typedef struct meshlink_open_params meshlink_open_params_t; + +/// A handle for a MeshLink sub-mesh. +typedef struct meshlink_submesh meshlink_submesh_t; + /// Code of most recent error encountered. typedef enum { MESHLINK_OK, ///< Everything is fine @@ -64,7 +70,7 @@ typedef enum { MESHLINK_ENETWORK, ///< MeshLink encountered a network error MESHLINK_EPEER, ///< A peer caused an error MESHLINK_ENOTSUP, ///< The operation is not supported in the current configuration of MeshLink - MESHLINK_EBUSY, ///< The MeshLink instance is already in use by another process + MESHLINK_EBUSY ///< The MeshLink instance is already in use by another process } meshlink_errno_t; /// Device class @@ -111,11 +117,20 @@ struct meshlink_node { void *priv; ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink. }; +struct meshlink_submesh { + const char *const name; ///< Textual name of this Sub-Mesh. It is stored in a nul-terminated C string, which is allocated by MeshLink. + void *priv; ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink. +}; + struct meshlink_channel { struct meshlink_node *const node; ///< Pointer to the peer of this channel. void *priv; ///< Private pointer which may be set freely by the application, and is never used or modified by MeshLink. }; +struct meshlink_open_params { + /* This is an opaque struct, all parameters must be set using the corresponding meshlink_open_params_*() functions. */ +}; + #endif // MESHLINK_INTERNAL_H /// Get the text for the given MeshLink error code. @@ -129,6 +144,51 @@ struct meshlink_channel { */ extern const char *meshlink_strerror(meshlink_errno_t err); +/// Create a new meshlink_open_params_t struct. +/** This function allocates and initializes a new meshlink_open_params_t struct that can be passed to meshlink_open_ex(). + * The resulting struct may be reused for multiple calls to meshlink_open_ex(). + * After the last use, the application must free this struct using meshlink_open_params_free(). + * + * @param confbase The directory in which MeshLink will store its configuration files. + * After the function returns, the application is free to overwrite or free @a confbase @a. + * @param name The name which this instance of the application will use in the mesh. + * After the function returns, the application is free to overwrite or free @a name @a. + * @param appname The application name which will be used in the mesh. + * After the function returns, the application is free to overwrite or free @a name @a. + * @param devclass The device class which will be used in the mesh. + * + * @return A pointer to a meshlink_open_params_t which can be passed to meshlink_open_ex(), or NULL in case of an error. + * The pointer is valid until meshlink_open_params_free() is called. + */ +extern meshlink_open_params_t *meshlink_open_params_init(const char *confbase, const char *name, const char *appname, dev_class_t devclass); + +/// Free a meshlink_open_params_t struct. +/** This function frees a meshlink_open_params_t struct and all resources associated with it. + * + * @param params A pointer to a meshlink_open_params_t which must have been created earlier with meshlink_open_params_init(). + */ +extern void meshlink_open_params_free(meshlink_open_params_t *params); + +/// Open or create a MeshLink instance. +/** This function opens or creates a MeshLink instance. + * All parameters needed by MeshLink are passed via a meshlink_open_params_t struct, + * which must have been initialized earlier by the application. + * + * This function returns a pointer to a struct meshlink_handle that will be allocated by MeshLink. + * When the application does no longer need to use this handle, it must call meshlink_close() to + * free its resources. + * + * This function does not start any network I/O yet. The application should + * first set callbacks, and then call meshlink_start(). + * + * @param params A pointer to a meshlink_open_params_t which must be filled in by the application. + * After the function returns, the application is free to reuse or free @a params @a. + * + * @return A pointer to a meshlink_handle_t which represents this instance of MeshLink, or NULL in case of an error. + * The pointer is valid until meshlink_close() is called. + */ +extern meshlink_handle_t *meshlink_open_ex(const meshlink_open_params_t *params); + /// Open or create a MeshLink instance. /** This function opens or creates a MeshLink instance. * The state is stored in the configuration directory passed in the variable @a confbase @a. @@ -158,6 +218,21 @@ extern const char *meshlink_strerror(meshlink_errno_t err); */ extern meshlink_handle_t *meshlink_open(const char *confbase, const char *name, const char *appname, dev_class_t devclass); +/// Create Sub-Mesh. +/** This function causes MeshLink to open a new Sub-Mesh network + * create a new thread, which will handle all network I/O. + * + * It is allowed to call this function even if MeshLink is already started, in which case it will return true. + * + * @param mesh A handle which represents an instance of MeshLink. + * + * @param submesh Name of the new Sub-Mesh to create. + * + * @return A pointer to a meshlink_submesh_t which represents this instance of SubMesh, or NULL in case of an error. + * The pointer is valid until meshlink_close() is called. + */ +meshlink_submesh_t *meshlink_submesh_open(meshlink_handle_t *mesh, const char *submesh); + /// Start MeshLink. /** This function causes MeshLink to open network sockets, make outgoing connections, and * create a new thread, which will handle all network I/O. @@ -276,7 +351,7 @@ typedef enum { 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_CRITICAL ///< Critical errors which cause MeshLink to fail completely. } meshlink_log_level_t; /// A callback for receiving log messages generated by MeshLink. @@ -417,6 +492,36 @@ extern meshlink_node_t **meshlink_get_all_nodes(meshlink_handle_t *mesh, meshlin */ extern bool meshlink_sign(meshlink_handle_t *mesh, const void *data, size_t len, void *signature, size_t *siglen); +/// Get the list of all nodes by device class. +/** This function returns a list with handles for all the nodes that matches with the given @a devclass @a . + * + * @param mesh A handle which represents an instance of MeshLink. + * @param devclass Device class of the nodes for which the list has to be obtained. + * @param nodes A pointer to a previously allocated array of pointers to meshlink_node_t, 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 with the same @a device class @a that are stored in the array. + * In case the @a nodes @a 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 of the given device class, or NULL in case of an error. + * If the @a nodes @a 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 @a should not be used anymore. + * If the new value is NULL, then the old array will have been freed by MeshLink. + */ +extern meshlink_node_t **meshlink_get_all_nodes_by_dev_class(meshlink_handle_t *mesh, dev_class_t devclass, meshlink_node_t **nodes, size_t *nmemb); + +/// Get the node's device class. +/** This function returns the device class of the given node. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param node A pointer to a meshlink_node_t describing the node. + * + * @return This function returns the device class of the @a node @a , or -1 in case of an error. + */ +extern dev_class_t meshlink_get_node_dev_class(meshlink_handle_t *mesh, meshlink_node_t *node); + /// 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. *