diff options
Diffstat (limited to 'src/transport/plugin_transport.h')
-rw-r--r-- | src/transport/plugin_transport.h | 468 |
1 files changed, 468 insertions, 0 deletions
diff --git a/src/transport/plugin_transport.h b/src/transport/plugin_transport.h new file mode 100644 index 000000000..57df9affe --- /dev/null +++ b/src/transport/plugin_transport.h | |||
@@ -0,0 +1,468 @@ | |||
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 transport/plugin_transport.h | ||
23 | * @brief API for the transport services. This header | ||
24 | * specifies the struct that is given to the plugin's entry | ||
25 | * method and the other struct that must be returned. | ||
26 | * Note that the destructors of transport plugins will | ||
27 | * be given the value returned by the constructor | ||
28 | * and is expected to return a NULL pointer. | ||
29 | * | ||
30 | * TODO: | ||
31 | * - consider moving DATA message (latency measurement) | ||
32 | * to service; avoids encapsulation overheads and | ||
33 | * would enable latency measurements for non-bidi | ||
34 | * transports. | ||
35 | * - | ||
36 | * | ||
37 | * @author Christian Grothoff | ||
38 | */ | ||
39 | #ifndef PLUGIN_TRANSPORT_H | ||
40 | #define PLUGIN_TRANSPORT_H | ||
41 | |||
42 | #include "gnunet_configuration_lib.h" | ||
43 | #include "gnunet_scheduler_lib.h" | ||
44 | #include "gnunet_transport_service.h" | ||
45 | |||
46 | /** | ||
47 | * Opaque internal context for a particular peer of the transport | ||
48 | * service. Plugins will be given a pointer to this type and, if | ||
49 | * cheaply possible, should pass this pointer back to the transport | ||
50 | * service whenever additional messages from the same peer are | ||
51 | * received. | ||
52 | */ | ||
53 | struct ReadyList; | ||
54 | |||
55 | /** | ||
56 | * Function called by the transport for each received message. | ||
57 | * This function should also be called with "NULL" for the | ||
58 | * message to signal that the other peer disconnected. | ||
59 | * | ||
60 | * @param cls closure | ||
61 | * @param plugin_context value to pass to this plugin | ||
62 | * to respond to the given peer (use is optional, | ||
63 | * but may speed up processing) | ||
64 | * @param service_context value passed to the transport-service | ||
65 | * to identify the neighbour; will be NULL on the first | ||
66 | * call for a given peer | ||
67 | * @param latency estimated latency for communicating with the | ||
68 | * given peer; should be set to GNUNET_TIME_UNIT_FOREVER_REL | ||
69 | * until the transport has seen messages transmitted in | ||
70 | * BOTH directions (and hence been able to do an actual | ||
71 | * round-trip observation); a non-FOREVER latency is also used | ||
72 | * by the transport to know that communication in both directions | ||
73 | * using this one plugin actually works | ||
74 | * @param peer (claimed) identity of the other peer | ||
75 | * @param message the message, NULL if peer was disconnected | ||
76 | * @return the new service_context that the plugin should use | ||
77 | * for future receive calls for messages from this | ||
78 | * particular peer | ||
79 | */ | ||
80 | typedef struct ReadyList * | ||
81 | (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, | ||
82 | void *plugin_context, | ||
83 | struct ReadyList * | ||
84 | service_context, | ||
85 | struct GNUNET_TIME_Relative | ||
86 | latency, | ||
87 | const struct GNUNET_PeerIdentity | ||
88 | * peer, | ||
89 | const struct GNUNET_MessageHeader | ||
90 | * message); | ||
91 | |||
92 | |||
93 | /** | ||
94 | * Function that will be called for each address the transport | ||
95 | * is aware that it might be reachable under. | ||
96 | * | ||
97 | * @param cls closure | ||
98 | * @param name name of the transport that generated the address | ||
99 | * @param addr one of the addresses of the host, NULL for the last address | ||
100 | * the specific address format depends on the transport | ||
101 | * @param addrlen length of the address | ||
102 | * @param expires when should this address automatically expire? | ||
103 | */ | ||
104 | typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls, | ||
105 | const char *name, | ||
106 | const void *addr, | ||
107 | size_t addrlen, | ||
108 | struct | ||
109 | GNUNET_TIME_Relative | ||
110 | expires); | ||
111 | |||
112 | |||
113 | /** | ||
114 | * Function that will be called for each address obtained from the HELLO. | ||
115 | * | ||
116 | * @param cls closure | ||
117 | * @param name name of the transport that generated the address | ||
118 | * @param addr one of the addresses of the host, NULL for the last address | ||
119 | * the specific address format depends on the transport | ||
120 | * @param addrlen length of the address | ||
121 | */ | ||
122 | typedef void (*GNUNET_TRANSPORT_AddressCallback) (void *cls, | ||
123 | const char *name, | ||
124 | const void *addr, | ||
125 | size_t addrlen); | ||
126 | |||
127 | |||
128 | /** | ||
129 | * Function that allows a transport to query the known | ||
130 | * network addresses for a given peer. | ||
131 | * | ||
132 | * @param cls closure | ||
133 | * @param timeout after how long should we time out? | ||
134 | * @param target which peer are we looking for? | ||
135 | * @param iter function to call for each known address | ||
136 | * @param iter_cls closure for iter | ||
137 | */ | ||
138 | typedef void (*GNUNET_TRANSPORT_LookupAddress) (void *cls, | ||
139 | struct GNUNET_TIME_Relative | ||
140 | timeout, | ||
141 | const struct | ||
142 | GNUNET_PeerIdentity * target, | ||
143 | GNUNET_TRANSPORT_AddressCallback | ||
144 | iter, void *iter_cls); | ||
145 | |||
146 | |||
147 | /** | ||
148 | * The transport service will pass a pointer to a struct | ||
149 | * of this type as the first and only argument to the | ||
150 | * entry point of each transport plugin. | ||
151 | */ | ||
152 | struct GNUNET_TRANSPORT_PluginEnvironment | ||
153 | { | ||
154 | /** | ||
155 | * Configuration to use. | ||
156 | */ | ||
157 | struct GNUNET_CONFIGURATION_Handle *cfg; | ||
158 | |||
159 | /** | ||
160 | * Scheduler to use. | ||
161 | */ | ||
162 | struct GNUNET_SCHEDULER_Handle *sched; | ||
163 | |||
164 | /** | ||
165 | * Our public key. | ||
166 | */ | ||
167 | struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *my_public_key; | ||
168 | |||
169 | /** | ||
170 | * Closure for the various callbacks. | ||
171 | */ | ||
172 | void *cls; | ||
173 | |||
174 | /** | ||
175 | * Function that should be called by the transport plugin | ||
176 | * whenever a message is received. | ||
177 | */ | ||
178 | GNUNET_TRANSPORT_PluginReceiveCallback receive; | ||
179 | |||
180 | /** | ||
181 | * Address lookup function. | ||
182 | */ | ||
183 | GNUNET_TRANSPORT_LookupAddress lookup; | ||
184 | |||
185 | /** | ||
186 | * Function that must be called by each plugin to notify the | ||
187 | * transport service about the addresses under which the transport | ||
188 | * provided by the plugin can be reached. | ||
189 | */ | ||
190 | GNUNET_TRANSPORT_AddressNotification notify_address; | ||
191 | |||
192 | /** | ||
193 | * What is the default quota (in terms of incoming bytes per | ||
194 | * ms) for new connections? | ||
195 | */ | ||
196 | uint32_t default_quota_in; | ||
197 | |||
198 | /** | ||
199 | * What is the maximum number of connections that this transport | ||
200 | * should allow? Transports that do not have sessions (such as | ||
201 | * UDP) can ignore this value. | ||
202 | */ | ||
203 | uint32_t max_connections; | ||
204 | |||
205 | }; | ||
206 | |||
207 | |||
208 | /** | ||
209 | * Function that can be used by the transport service to transmit | ||
210 | * a message using the plugin using a fresh connection (even if | ||
211 | * we already have a connection to this peer, this function is | ||
212 | * required to establish a new one). | ||
213 | * | ||
214 | * @param cls closure | ||
215 | * @param target who should receive this message | ||
216 | * @param msg1 first message to transmit | ||
217 | * @param msg2 second message to transmit (can be NULL) | ||
218 | * @param timeout how long should we try to transmit these? | ||
219 | * @param addrlen length of the address | ||
220 | * @param addr the address | ||
221 | * @return session instance if the transmission has been scheduled | ||
222 | * NULL if the address format is invalid | ||
223 | */ | ||
224 | typedef void * | ||
225 | (*GNUNET_TRANSPORT_TransmitToAddressFunction) (void *cls, | ||
226 | const struct | ||
227 | GNUNET_PeerIdentity * target, | ||
228 | const struct | ||
229 | GNUNET_MessageHeader * msg1, | ||
230 | const struct | ||
231 | GNUNET_MessageHeader * msg2, | ||
232 | struct GNUNET_TIME_Relative | ||
233 | timeout, const void *addr, | ||
234 | size_t addrlen); | ||
235 | |||
236 | /** | ||
237 | * Function called by the GNUNET_TRANSPORT_TransmitFunction | ||
238 | * upon "completion". | ||
239 | * | ||
240 | * @param cls closure | ||
241 | * @param service_context value passed to the transport-service | ||
242 | * to identify the neighbour | ||
243 | * @param target who was the recipient of the message? | ||
244 | * @param result GNUNET_OK on success | ||
245 | * GNUNET_SYSERR if the target disconnected; | ||
246 | * disconnect will ALSO be signalled using | ||
247 | * the ReceiveCallback. | ||
248 | */ | ||
249 | typedef void | ||
250 | (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls, | ||
251 | struct ReadyList * | ||
252 | service_context, | ||
253 | const struct GNUNET_PeerIdentity * | ||
254 | target, int result); | ||
255 | |||
256 | /** | ||
257 | * Function that can be used by the transport service to transmit | ||
258 | * a message using the plugin. Note that in the case of a | ||
259 | * peer disconnecting, the continuation MUST be called | ||
260 | * prior to the disconnect notification itself. This function | ||
261 | * will be called with this peer's HELLO message to initiate | ||
262 | * a fresh connection to another peer. | ||
263 | * | ||
264 | * @param cls closure | ||
265 | * @param plugin_context value we were asked to pass to this plugin | ||
266 | * to respond to the given peer (use is optional, | ||
267 | * but may speed up processing), can be NULL | ||
268 | * @param service_context value passed to the transport-service | ||
269 | * to identify the neighbour; NULL is used to indicate | ||
270 | * an urgent message. If the urgent message can not be | ||
271 | * scheduled for immediate transmission, the plugin is to | ||
272 | * call the continuation with failure immediately | ||
273 | * @param target who should receive this message | ||
274 | * @param msg the message to transmit | ||
275 | * @param timeout how long to wait at most for the transmission | ||
276 | * @param cont continuation to call once the message has | ||
277 | * been transmitted (or if the transport is ready | ||
278 | * for the next transmission call; or if the | ||
279 | * peer disconnected...); can be NULL | ||
280 | * @param cont_cls closure for cont | ||
281 | * @return plugin_context that should be used next time for | ||
282 | * sending messages to the specified peer | ||
283 | */ | ||
284 | typedef void * | ||
285 | (*GNUNET_TRANSPORT_TransmitFunction) (void *cls, | ||
286 | void *plugin_context, | ||
287 | struct ReadyList * service_context, | ||
288 | const struct GNUNET_PeerIdentity * | ||
289 | target, | ||
290 | const struct GNUNET_MessageHeader * | ||
291 | msg, | ||
292 | struct GNUNET_TIME_Relative timeout, | ||
293 | GNUNET_TRANSPORT_TransmitContinuation | ||
294 | cont, void *cont_cls); | ||
295 | |||
296 | |||
297 | /** | ||
298 | * Function that can be called to force a disconnect from the | ||
299 | * specified neighbour. This should also cancel all previously | ||
300 | * scheduled transmissions. Obviously the transmission may have been | ||
301 | * partially completed already, which is OK. The plugin is supposed | ||
302 | * to close the connection (if applicable) and no longer call the | ||
303 | * transmit continuation(s). | ||
304 | * | ||
305 | * Finally, plugin MUST NOT call the services's receive function to | ||
306 | * notify the service that the connection to the specified target was | ||
307 | * closed after a getting this call. | ||
308 | * | ||
309 | * @param cls closure | ||
310 | * @param plugin_context value we were asked to pass to this plugin | ||
311 | * to respond to the given peer (use is optional, | ||
312 | * but may speed up processing), can be NULL (if | ||
313 | * NULL was returned from the transmit function) | ||
314 | * @param service_context must correspond to the service context | ||
315 | * of the corresponding Transmit call; the plugin should | ||
316 | * not cancel a send call made with a different service | ||
317 | * context pointer! Never NULL. | ||
318 | * @param target peer for which the last transmission is | ||
319 | * to be cancelled | ||
320 | */ | ||
321 | typedef void | ||
322 | (*GNUNET_TRANSPORT_CancelFunction) (void *cls, | ||
323 | void *plugin_context, | ||
324 | struct ReadyList * service_context, | ||
325 | const struct GNUNET_PeerIdentity * | ||
326 | target); | ||
327 | |||
328 | |||
329 | /** | ||
330 | * Function called by the pretty printer for the resolved address for | ||
331 | * each human-readable address obtained. | ||
332 | * | ||
333 | * @param cls closure | ||
334 | * @param hostname one of the names for the host, NULL | ||
335 | * on the last call to the callback | ||
336 | */ | ||
337 | typedef void (*GNUNET_TRANSPORT_AddressStringCallback) (void *cls, | ||
338 | const char *address); | ||
339 | |||
340 | |||
341 | /** | ||
342 | * Convert the transports address to a nice, human-readable | ||
343 | * format. | ||
344 | * | ||
345 | * @param cls closure | ||
346 | * @param name name of the transport that generated the address | ||
347 | * @param addr one of the addresses of the host, NULL for the last address | ||
348 | * the specific address format depends on the transport | ||
349 | * @param addrlen length of the address | ||
350 | * @param numeric should (IP) addresses be displayed in numeric form? | ||
351 | * @param timeout after how long should we give up? | ||
352 | * @param asc function to call on each string | ||
353 | * @param asc_cls closure for asc | ||
354 | */ | ||
355 | typedef void | ||
356 | (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls, | ||
357 | const char *type, | ||
358 | const void *addr, | ||
359 | size_t addrlen, | ||
360 | int numeric, | ||
361 | struct GNUNET_TIME_Relative | ||
362 | timeout, | ||
363 | GNUNET_TRANSPORT_AddressStringCallback | ||
364 | asc, void *asc_cls); | ||
365 | |||
366 | |||
367 | /** | ||
368 | * Set a quota for receiving data from the given peer; this is a | ||
369 | * per-transport limit. The transport should limit its read/select | ||
370 | * calls to stay below the quota (in terms of incoming data). | ||
371 | * | ||
372 | * @param cls closure | ||
373 | * @param peer the peer for whom the quota is given | ||
374 | * @param quota_in quota for receiving/sending data in bytes per ms | ||
375 | */ | ||
376 | typedef void | ||
377 | (*GNUNET_TRANSPORT_SetQuota) (void *cls, | ||
378 | const struct GNUNET_PeerIdentity * target, | ||
379 | uint32_t quota_in); | ||
380 | |||
381 | |||
382 | /** | ||
383 | * Another peer has suggested an address for this | ||
384 | * peer and transport plugin. Check that this could be a valid | ||
385 | * address. If so, consider adding it to the list | ||
386 | * of addresses. | ||
387 | * | ||
388 | * @param addr pointer to the address | ||
389 | * @param addrlen length of addr | ||
390 | * @return GNUNET_OK if this is a plausible address for this peer | ||
391 | * and transport | ||
392 | */ | ||
393 | typedef int | ||
394 | (*GNUNET_TRANSPORT_SuggestAddress) (void *cls, | ||
395 | const void *addr, size_t addrlen); | ||
396 | |||
397 | /** | ||
398 | * Each plugin is required to return a pointer to a struct of this | ||
399 | * type as the return value from its entry point. | ||
400 | */ | ||
401 | struct GNUNET_TRANSPORT_PluginFunctions | ||
402 | { | ||
403 | |||
404 | /** | ||
405 | * Closure for all of the callbacks. | ||
406 | */ | ||
407 | void *cls; | ||
408 | |||
409 | /** | ||
410 | * Function used to send a single message to a particular | ||
411 | * peer using the specified address. Used to validate | ||
412 | * HELLOs. | ||
413 | */ | ||
414 | GNUNET_TRANSPORT_TransmitToAddressFunction send_to; | ||
415 | |||
416 | /** | ||
417 | * Function that the transport service will use to transmit data to | ||
418 | * another peer. May be null for plugins that only support | ||
419 | * receiving data. After this call, the plugin call the specified | ||
420 | * continuation with success or error before notifying us about the | ||
421 | * target having disconnected. | ||
422 | */ | ||
423 | GNUNET_TRANSPORT_TransmitFunction send; | ||
424 | |||
425 | /** | ||
426 | * Function that can be used to force the plugin to disconnect | ||
427 | * from the given peer and cancel all previous transmissions | ||
428 | * (and their continuationc). | ||
429 | */ | ||
430 | GNUNET_TRANSPORT_CancelFunction cancel; | ||
431 | |||
432 | /** | ||
433 | * Function to pretty-print addresses. NOTE: this function is not | ||
434 | * yet used by transport-service, but will be used in the future | ||
435 | * once the transport-API has been completed. | ||
436 | */ | ||
437 | GNUNET_TRANSPORT_AddressPrettyPrinter address_pretty_printer; | ||
438 | |||
439 | /** | ||
440 | * Function that the transport service can use to try to enforce a | ||
441 | * quota for the number of bytes received via this transport. | ||
442 | * Transports that can not refuse incoming data (such as UDP) | ||
443 | * are free to ignore these calls. | ||
444 | */ | ||
445 | GNUNET_TRANSPORT_SetQuota set_receive_quota; | ||
446 | |||
447 | /** | ||
448 | * Function that will be called if another peer suggested that | ||
449 | * we should use a particular address (since he is reaching | ||
450 | * us at that address) for this transport. | ||
451 | */ | ||
452 | GNUNET_TRANSPORT_SuggestAddress address_suggested; | ||
453 | |||
454 | /** | ||
455 | * Relative cost of this transport compared to others. This | ||
456 | * is supposed to be a static cost estimate which determines | ||
457 | * which plugins should not even be attempted if other, | ||
458 | * cheaper transports are already working. The idea is that | ||
459 | * the costs have roughly this relationship: | ||
460 | * <pre> | ||
461 | * TCP < UDP < HTTP == HTTPS < SMTP | ||
462 | * </pre> | ||
463 | */ | ||
464 | unsigned int cost_estimate; | ||
465 | }; | ||
466 | |||
467 | |||
468 | #endif | ||