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 /// The status of a node.
30 typedef struct devtool_node_status devtool_node_status_t;
32 /// The status of a node.
33 struct devtool_node_status {
40 DEVTOOL_UDP_FAILED = -2, /// UDP tried but failed
41 DEVTOOL_UDP_IMPOSSIBLE = -1, /// UDP not possible (node unreachable)
42 DEVTOOL_UDP_UNKNOWN = 0, /// UDP status not known (never tried to communicate with the node)
43 DEVTOOL_UDP_TRYING, /// UDP detection in progress
44 DEVTOOL_UDP_WORKING, /// UDP communication established
52 /// Get the status of a node.
53 /** This function returns a struct containing extra information about a node.
54 * The information is a snapshot taken at call time.
56 * @param mesh A handle which represents an instance of MeshLink.
57 * @param node A pointer to a meshlink_node_t.
58 * @param status A pointer to a devtools_node_status_t variable that has
59 * to be provided by the caller.
60 * The contents of this variable will be changed to reflect
61 * the current status of the node.
63 void devtool_get_node_status(meshlink_handle_t *mesh, meshlink_node_t *node, devtool_node_status_t *status);
65 /// Open a MeshLink instance in a given network namespace.
66 /** This function opens MeshLink in the given network namespace.
68 * @param confbase The directory in which MeshLink will store its configuration files.
69 * After the function returns, the application is free to overwrite or free @a confbase @a.
70 * @param name The name which this instance of the application will use in the mesh.
71 * After the function returns, the application is free to overwrite or free @a name @a.
72 * @param appname The application name which will be used in the mesh.
73 * After the function returns, the application is free to overwrite or free @a name @a.
74 * @param devclass The device class which will be used in the mesh.
75 * @param netns A filedescriptor that represents the network namespace.
77 * @return A pointer to a meshlink_handle_t which represents this instance of MeshLink, or NULL in case of an error.
78 * The pointer is valid until meshlink_close() is called.
80 meshlink_handle_t *devtool_open_in_netns(const char *confbase, const char *name, const char *appname, dev_class_t devclass, int netns);
82 /// Debug function pointer variable for set port API
83 /** This function pointer variable is a userspace tracepoint or debugger callback for
84 * set port function @a meshlink_set_port @a.
85 * On assigning a debug function variable invokes callback when try_bind() succeeds in meshlink_set_port API.
88 extern void (*devtool_trybind_probe)(void);
90 /// Debug function pointer variable for encrypted key rotate API
91 /** This function pointer variable is a userspace tracepoint or debugger callback for
92 * encrypted key rotation function @a meshlink_encrypted_key_rotate @a.
93 * On assigning a debug function variable invokes callback for each stage from the key rotate API.
95 * @param stage Debug stage number.
97 extern void (*devtool_keyrotate_probe)(int stage);
99 /// Debug function pointer variable for SPTPS key renewal
100 /** This function pointer variable is a userspace tracepoint or debugger callback for
103 * @param node The node whose SPTPS key(s) are being renewed
105 extern void (*devtool_sptps_renewal_probe)(meshlink_node_t *node);
107 /// Force renewal of SPTPS sessions with the given node.
108 /** This causes the SPTPS sessions for both the UDP and TCP connections to renew their keys.
110 * @param mesh A handle which represents an instance of MeshLink.
111 * @param node The node whose SPTPS key(s) should be renewed
113 void devtool_force_sptps_renewal(meshlink_handle_t *mesh, meshlink_node_t *node);
115 /// Debug function pointer variable for asserting inviter/invitee committing sequence
116 /** This function pointer variable is a userspace tracepoint or debugger callback which
117 * invokes either after inviter writing invitees host file into the disk
118 * or after invitee writing it's main config file and host config files that inviter sent into
121 * @param inviter_commited_first true if inviter committed first else false if invitee committed first the other host file into the disk.
123 extern void (*devtool_set_inviter_commits_first)(bool inviter_commited_first);
125 /// Set the meta-connection status callback.
126 /** This functions sets the callback that is called whenever a meta-connection is made or closed.
127 * The callback is run in MeshLink's own thread.
128 * It is therefore important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
129 * to hand the data over to the application's thread.
130 * The callback should also not block itself and return as quickly as possible.
132 * \memberof meshlink_handle
133 * @param mesh A handle which represents an instance of MeshLink.
134 * @param cb A pointer to the function which will be called when a node's meta-connection status changes.
135 * If a NULL pointer is given, the callback will be disabled.
137 void devtool_set_meta_status_cb(struct meshlink_handle *mesh, meshlink_node_status_cb_t cb);