2 This file is part of GNUnet.
3 Copyright (C) 2013 Christian Grothoff (and other contributing authors)
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 * DV service API (should only be used by the DV plugin)
27 * @defgroup dv DV service
28 * Distance vector routing
30 * The DV service API should only be used by the DV plugin.
33 #ifndef GNUNET_SERVICE_DV_H
34 #define GNUNET_SERVICE_DV_H
36 #include "gnunet_util_lib.h"
37 #include "gnunet_ats_service.h"
40 * Signature of a function to be called if DV
41 * starts to be able to talk to a peer.
44 * @param peer newly connected peer
45 * @param distance distance to the peer
46 * @param network the peer is located in
48 typedef void (*GNUNET_DV_ConnectCallback)(void *cls,
49 const struct GNUNET_PeerIdentity *peer,
51 enum GNUNET_ATS_Network_Type network);
55 * Signature of a function to be called if DV
56 * distance to a peer is changed.
59 * @param peer connected peer
60 * @param distance new distance to the peer
61 * @param network this network will be used to reach the next hop
63 typedef void (*GNUNET_DV_DistanceChangedCallback)(void *cls,
64 const struct GNUNET_PeerIdentity *peer,
66 enum GNUNET_ATS_Network_Type network);
70 * Signature of a function to be called if DV
71 * is no longer able to talk to a peer.
74 * @param peer peer that disconnected
76 typedef void (*GNUNET_DV_DisconnectCallback)(void *cls,
77 const struct GNUNET_PeerIdentity *peer);
81 * Signature of a function to be called if DV
82 * receives a message for this peer.
85 * @param sender sender of the message
86 * @param distance how far did the message travel
87 * @param msg actual message payload
89 typedef void (*GNUNET_DV_MessageReceivedCallback)(void *cls,
90 const struct GNUNET_PeerIdentity *sender,
92 const struct GNUNET_MessageHeader *msg);
96 * Signature of a function called once the delivery of a
97 * message has been successful.
100 * @param ok GNUNET_OK on success, GNUNET_SYSERR on error
102 typedef void (*GNUNET_DV_MessageSentCallback)(void *cls,
107 * Handle to the DV service.
109 struct GNUNET_DV_ServiceHandle;
113 * Connect to the DV service.
115 * @param cfg configuration
116 * @param cls closure for callbacks
117 * @param connect_cb function to call on connects
118 * @param distance_cb function to call if distances change
119 * @param disconnect_cb function to call on disconnects
120 * @param message_cb function to call if we receive messages
121 * @return handle to access the service
123 struct GNUNET_DV_ServiceHandle *
124 GNUNET_DV_service_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
126 GNUNET_DV_ConnectCallback connect_cb,
127 GNUNET_DV_DistanceChangedCallback distance_cb,
128 GNUNET_DV_DisconnectCallback disconnect_cb,
129 GNUNET_DV_MessageReceivedCallback message_cb);
133 * Disconnect from DV service.
135 * @param sh service handle
138 GNUNET_DV_service_disconnect (struct GNUNET_DV_ServiceHandle *sh);
142 * Handle for a send operation.
144 struct GNUNET_DV_TransmitHandle;
148 * Send a message via DV service.
150 * @param sh service handle
151 * @param target intended recpient
152 * @param msg message payload
153 * @param cb function to invoke when done
154 * @param cb_cls closure for 'cb'
155 * @return handle to cancel the operation
157 struct GNUNET_DV_TransmitHandle *
158 GNUNET_DV_send (struct GNUNET_DV_ServiceHandle *sh,
159 const struct GNUNET_PeerIdentity *target,
160 const struct GNUNET_MessageHeader *msg,
161 GNUNET_DV_MessageSentCallback cb,
166 * Abort send operation (naturally, the message may have
167 * already been transmitted; this only stops the 'cb'
168 * from being called again).
170 * @param th send operation to cancel
173 GNUNET_DV_send_cancel (struct GNUNET_DV_TransmitHandle *th);
175 /** @} */ /* end of group */