/*
meshlink.h -- MeshLink API
- Copyright (C) 2014-2018 Guus Sliepen <guus@meshlink.io>
+ Copyright (C) 2014-2019 Guus Sliepen <guus@meshlink.io>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
/// 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
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
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.
*/
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.
*/
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.
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.
*/
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.
*
* The URL can only be used once, after the user has joined the mesh the URL is no longer valid.
*
* @param mesh A handle which represents an instance of MeshLink.
+ * @param submesh A handle which represents an instance of SubMesh.
* @param name A nul-terminated C string containing the name that the invitee will be allowed to use in the mesh.
* After this function returns, the application is free to overwrite or free @a name @a.
* @param flags A bitwise-or'd combination of flags that controls how the URL is generated.
* @return This function returns a nul-terminated C string that contains the invitation URL, or NULL in case of an error.
* The application should call free() after it has finished using the URL.
*/
-extern char *meshlink_invite_ex(meshlink_handle_t *mesh, const char *name, uint32_t flags);
+extern char *meshlink_invite_ex(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, const char *name, uint32_t flags);
/// 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.
* Calling this function is equal to callen meshlink_invite_ex() with flags set to 0.
*
* @param mesh A handle which represents an instance of MeshLink.
+ * @param submesh A handle which represents an instance of SubMesh.
* @param name A nul-terminated C string containing the name that the invitee will be allowed to use in the mesh.
* After this function returns, the application is free to overwrite or free @a name @a.
*
* @return This function returns a nul-terminated C string that contains the invitation URL, or NULL in case of an error.
* The application should call free() after it has finished using the URL.
*/
-extern char *meshlink_invite(meshlink_handle_t *mesh, const char *name);
+extern char *meshlink_invite(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, 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.
projects / meshlink / blobdiff