X-Git-Url: http://git.meshlink.io/?p=meshlink;a=blobdiff_plain;f=src%2Fdevtools.h;h=6d0b4989c3ce32c18c124faf8bef9219794ba712;hp=53755187601362975058d8eac81679fbf9e16d9c;hb=963c5055505f2fc117cd5efa06eaa02c9b2bf85d;hpb=61d9b04f66055e61f0afdf8955ff890f4da39288 diff --git a/src/devtools.h b/src/devtools.h index 53755187..6d0b4989 100644 --- a/src/devtools.h +++ b/src/devtools.h @@ -20,6 +20,160 @@ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -extern bool devtool_export_json_all_edges_state(meshlink_handle_t *mesh, FILE* stream); +/// \file devtools.h +/** This header files declares functions that are only intended for debugging and quality control. + * They are not necessary for the normal operation of MeshLink. + * Applications should not depend on any of these functions for their normal operation. + */ + +/// An edge in the MeshLink network. +typedef struct devtool_edge devtool_edge_t; + +/// An edge in the MeshLink network. +struct devtool_edge { + 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. + int weight; ///< Weight assigned to this edge. +}; + +/// Get a list of edges. +/** This function returns an array with copies of all known bidirectional edges. + * The edges are copied to capture the mesh state at call time, since edges + * mutate frequently. The nodes pointed to within the devtool_edge_t type + * are not copies; these are the same pointers that one would get from a call + * to meshlink_get_all_nodes(). + * + * @param mesh A handle which represents an instance of MeshLink. + * @param edges A pointer to a previously allocated array of + * devtool_edge_t, or NULL in which case MeshLink will + * allocate a new array. + * The application is allowed to call free() on the array whenever it wishes. + * The pointers in the devtool_edge_t elements are valid until + * meshlink_close() is called. + * @param nmemb A pointer to a variable holding the number of elements that + * are stored in the array. In case the @a edges @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 devtool_edge_t elements, + * or NULL in case of an error. + * If the @a edges @a argument was not NULL, then the + * return 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. + */ +extern devtool_edge_t *devtool_get_all_edges(meshlink_handle_t *mesh, devtool_edge_t *edges, size_t *nmemb); + +/// Export a list of edges to a file in JSON format. +/* @param mesh A handle which represents an instance of MeshLink. + * @param FILE An open file descriptor to which a JSON representation of the edges will be written. + * + * @return True in case of success, false otherwise. + */ +extern bool devtool_export_json_all_edges_state(meshlink_handle_t *mesh, FILE *stream); + +/// The status of a node. +typedef struct devtool_node_status devtool_node_status_t; + +/// The status of a node. +struct devtool_node_status { + uint32_t status; + struct sockaddr_storage address; + uint16_t mtu; + uint16_t minmtu; + uint16_t maxmtu; + int mtuprobes; + enum { + DEVTOOL_UDP_FAILED = -2, /// UDP tried but failed + DEVTOOL_UDP_IMPOSSIBLE = -1, /// UDP not possible (node unreachable) + DEVTOOL_UDP_UNKNOWN = 0, /// UDP status not known (never tried to communicate with the node) + DEVTOOL_UDP_TRYING, /// UDP detection in progress + DEVTOOL_UDP_WORKING, /// UDP communication established + } udp_status; + uint64_t in_packets; + uint64_t in_bytes; + uint64_t out_packets; + uint64_t out_bytes; +}; + +/// Get the status of a node. +/** This function returns a struct containing extra information about a node. + * The information is a snapshot taken at call time. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param node A pointer to a meshlink_node_t. + * @param status A pointer to a devtools_node_status_t variable that has + * to be provided by the caller. + * The contents of this variable will be changed to reflect + * the current status of the node. + */ +extern void devtool_get_node_status(meshlink_handle_t *mesh, meshlink_node_t *node, devtool_node_status_t *status); + +/// Get the list of all submeshes of a meshlink instance. +/** This function returns an array of submesh handles. + * These pointers are the same pointers that are present in the submeshes list + * in mesh handle. + * + * @param mesh A handle which represents an instance of MeshLink. + * @param submeshes A pointer to an array of submesh handles if any allocated previously. + * @param nmemb A pointer to a size_t variable that has + * to be provided by the caller. + * The contents of this variable will be changed to indicate + * the number if array elements. + */ +extern meshlink_submesh_t **devtool_get_all_submeshes(meshlink_handle_t *mesh, meshlink_submesh_t **submeshes, size_t *nmemb); + +/// Open a MeshLink instance in a given network namespace. +/** This function opens MeshLink in the given network namespace. + * + * @param confbase The directory in which MeshLink will store its configuration files. + * After the function returns, the application is free to overwrite or free @a confbase @a. + * @param name The name which this instance of the application will use in the mesh. + * After the function returns, the application is free to overwrite or free @a name @a. + * @param appname The application name which will be used in the mesh. + * After the function returns, the application is free to overwrite or free @a name @a. + * @param devclass The device class which will be used in the mesh. + * @param netns A filedescriptor that represents the network namespace. + * + * @return A pointer to a meshlink_handle_t which represents this instance of MeshLink, or NULL in case of an error. + * The pointer is valid until meshlink_close() is called. + */ +extern meshlink_handle_t *devtool_open_in_netns(const char *confbase, const char *name, const char *appname, dev_class_t devclass, int netns); + +/// Debug function pointer variable for set port API +/** This function pointer variable is a userspace tracepoint or debugger callback for + * set port function @a meshlink_set_port @a. + * On assigning a debug function variable invokes callback when try_bind() succeeds in meshlink_set_port API. + * + */ +extern void (*devtool_trybind_probe)(void); + +/// Debug function pointer variable for encrypted key rotate API +/** This function pointer variable is a userspace tracepoint or debugger callback for + * encrypted key rotation function @a meshlink_encrypted_key_rotate @a. + * On assigning a debug function variable invokes callback for each stage from the key rotate API. + * + * @param stage Debug stage number. + */ +extern void (*devtool_keyrotate_probe)(int stage); + +/// Debug function pointer variable for asserting inviter/invitee committing sequence +/** This function pointer variable is a userspace tracepoint or debugger callback which + * invokes either after inviter writing invitees host file into the disk + * or after invitee writing it's main config file and host config files that inviter sent into + * the disk. + * + * @param inviter_commited_first true if inviter committed first else false if invitee committed first the other host file into the disk. + */ +extern void (*devtool_set_inviter_commits_first)(bool inviter_commited_first); #endif