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 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.
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.
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/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
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)
34 #ifndef GNUNET_TRANSPORT_MONITOR_SERVICE_H
35 #define GNUNET_TRANSPORT_MONITOR_SERVICE_H
40 #if 0 /* keep Emacsens' auto-indent happy */
45 #include "gnunet_util_lib.h"
46 #include "gnunet_ats_transport_service.h"
47 #include "gnunet_transport_communication_service.h"
51 * Version number of the transport API.
53 #define GNUNET_TRANSPORT_MONITOR_VERSION 0x00000000
57 * Information about another peer's address.
59 struct GNUNET_TRANSPORT_MonitorInformation
63 * Address we have for the peer, human-readable, 0-terminated, in UTF-8.
68 * Network type of the address.
70 enum GNUNET_NetworkType nt;
75 enum GNUNET_TRANSPORT_ConnectionStatus cs;
78 * Number of messages pending transmission for this @e address.
80 uint32_t num_msg_pending;
83 * Number of bytes pending transmission for this @e address.
85 uint32_t num_bytes_pending;
88 * When was this address last validated.
90 struct GNUNET_TIME_Absolute last_validation;
93 * When does this address expire.
95 struct GNUNET_TIME_Absolute valid_until;
98 * Time of the next validation operation.
100 struct GNUNET_TIME_Absolute next_validation;
103 * Current estimate of the RTT.
105 struct GNUNET_TIME_Relative rtt;
111 * Function to call with information about a peer.
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.
117 * The #GNUNET_TRANSPORT_monitor_peers_cancel() call MUST not be called from
118 * within this function!
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
127 (*GNUNET_TRANSPORT_MonitorCallback) (void *cls,
128 const struct GNUNET_PeerIdentity *peer,
129 const struct GNUNET_TRANSPORT_MonitorInformation *mi);
133 * Handle for a #GNUNET_TRANSPORT_monitor() operation.
135 struct GNUNET_TRANSPORT_MonitorContext;
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
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.
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.
153 * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the
156 * @param cfg configuration to use
157 * @param peer a specific peer identity to obtain information for,
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
164 struct GNUNET_TRANSPORT_MonitorContext *
165 GNUNET_TRANSPORT_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg,
166 const struct GNUNET_PeerIdentity *peer,
168 GNUNET_TRANSPORT_MonitorCallback cb,
173 * Cancel request to monitor peers
175 * @param mc handle for the request to cancel
178 GNUNET_TRANSPORT_monitor_cancel (struct GNUNET_TRANSPORT_MonitorContext *mc);
181 #if 0 /* keep Emacsens' auto-indent happy */
188 /* ifndef GNUNET_TRANSPORT_MONITOR_SERVICE_H */
191 /** @} */ /* end of group */
193 /* end of gnunet_transport_monitor_service.h */