git.meshlink.io Git - meshlink-tiny/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 /// The status of a node.
  30 typedef struct devtool_node_status devtool_node_status_t;
  31
  32 /// The status of a node.
  33 struct devtool_node_status {
  34         uint32_t status;
  35         uint16_t mtu;
  36         uint16_t minmtu;
  37         uint16_t maxmtu;
  38         int mtuprobes;
  39         enum {
  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
  45         } udp_status;
  46         uint64_t in_packets;
  47         uint64_t in_bytes;
  48         uint64_t out_packets;
  49         uint64_t out_bytes;
  50 };
  51
  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.
  55  *
  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.
  62  */
  63 void devtool_get_node_status(meshlink_handle_t *mesh, meshlink_node_t *node, devtool_node_status_t *status);
  64
  65 /// Open a MeshLink instance in a given network namespace.
  66 /** This function opens MeshLink in the given network namespace.
  67  *
  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.
  76  *
  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.
  79  */
  80 meshlink_handle_t *devtool_open_in_netns(const char *confbase, const char *name, const char *appname, dev_class_t devclass, int netns);
  81
  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.
  86  *
  87  */
  88 extern void (*devtool_trybind_probe)(void);
  89
  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.
  94  *
  95  *  @param stage Debug stage number.
  96  */
  97 extern void (*devtool_keyrotate_probe)(int stage);
  98
  99 /// Debug function pointer variable for SPTPS key renewal
 100 /** This function pointer variable is a userspace tracepoint or debugger callback for
 101  *  SPTPS key renewal.
 102  *
 103  *  @param node The node whose SPTPS key(s) are being renewed
 104  */
 105 extern void (*devtool_sptps_renewal_probe)(meshlink_node_t *node);
 106
 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.
 109  *
 110  *  @param mesh A handle which represents an instance of MeshLink.
 111  *  @param node The node whose SPTPS key(s) should be renewed
 112  */
 113 void devtool_force_sptps_renewal(meshlink_handle_t *mesh, meshlink_node_t *node);
 114
 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
 119  *  the disk.
 120  *
 121  *  @param inviter_commited_first       true if inviter committed first else false if invitee committed first the other host file into the disk.
 122  */
 123 extern void (*devtool_set_inviter_commits_first)(bool inviter_commited_first);
 124
 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.
 131  *
 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.
 136  */
 137 void devtool_set_meta_status_cb(struct meshlink_handle *mesh, meshlink_node_status_cb_t cb);
 138
 139 #endif