Removed references to HAVE_STRUCT_SOCKADDR_STORAGE.

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index 8bc8c706f5a4bff29455f302a8b262c22d5e61d1..6f104abe5fcb5cc29bedb9f7e048dd465e211e37 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -100,13 +100,20 @@ struct meshlink_channel {
 
 #endif // MESHLINK_INTERNAL_H
 
-// TODO documentation
+/// An edge in the meshlink network.
 struct meshlink_edge {
-       struct meshlink_node *from;
-       struct meshlink_node *to;
-       struct sockaddr_storage address;
-       uint32_t options;
-       int weight;
+       struct meshlink_node *from;     ///< Pointer to a node. Node memory is
+                                       //   owned by meshlink and should not be
+                                       //   deallocated. Node contents may be
+                                       //   changed by meshlink.
+       struct meshlink_node *to;       ///< Pointer to a node. Node memory is
+                                        //   owned by meshlink and should not be
+                                        //   deallocated. Node contents may be
+                                        //   changed by meshlink.
+       struct sockaddr_storage address;///< The address information associated
+                                       //   with this edge.
+       uint32_t options;               ///< Edge options. @TODO what are edge options?
+       int weight;                     ///< Weight assigned to this edge.
 };
 
 /// Get the text for the given MeshLink error code.
@@ -628,16 +635,31 @@ extern void meshlink_hint_address(meshlink_handle_t *mesh, meshlink_node_t *node
  *  to meshlink_get_all_nodes().
  *
  *  @param mesh         A handle which represents an instance of MeshLink.
- *  @param nmemb        A pointer to a variable that will be filled with the number
- *                     of edges in the returned array.
- *
+ *  @param edges        A pointer to a previously allocated array of pointers to
+ *                     meshlink_edge_t, or NULL in which case MeshLink will
+ *                     allocate a new array. The application CANNOT supply an
+ *                     array it allocated itself with malloc, but CAN use
+ *                     the return value from the previous call to this function
+ *                     (which is the preferred way).
+ *                      The pointers in the array are valid until meshlink_close() is called.
+ *  @param nmemb        A pointer to a variable holding the number of nodes 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 
  *                     edges, or NULL in case of an error.
- *                     The caller must call free() on each element of this
+ *                     If the @a edges @a argument was not NULL, then the
+ *                     retun value can be either the same value or a different
+ *                     value. If the new values is NULL, then the old array
+ *                     will have been freed by Meshlink.
+ *                     The caller must call free() on each element of this
  *                     array (but not the contents of said elements),
  *                     as well as the array itself when it is finished.
  */
-extern meshlink_edge_t **meshlink_get_all_edges_state(meshlink_handle_t *mesh, size_t *nmemb);
+extern meshlink_edge_t **meshlink_get_all_edges_state(meshlink_handle_t *mesh, meshlink_edge_t **edges, size_t *nmemb);
 
 #ifdef __cplusplus
 }