diff options
Diffstat (limited to 'src/include/gnunet_transport_service.h')
-rw-r--r-- | src/include/gnunet_transport_service.h | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h new file mode 100644 index 000000000..25ca388a7 --- /dev/null +++ b/src/include/gnunet_transport_service.h | |||
@@ -0,0 +1,241 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | (C) 2009 Christian Grothoff (and other contributing authors) | ||
4 | |||
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 2, or (at your | ||
8 | 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 | General Public License for more details. | ||
14 | |||
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., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file include/gnunet_transport_service.h | ||
23 | * @brief low-level P2P IO | ||
24 | * @author Christian Grothoff | ||
25 | */ | ||
26 | |||
27 | #ifndef GNUNET_TRANSPORT_SERVICE_H | ||
28 | #define GNUNET_TRANSPORT_SERVICE_H | ||
29 | |||
30 | #ifdef __cplusplus | ||
31 | extern "C" | ||
32 | { | ||
33 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
34 | } | ||
35 | #endif | ||
36 | #endif | ||
37 | |||
38 | #include "gnunet_configuration_lib.h" | ||
39 | #include "gnunet_crypto_lib.h" | ||
40 | #include "gnunet_network_lib.h" | ||
41 | #include "gnunet_scheduler_lib.h" | ||
42 | #include "gnunet_time_lib.h" | ||
43 | |||
44 | /** | ||
45 | * Version number of the transport API. | ||
46 | */ | ||
47 | #define GNUNET_TRANSPORT_VERSION 0x00000000 | ||
48 | |||
49 | /** | ||
50 | * Function called by the transport for each received message. | ||
51 | * | ||
52 | * @param cls closure | ||
53 | * @param latency estimated latency for communicating with the | ||
54 | * given peer | ||
55 | * @param peer (claimed) identity of the other peer | ||
56 | * @param message the message | ||
57 | */ | ||
58 | typedef void (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls, | ||
59 | struct GNUNET_TIME_Relative | ||
60 | latency, | ||
61 | const struct | ||
62 | GNUNET_PeerIdentity * peer, | ||
63 | const struct | ||
64 | GNUNET_MessageHeader * | ||
65 | message); | ||
66 | |||
67 | |||
68 | /** | ||
69 | * Opaque handle to the service. | ||
70 | */ | ||
71 | struct GNUNET_TRANSPORT_Handle; | ||
72 | |||
73 | |||
74 | /** | ||
75 | * Function called to notify transport users that another | ||
76 | * peer connected to us. | ||
77 | * | ||
78 | * @param cls closure | ||
79 | * @param peer the peer that connected | ||
80 | * @param latency current latency of the connection | ||
81 | */ | ||
82 | typedef void | ||
83 | (*GNUNET_TRANSPORT_NotifyConnect) (void *cls, | ||
84 | const struct GNUNET_PeerIdentity * peer, | ||
85 | struct GNUNET_TIME_Relative latency); | ||
86 | |||
87 | /** | ||
88 | * Function called to notify transport users that another | ||
89 | * peer disconnected from us. | ||
90 | * | ||
91 | * @param cls closure | ||
92 | * @param peer the peer that disconnected | ||
93 | */ | ||
94 | typedef void | ||
95 | (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls, | ||
96 | const struct GNUNET_PeerIdentity * | ||
97 | peer); | ||
98 | |||
99 | |||
100 | /** | ||
101 | * Connect to the transport service. Note that the connection may | ||
102 | * complete (or fail) asynchronously. | ||
103 | * | ||
104 | * @param sched scheduler to use | ||
105 | * @param cfg configuration to use | ||
106 | * @param cls closure for the callbacks | ||
107 | * @param rec receive function to call | ||
108 | * @param nc function to call on connect events | ||
109 | * @param dc function to call on disconnect events | ||
110 | */ | ||
111 | struct GNUNET_TRANSPORT_Handle *GNUNET_TRANSPORT_connect (struct | ||
112 | GNUNET_SCHEDULER_Handle | ||
113 | *sched, | ||
114 | struct | ||
115 | GNUNET_CONFIGURATION_Handle | ||
116 | *cfg, void *cls, | ||
117 | GNUNET_TRANSPORT_ReceiveCallback | ||
118 | rec, | ||
119 | GNUNET_TRANSPORT_NotifyConnect | ||
120 | nc, | ||
121 | GNUNET_TRANSPORT_NotifyDisconnect | ||
122 | nd); | ||
123 | |||
124 | |||
125 | /** | ||
126 | * Disconnect from the transport service. | ||
127 | */ | ||
128 | void GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle); | ||
129 | |||
130 | |||
131 | /** | ||
132 | * Set the share of incoming/outgoing bandwidth for the given | ||
133 | * peer to the specified amount. | ||
134 | * | ||
135 | * @param handle connection to transport service | ||
136 | * @param target who's bandwidth quota is being changed | ||
137 | * @param quota_in incoming bandwidth quota in bytes per ms; 0 can | ||
138 | * be used to force all traffic to be discarded | ||
139 | * @param quota_out outgoing bandwidth quota in bytes per ms; 0 can | ||
140 | * be used to force all traffic to be discarded | ||
141 | * @param timeout how long to wait until signaling failure if | ||
142 | * we can not communicate the quota change | ||
143 | * @param cont continuation to call when done, will be called | ||
144 | * either with reason "TIMEOUT" or with reason "PREREQ_DONE" | ||
145 | * @param cont_cls closure for continuation | ||
146 | */ | ||
147 | void | ||
148 | GNUNET_TRANSPORT_set_quota (struct GNUNET_TRANSPORT_Handle *handle, | ||
149 | const struct GNUNET_PeerIdentity *target, | ||
150 | uint32_t quota_in, | ||
151 | uint32_t quota_out, | ||
152 | struct GNUNET_TIME_Relative timeout, | ||
153 | GNUNET_SCHEDULER_Task cont, void *cont_cls); | ||
154 | |||
155 | |||
156 | /** | ||
157 | * Opaque handle for a transmission-ready request. | ||
158 | */ | ||
159 | struct GNUNET_TRANSPORT_TransmitHandle; | ||
160 | |||
161 | |||
162 | /** | ||
163 | * Check if we could queue a message of the given size for | ||
164 | * transmission. The transport service will take both its | ||
165 | * internal buffers and bandwidth limits imposed by the | ||
166 | * other peer into consideration when answering this query. | ||
167 | * | ||
168 | * @param handle connection to transport service | ||
169 | * @param target who should receive the message | ||
170 | * @param size how big is the message we want to transmit? | ||
171 | * @param timeout after how long should we give up (and call | ||
172 | * notify with buf NULL and size 0)? | ||
173 | * @param notify function to call when we are ready to | ||
174 | * send such a message | ||
175 | * @param notify_cls closure for notify | ||
176 | * @return NULL if someone else is already waiting to be notified | ||
177 | * non-NULL if the notify callback was queued (can be used to cancel | ||
178 | * using GNUNET_TRANSPORT_notify_transmit_ready_cancel) | ||
179 | */ | ||
180 | struct GNUNET_TRANSPORT_TransmitHandle | ||
181 | *GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle | ||
182 | *handle, | ||
183 | const struct GNUNET_PeerIdentity | ||
184 | *target, size_t size, | ||
185 | struct GNUNET_TIME_Relative | ||
186 | timeout, | ||
187 | GNUNET_NETWORK_TransmitReadyNotify | ||
188 | notify, void *notify_cls); | ||
189 | |||
190 | |||
191 | /** | ||
192 | * Cancel the specified transmission-ready | ||
193 | * notification. | ||
194 | */ | ||
195 | void | ||
196 | GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct | ||
197 | GNUNET_TRANSPORT_TransmitHandle | ||
198 | *h); | ||
199 | |||
200 | |||
201 | /** | ||
202 | * Obtain the HELLO message for this peer. | ||
203 | * | ||
204 | * @param handle connection to transport service | ||
205 | * @param timeout how long to wait for the HELLO | ||
206 | * @param rec function to call with the HELLO, sender will be our peer | ||
207 | * identity; message and sender will be NULL on timeout | ||
208 | * (handshake with transport service pending/failed). | ||
209 | * cost estimate will be 0. | ||
210 | * @param rec_cls closure for rec | ||
211 | */ | ||
212 | void | ||
213 | GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle, | ||
214 | struct GNUNET_TIME_Relative timeout, | ||
215 | GNUNET_TRANSPORT_ReceiveCallback rec, | ||
216 | void *rec_cls); | ||
217 | |||
218 | |||
219 | /** | ||
220 | * Offer the transport service the HELLO of another peer. Note that | ||
221 | * the transport service may just ignore this message if the HELLO is | ||
222 | * malformed or useless due to our local configuration. | ||
223 | * | ||
224 | * @param handle connection to transport service | ||
225 | * @param hello the hello message | ||
226 | */ | ||
227 | void | ||
228 | GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle, | ||
229 | const struct GNUNET_MessageHeader *hello); | ||
230 | |||
231 | |||
232 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
233 | { | ||
234 | #endif | ||
235 | #ifdef __cplusplus | ||
236 | } | ||
237 | #endif | ||
238 | |||
239 | /* ifndef GNUNET_TRANSPORT_SERVICE_H */ | ||
240 | #endif | ||
241 | /* end of gnunet_transport_service.h */ | ||