1 #ifndef MESHLINK_DEVTOOLS_H
2 #define MESHLINK_DEVTOOLS_H
5 devtools.h -- header for devtools.h
6 Copyright (C) 2014, 2017 Guus Sliepen <guus@meshlink.io>
8 This program is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 2 of the License, or
11 (at your option) any later version.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License along
19 with this program; if not, write to the Free Software Foundation, Inc.,
20 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 /** This header files declares functions that are only intended for debugging and quality control.
25 * They are not necessary for the normal operation of MeshLink.
26 * Applications should not depend on any of these functions for their normal operation.
29 /// An edge in the MeshLink network.
30 typedef struct devtool_edge devtool_edge_t;
32 /// An edge in the MeshLink network.
34 struct meshlink_node *from; ///< Pointer to a node. Node memory is
35 // owned by meshlink and should not be
36 // deallocated. Node contents may be
37 // changed by meshlink.
38 struct meshlink_node *to; ///< Pointer to a node. Node memory is
39 // owned by meshlink and should not be
40 // deallocated. Node contents may be
41 // changed by meshlink.
42 struct sockaddr_storage address;///< The address information associated
44 uint32_t options; ///< Edge options. @TODO what are edge options?
45 int weight; ///< Weight assigned to this edge.
48 /// Get a list of edges.
49 /** This function returns an array with copies of all known bidirectional edges.
50 * The edges are copied to capture the mesh state at call time, since edges
51 * mutate frequently. The nodes pointed to within the devtool_edge_t type
52 * are not copies; these are the same pointers that one would get from a call
53 * to meshlink_get_all_nodes().
55 * @param mesh A handle which represents an instance of MeshLink.
56 * @param edges A pointer to a previously allocated array of
57 * devtool_edge_t, or NULL in which case MeshLink will
58 * allocate a new array.
59 * The application is allowed to call free() on the array whenever it wishes.
60 * The pointers in the devtool_edge_t elements are valid until
61 * meshlink_close() is called.
62 * @param nmemb A pointer to a variable holding the number of elements that
63 * are stored in the array. In case the @a edges @a
64 * argument is not NULL, MeshLink might call realloc()
65 * on the array to change its size.
66 * The contents of this variable will be changed to reflect
67 * the new size of the array.
68 * @return A pointer to an array containing devtool_edge_t elements,
69 * or NULL in case of an error.
70 * If the @a edges @a argument was not NULL, then the
71 * retun value can be either the same value or a different
72 * value. If the new values is NULL, then the old array
73 * will have been freed by Meshlink.
75 extern devtool_edge_t *devtool_get_all_edges(meshlink_handle_t *mesh, devtool_edge_t *edges, size_t *nmemb);
77 /// Export a list of edges to a file in JSON format.
78 /* @param mesh A handle which represents an instance of MeshLink.
79 * @param FILE An open file descriptor to which a JSON representation of the edges will be written.
81 * @return True in case of success, false otherwise.
83 extern bool devtool_export_json_all_edges_state(meshlink_handle_t *mesh, FILE *stream);