Improve support for submeshes.

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index a73bccf33beba50245feec92d659551ab39e0396..6f645373a4faa7e552864b32b93c31875ced053b 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -508,6 +508,26 @@ extern bool meshlink_sign(meshlink_handle_t *mesh, const void *data, size_t len,
  */
 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 list of all nodes by Submesh.
+/** This function returns a list with handles for all the nodes that matches with the given @a Submesh @a .
+ *
+ *  @param mesh         A handle which represents an instance of MeshLink.
+ *  @param submesh      Submesh handle 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 Submesh, 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_submesh(meshlink_handle_t *mesh, meshlink_submesh_t *submesh, meshlink_node_t **nodes, size_t *nmemb);
+
 /// Get the node's device class.
 /** This function returns the device class of the given node.
  *
@@ -518,6 +538,16 @@ extern meshlink_node_t **meshlink_get_all_nodes_by_dev_class(meshlink_handle_t *
  */
 extern dev_class_t meshlink_get_node_dev_class(meshlink_handle_t *mesh, meshlink_node_t *node);
 
+/// Get the node's submesh handle.
+/** This function returns the submesh handle 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 submesh handle of the @a node @a , or NULL in case of an error.
+ */
+extern meshlink_submesh_t *meshlink_get_node_submesh(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.
  *