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.
23 #ifndef MESHLINK_EXPORT
24 #define MESHLINK_EXPORT __attribute__((visibility("default")))
28 /** This header files declares functions that are only intended for debugging and quality control.
29 * They are not necessary for the normal operation of MeshLink.
30 * Applications should not depend on any of these functions for their normal operation.
33 /// An edge in the MeshLink network.
34 typedef struct devtool_edge devtool_edge_t;
36 /// An edge in the MeshLink network.
38 struct meshlink_node *from; ///< 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 meshlink_node *to; ///< Pointer to a node. Node memory is
43 // owned by meshlink and should not be
44 // deallocated. Node contents may be
45 // changed by meshlink.
46 struct sockaddr_storage address;///< The address information associated
48 int weight; ///< Weight assigned to this edge.
51 /// Get a list of edges.
52 /** This function returns an array with copies of all known bidirectional edges.
53 * The edges are copied to capture the mesh state at call time, since edges
54 * mutate frequently. The nodes pointed to within the devtool_edge_t type
55 * are not copies; these are the same pointers that one would get from a call
56 * to meshlink_get_all_nodes().
58 * @param mesh A handle which represents an instance of MeshLink.
59 * @param edges A pointer to a previously allocated array of
60 * devtool_edge_t, or NULL in which case MeshLink will
61 * allocate a new array.
62 * The application is allowed to call free() on the array whenever it wishes.
63 * The pointers in the devtool_edge_t elements are valid until
64 * meshlink_close() is called.
65 * @param nmemb A pointer to a variable holding the number of elements that
66 * are stored in the array. In case the @a edges @a
67 * argument is not NULL, MeshLink might call realloc()
68 * on the array to change its size.
69 * The contents of this variable will be changed to reflect
70 * the new size of the array.
71 * @return A pointer to an array containing devtool_edge_t elements,
72 * or NULL in case of an error.
73 * If the @a edges @a argument was not NULL, then the
74 * return value can be either the same value or a different
75 * value. If the new values is NULL, then the old array
76 * will have been freed by Meshlink.
78 MESHLINK_EXPORT devtool_edge_t *devtool_get_all_edges(meshlink_handle_t *mesh, devtool_edge_t *edges, size_t *nmemb);
80 /// Export a list of edges to a file in JSON format.
81 /* @param mesh A handle which represents an instance of MeshLink.
82 * @param FILE An open file descriptor to which a JSON representation of the edges will be written.
84 * @return True in case of success, false otherwise.
86 MESHLINK_EXPORT bool devtool_export_json_all_edges_state(meshlink_handle_t *mesh, FILE *stream);
88 /// The status of a node.
89 typedef struct devtool_node_status devtool_node_status_t;
91 /// The status of a node.
92 struct devtool_node_status {
94 struct sockaddr_storage address;
101 DEVTOOL_UDP_FAILED = -2, /// UDP tried but failed
102 DEVTOOL_UDP_IMPOSSIBLE = -1, /// UDP not possible (node unreachable)
103 DEVTOOL_UDP_UNKNOWN = 0, /// UDP status not known (never tried to communicate with the node)
104 DEVTOOL_UDP_TRYING, /// UDP detection in progress
105 DEVTOOL_UDP_WORKING, /// UDP communication established
108 uint64_t in_data; /// Bytes received from channels
109 uint64_t out_data; /// Bytes sent via channels
110 uint64_t in_forward; /// Bytes received for channels that need to be forwarded to other nodes
111 uint64_t out_forward; /// Bytes forwarded from channel from other nodes
112 uint64_t in_meta; /// Bytes received from meta-connections, heartbeat packets etc.
113 uint64_t out_meta; /// Bytes sent on meta-connections, heartbeat packets etc.
116 /// Get the status of a node.
117 /** This function returns a struct containing extra information about a node.
118 * The information is a snapshot taken at call time.
120 * @param mesh A handle which represents an instance of MeshLink.
121 * @param node A pointer to a meshlink_node_t.
122 * @param status A pointer to a devtools_node_status_t variable that has
123 * to be provided by the caller.
124 * The contents of this variable will be changed to reflect
125 * the current status of the node.
127 MESHLINK_EXPORT void devtool_get_node_status(meshlink_handle_t *mesh, meshlink_node_t *node, devtool_node_status_t *status);
129 /// Reset the traffic counters of a node.
130 /** This function resets the byte counters for the given node to zero.
131 * It also returns the status containing the counters right before they are zeroed.
133 * @param mesh A handle which represents an instance of MeshLink.
134 * @param node A pointer to a meshlink_node_t.
135 * @param status A pointer to a devtools_node_status_t variable that has
136 * to be provided by the caller.
137 * The contents of this variable will be changed to reflect
138 * the current status of the node before the counters are zeroed.
139 * If a NULL pointers is passed, no status will be written.
141 MESHLINK_EXPORT void devtool_reset_node_counters(meshlink_handle_t *mesh, meshlink_node_t *node, devtool_node_status_t *status);
143 /// Get the list of all submeshes of a meshlink instance.
144 /** This function returns an array of submesh handles.
145 * These pointers are the same pointers that are present in the submeshes list
148 * @param mesh A handle which represents an instance of MeshLink.
149 * @param submeshes A pointer to an array of submesh handles if any allocated previously.
150 * @param nmemb A pointer to a size_t variable that has
151 * to be provided by the caller.
152 * The contents of this variable will be changed to indicate
153 * the number if array elements.
155 MESHLINK_EXPORT meshlink_submesh_t **devtool_get_all_submeshes(meshlink_handle_t *mesh, meshlink_submesh_t **submeshes, size_t *nmemb);
157 /// Open a MeshLink instance in a given network namespace.
158 /** This function opens MeshLink in the given network namespace.
160 * @param confbase The directory in which MeshLink will store its configuration files.
161 * After the function returns, the application is free to overwrite or free @a confbase @a.
162 * @param name The name which this instance of the application will use in the mesh.
163 * After the function returns, the application is free to overwrite or free @a name @a.
164 * @param appname The application name which will be used in the mesh.
165 * After the function returns, the application is free to overwrite or free @a name @a.
166 * @param devclass The device class which will be used in the mesh.
167 * @param netns A filedescriptor that represents the network namespace.
169 * @return A pointer to a meshlink_handle_t which represents this instance of MeshLink, or NULL in case of an error.
170 * The pointer is valid until meshlink_close() is called.
172 MESHLINK_EXPORT meshlink_handle_t *devtool_open_in_netns(const char *confbase, const char *name, const char *appname, dev_class_t devclass, int netns);
174 /// Debug function pointer variable for set port API
175 /** This function pointer variable is a userspace tracepoint or debugger callback for
176 * set port function @a meshlink_set_port @a.
177 * On assigning a debug function variable invokes callback when try_bind() succeeds in meshlink_set_port API.
180 MESHLINK_EXPORT extern void (*devtool_trybind_probe)(void);
182 /// Debug function pointer variable for encrypted key rotate API
183 /** This function pointer variable is a userspace tracepoint or debugger callback for
184 * encrypted key rotation function @a meshlink_encrypted_key_rotate @a.
185 * On assigning a debug function variable invokes callback for each stage from the key rotate API.
187 * @param stage Debug stage number.
189 MESHLINK_EXPORT extern void (*devtool_keyrotate_probe)(int stage);
191 /// Debug function pointer variable for asynchronous DNS resolving
192 MESHLINK_EXPORT extern void (*devtool_adns_resolve_probe)(void);
194 /// Debug function pointer variable for SPTPS key renewal
195 /** This function pointer variable is a userspace tracepoint or debugger callback for
198 * @param node The node whose SPTPS key(s) are being renewed
200 MESHLINK_EXPORT extern void (*devtool_sptps_renewal_probe)(meshlink_node_t *node);
202 /// Force renewal of SPTPS sessions with the given node.
203 /** This causes the SPTPS sessions for both the UDP and TCP connections to renew their keys.
205 * @param mesh A handle which represents an instance of MeshLink.
206 * @param node The node whose SPTPS key(s) should be renewed
208 MESHLINK_EXPORT void devtool_force_sptps_renewal(meshlink_handle_t *mesh, meshlink_node_t *node);
210 /// Debug function pointer variable for asserting inviter/invitee committing sequence
211 /** This function pointer variable is a userspace tracepoint or debugger callback which
212 * invokes either after inviter writing invitees host file into the disk
213 * or after invitee writing it's main config file and host config files that inviter sent into
216 * @param inviter_commited_first true if inviter committed first else false if invitee committed first the other host file into the disk.
218 MESHLINK_EXPORT extern void (*devtool_set_inviter_commits_first)(bool inviter_commited_first);
220 /// Set the meta-connection status callback.
221 /** This functions sets the callback that is called whenever a meta-connection is made or closed.
222 * The callback is run in MeshLink's own thread.
223 * It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
224 * to hand the data over to the application's thread.
225 * The callback should also not block itself and return as quickly as possible.
227 * \memberof meshlink_handle
228 * @param mesh A handle which represents an instance of MeshLink.
229 * @param cb A pointer to the function which will be called when a node's meta-connection status changes.
230 * If a NULL pointer is given, the callback will be disabled.
232 MESHLINK_EXPORT void devtool_set_meta_status_cb(struct meshlink_handle *mesh, meshlink_node_status_cb_t cb);