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