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