2 This file is part of GNUnet.
3 Copyright (C) 2009-2016 GNUnet e.V.
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.
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.
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.
22 * @author Christian Grothoff
25 * Monitoring / diagnostics API for the transport service
27 * @defgroup transport TRANSPORT service
28 * Communication with other peers
30 * @see [Documentation](https://gnunet.org/transport-service)
35 #ifndef GNUNET_TRANSPORT_MONITOR_SERVICE_H
36 #define GNUNET_TRANSPORT_MONITOR_SERVICE_H
41 #if 0 /* keep Emacsens' auto-indent happy */
46 #include "gnunet_util_lib.h"
49 * Version number of the transport API.
51 #define GNUNET_TRANSPORT_MONITOR_VERSION 0x00000000
55 * Information about another peer's address.
57 struct GNUNET_TRANSPORT_MonitorInformation
61 * Address we have for the peer, human-readable, 0-terminated, in UTF-8.
66 * Network type of the address.
68 enum GNUNET_ATS_Network_Type nt;
71 * #GNUNET_YES if this is an inbound connection (communicator initiated)
72 * #GNUNET_NO if this is an outbound connection (transport initiated)
77 * Number of messages pending transmission for this @e address.
79 uint32_t num_msg_pending;
82 * Number of bytes pending transmission for this @e address.
84 uint32_t num_bytes_pending;
87 * When was this address last validated.
89 struct GNUNET_TIME_Absolute last_validation;
92 * When does this address expire.
94 struct GNUNET_TIME_Absolute valid_until;
97 * Time of the next validation operation.
99 struct GNUNET_TIME_Absolute next_validation;
102 * Current estimate of the RTT.
104 struct GNUNET_TIME_Relative rtt;
110 * Function to call with information about a peer.
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.
116 * The #GNUNET_TRANSPORT_monitor_peers_cancel() call MUST not be called from
117 * within this function!
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
126 (*GNUNET_TRANSPORT_MontiorCallback) (void *cls,
127 const struct GNUNET_PeerIdentity *peer,
128 const struct GNUNET_TRANSPORT_MonitorInformation *mi);
132 * Handle for a #GNUNET_TRANSPORT_monitor() operation.
134 struct GNUNET_TRANSPORT_MonitorContext;
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
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.
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.
152 * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the
155 * @param cfg configuration to use
156 * @param peer a specific peer identity to obtain information for,
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
163 struct GNUNET_TRANSPORT_MonitorContext *
164 GNUNET_TRANSPORT_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg,
165 const struct GNUNET_PeerIdentity *peer,
167 GNUNET_TRANSPORT_MonitorCallback mc,
172 * Cancel request to monitor peers
174 * @param pmc handle for the request to cancel
177 GNUNET_TRANSPORT_monitor_cancel (struct GNUNET_TRANSPORT_MonitorContext *pmc);
180 #if 0 /* keep Emacsens' auto-indent happy */
187 /* ifndef GNUNET_TRANSPORT_MONITOR_SERVICE_H */
190 /** @} */ /* end of group */
192 /* end of gnunet_transport_monitor_service.h */