src/include/gnunet_transport_monitor_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2016 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Monitoring / diagnostics API for the transport service
  26  *
  27  * @defgroup transport TRANSPORT service
  28  * Communication with other peers
  29  *
  30  * @see [Documentation](https://gnunet.org/transport-service)
  31  *
  32  * @{
  33  */
  34
  35 #ifndef GNUNET_TRANSPORT_MONITOR_SERVICE_H
  36 #define GNUNET_TRANSPORT_MONITOR_SERVICE_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 #include "gnunet_util_lib.h"
  47
  48 /**
  49  * Version number of the transport API.
  50  */
  51 #define GNUNET_TRANSPORT_MONITOR_VERSION 0x00000000
  52
  53
  54 /**
  55  * Information about another peer's address.
  56  */
  57 struct GNUNET_TRANSPORT_MonitorInformation
  58 {
  59
  60   /**
  61    * Address we have for the peer, human-readable, 0-terminated, in UTF-8.
  62    */
  63   const char *address;
  64
  65   /**
  66    * Network type of the address.
  67    */
  68   enum GNUNET_ATS_Network_Type nt;
  69
  70   /**
  71    * #GNUNET_YES if this is an inbound connection (communicator initiated)
  72    * #GNUNET_NO if this is an outbound connection (transport initiated)
  73    */
  74   int is_inbound;
  75
  76   /**
  77    * Number of messages pending transmission for this @e address.
  78    */
  79   uint32_t num_msg_pending;
  80
  81   /**
  82    * Number of bytes pending transmission for this @e address.
  83    */
  84   uint32_t num_bytes_pending;
  85
  86   /**
  87    * When was this address last validated.
  88    */
  89   struct GNUNET_TIME_Absolute last_validation;
  90
  91   /**
  92    * When does this address expire.
  93    */
  94   struct GNUNET_TIME_Absolute valid_until;
  95
  96   /**
  97    * Time of the next validation operation.
  98    */
  99   struct GNUNET_TIME_Absolute next_validation;
 100
 101   /**
 102    * Current estimate of the RTT.
 103    */
 104   struct GNUNET_TIME_Relative rtt;
 105
 106 };
 107
 108
 109 /**
 110  * Function to call with information about a peer.
 111  *
 112  * If one_shot was set to #GNUNET_YES to iterate over all peers once,
 113  * a final call with NULL for peer and address will follow when done.
 114  * In this case state and timeout do not contain valid values.
 115  *
 116  * The #GNUNET_TRANSPORT_monitor_peers_cancel() call MUST not be called from
 117  * within this function!
 118  *
 119  *
 120  * @param cls closure
 121  * @param peer peer this update is about,
 122  *        NULL if this is the final last callback for a iteration operation
 123  * @param mi monitoring data on the peer
 124  */
 125 typedef void
 126 (*GNUNET_TRANSPORT_MontiorCallback) (void *cls,
 127                                      const struct GNUNET_PeerIdentity *peer,
 128                                      const struct GNUNET_TRANSPORT_MonitorInformation *mi);
 129
 130
 131 /**
 132  * Handle for a #GNUNET_TRANSPORT_monitor() operation.
 133  */
 134 struct GNUNET_TRANSPORT_MonitorContext;
 135
 136
 137 /**
 138  * Return information about a specific peer or all peers currently known to
 139  * transport service once or in monitoring mode. To obtain information about
 140  * a specific peer, a peer identity can be passed. To obtain information about
 141  * all peers currently known to transport service, NULL can be passed as peer
 142  * identity.
 143  *
 144  * For each peer, the callback is called with information about the address used
 145  * to communicate with this peer, the state this peer is currently in and the
 146  * the current timeout for this state.
 147  *
 148  * Upon completion, the #GNUNET_TRANSPORT_PeerIterateCallback is called one
 149  * more time with `NULL`. After this, the operation must no longer be
 150  * explicitly canceled.
 151  *
 152  * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the
 153  * the peer_callback!
 154  *
 155  * @param cfg configuration to use
 156  * @param peer a specific peer identity to obtain information for,
 157  *      NULL for all peers
 158  * @param one_shot #GNUNET_YES to return the current state and then end (with NULL+NULL),
 159  *                 #GNUNET_NO to monitor peers continuously
 160  * @param mc function to call with the results
 161  * @param mc_cls closure for @a mc
 162  */
 163 struct GNUNET_TRANSPORT_MonitorContext *
 164 GNUNET_TRANSPORT_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg,
 165                           const struct GNUNET_PeerIdentity *peer,
 166                           int one_shot,
 167                           GNUNET_TRANSPORT_MonitorCallback mc,
 168                           void *mc_cls);
 169
 170
 171 /**
 172  * Cancel request to monitor peers
 173  *
 174  * @param pmc handle for the request to cancel
 175  */
 176 void
 177 GNUNET_TRANSPORT_monitor_cancel (struct GNUNET_TRANSPORT_MonitorContext *pmc);
 178
 179
 180 #if 0                           /* keep Emacsens' auto-indent happy */
 181 {
 182 #endif
 183 #ifdef __cplusplus
 184 }
 185 #endif
 186
 187 /* ifndef GNUNET_TRANSPORT_MONITOR_SERVICE_H */
 188 #endif
 189
 190 /** @} */  /* end of group */
 191
 192 /* end of gnunet_transport_monitor_service.h */