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