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