summaryrefslogtreecommitdiff
path: root/src/include/gnunet_dv_service.h
blob: aa8d6af61353c5faed16117a80265a3bfcac1057 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
/*
     This file is part of GNUnet.
     Copyright (C) 2013, 2016 GNUnet e.V.

     GNUnet is free software: you can redistribute it and/or modify it
     under the terms of the GNU Affero General Public License as published
     by the Free Software Foundation, either version 3 of the License,
     or (at your option) any later version.

     GNUnet is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Affero General Public License for more details.
    
     You should have received a copy of the GNU Affero General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/**
 * @author Christian Grothoff
 *
 * @file
 * DV service API (should only be used by the DV plugin)
 *
 * @defgroup dv  DV service
 * Distance Vector routing
 *
 * The DV service API should only be used by the DV plugin.
 * @{
 */
#ifndef GNUNET_SERVICE_DV_H
#define GNUNET_SERVICE_DV_H

#include "gnunet_util_lib.h"
#include "gnunet_ats_service.h"

/**
 * Signature of a function to be called if DV
 * starts to be able to talk to a peer.
 *
 * @param cls closure
 * @param peer newly connected peer
 * @param distance distance to the peer
 * @param network the peer is located in
 */
typedef void
(*GNUNET_DV_ConnectCallback)(void *cls,
                             const struct GNUNET_PeerIdentity *peer,
                             uint32_t distance,
                             enum GNUNET_ATS_Network_Type network);


/**
 * Signature of a function to be called if DV
 * distance to a peer is changed.
 *
 * @param cls closure
 * @param peer connected peer
 * @param distance new distance to the peer
 * @param network this network will be used to reach the next hop
 */
typedef void
(*GNUNET_DV_DistanceChangedCallback)(void *cls,
                                     const struct GNUNET_PeerIdentity *peer,
                                     uint32_t distance,
                                     enum GNUNET_ATS_Network_Type network);


/**
 * Signature of a function to be called if DV
 * is no longer able to talk to a peer.
 *
 * @param cls closure
 * @param peer peer that disconnected
 */
typedef void
(*GNUNET_DV_DisconnectCallback)(void *cls,
                                const struct GNUNET_PeerIdentity *peer);


/**
 * Signature of a function to be called if DV
 * receives a message for this peer.
 *
 * @param cls closure
 * @param sender sender of the message
 * @param distance how far did the message travel
 * @param msg actual message payload
 */
typedef void
(*GNUNET_DV_MessageReceivedCallback)(void *cls,
                                     const struct GNUNET_PeerIdentity *sender,
                                     uint32_t distance,
                                     const struct GNUNET_MessageHeader *msg);


/**
 * Signature of a function called once the delivery of a
 * message has been successful.
 *
 * @param cls closure
 */
typedef void
(*GNUNET_DV_MessageSentCallback)(void *cls);


/**
 * Handle to the DV service.
 */
struct GNUNET_DV_ServiceHandle;


/**
 * Connect to the DV service.
 *
 * @param cfg configuration
 * @param cls closure for callbacks
 * @param connect_cb function to call on connects
 * @param distance_cb function to call if distances change
 * @param disconnect_cb function to call on disconnects
 * @param message_cb function to call if we receive messages
 * @return handle to access the service
 */
struct GNUNET_DV_ServiceHandle *
GNUNET_DV_service_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
			   void *cls,
			   GNUNET_DV_ConnectCallback connect_cb,
			   GNUNET_DV_DistanceChangedCallback distance_cb,
			   GNUNET_DV_DisconnectCallback disconnect_cb,
			   GNUNET_DV_MessageReceivedCallback message_cb);


/**
 * Disconnect from DV service.
 *
 * @param sh service handle
 */
void
GNUNET_DV_service_disconnect (struct GNUNET_DV_ServiceHandle *sh);


/**
 * Handle for a send operation.
 */
struct GNUNET_DV_TransmitHandle;


/**
 * Send a message via DV service.
 *
 * @param sh service handle
 * @param target intended recpient
 * @param msg message payload
 * @return handle to cancel the operation
 */
void
GNUNET_DV_send (struct GNUNET_DV_ServiceHandle *sh,
		const struct GNUNET_PeerIdentity *target,
		const struct GNUNET_MessageHeader *msg);


#endif

/** @} */  /* end of group */