git.meshlink.io Git - meshlink/blob - 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         uint32_t options;               ///< Edge options. @TODO what are edge options?
  45         int weight;                     ///< Weight assigned to this edge.
  46 };
  47
  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().
  54  *
  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  *                      return 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.
  74  */
  75 extern devtool_edge_t *devtool_get_all_edges(meshlink_handle_t *mesh, devtool_edge_t *edges, size_t *nmemb);
  76
  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.
  80  *
  81  *  @return             True in case of success, false otherwise.
  82  */
  83 extern bool devtool_export_json_all_edges_state(meshlink_handle_t *mesh, FILE *stream);
  84
  85 /// The status of a node.
  86 typedef struct devtool_node_status devtool_node_status_t;
  87
  88 /// The status of a node.
  89 struct devtool_node_status {
  90         uint32_t options;
  91         uint32_t status;
  92         struct sockaddr_storage address;
  93         uint16_t mtu;
  94         uint16_t minmtu;
  95         uint16_t maxmtu;
  96         int mtuprobes;
  97         enum {
  98                 DEVTOOL_UDP_FAILED = -2,     /// UDP tried but failed
  99                 DEVTOOL_UDP_IMPOSSIBLE = -1, /// UDP not possible (node unreachable)
 100                 DEVTOOL_UDP_UNKNOWN = 0,     /// UDP status not known (never tried to communicate with the node)
 101                 DEVTOOL_UDP_TRYING,          /// UDP detection in progress
 102                 DEVTOOL_UDP_WORKING,         /// UDP communication established
 103         } udp_status;
 104         uint64_t in_packets;
 105         uint64_t in_bytes;
 106         uint64_t out_packets;
 107         uint64_t out_bytes;
 108 };
 109
 110 /// Get the status of a node.
 111 /** This function returns a struct containing extra information about a node.
 112  *  The information is a snapshot taken at call time.
 113  *
 114  *  @param mesh         A handle which represents an instance of MeshLink.
 115  *  @param node         A pointer to a meshlink_node_t.
 116  *  @param status       A pointer to a devtools_node_status_t variable that has
 117  *                      to be provided by the caller.
 118  *                      The contents of this variable will be changed to reflect
 119  *                      the current status of the node.
 120  */
 121 extern void devtool_get_node_status(meshlink_handle_t *mesh, meshlink_node_t *node, devtool_node_status_t *status);
 122
 123 /// Get the list of all submeshes of a meshlink instance.
 124 /** This function returns an array of submesh handles.
 125  *  These pointers are the same pointers that are present in the submeshes list
 126  *  in mesh handle.
 127  *
 128  *  @param mesh         A handle which represents an instance of MeshLink.
 129  *  @param submeshes    A pointer to an array of submesh handles if any allocated previously.
 130  *  @param nmemb        A pointer to a size_t variable that has
 131  *                      to be provided by the caller.
 132  *                      The contents of this variable will be changed to indicate
 133  *                      the number if array elements.
 134  */
 135 extern meshlink_submesh_t **devtool_get_all_submeshes(meshlink_handle_t *mesh, meshlink_submesh_t **submeshes, size_t *nmemb);
 136
 137 /// Open a MeshLink instance in a given network namespace.
 138 /** This function opens MeshLink in the given network namespace.
 139  *
 140  *  @param confbase The directory in which MeshLink will store its configuration files.
 141  *                  After the function returns, the application is free to overwrite or free @a confbase @a.
 142  *  @param name     The name which this instance of the application will use in the mesh.
 143  *                  After the function returns, the application is free to overwrite or free @a name @a.
 144  *  @param appname  The application name which will be used in the mesh.
 145  *                  After the function returns, the application is free to overwrite or free @a name @a.
 146  *  @param devclass The device class which will be used in the mesh.
 147  *  @param netns    A filedescriptor that represents the network namespace.
 148  *
 149  *  @return         A pointer to a meshlink_handle_t which represents this instance of MeshLink, or NULL in case of an error.
 150  *                  The pointer is valid until meshlink_close() is called.
 151  */
 152 extern meshlink_handle_t *devtool_open_in_netns(const char *confbase, const char *name, const char *appname, dev_class_t devclass, int netns);
 153
 154 /// Debug function pointer variable for set port API
 155 /** This function pointer variable is a userspace tracepoint or debugger callback for
 156  *  set port function @a meshlink_set_port @a.
 157  *  On assigning a debug function variable invokes callback when try_bind() succeeds in meshlink_set_port API.
 158  *
 159  */
 160 extern void (*devtool_trybind_probe)(void);
 161
 162 /// Debug function pointer variable for encrypted key rotate API
 163 /** This function pointer variable is a userspace tracepoint or debugger callback for
 164  *  encrypted key rotation function @a meshlink_encrypted_key_rotate @a.
 165  *  On assigning a debug function variable invokes callback for each stage from the key rotate API.
 166  *
 167  *  @param stage Debug stage number.
 168  */
 169 extern void (*devtool_keyrotate_probe)(int stage);
 170
 171 #endif