diff options
Diffstat (limited to 'src/include/gnunet_transport_plugin.h')
-rw-r--r-- | src/include/gnunet_transport_plugin.h | 733 |
1 files changed, 0 insertions, 733 deletions
diff --git a/src/include/gnunet_transport_plugin.h b/src/include/gnunet_transport_plugin.h deleted file mode 100644 index 0ab4a995c..000000000 --- a/src/include/gnunet_transport_plugin.h +++ /dev/null | |||
@@ -1,733 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | Copyright (C) 2009-2014 GNUnet e.V. | ||
4 | |||
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. | ||
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 | Affero General Public License for more details. | ||
14 | |||
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/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @addtogroup Backbone | ||
23 | * @{ | ||
24 | * | ||
25 | * @author Christian Grothoff | ||
26 | * | ||
27 | * @file | ||
28 | * Transport service plugin API | ||
29 | * | ||
30 | * @defgroup transport-plugin Transport Service plugin API | ||
31 | * | ||
32 | * Specifies the struct that is given to the plugin's entry method and the other | ||
33 | * struct that must be returned. Note that the destructors of transport plugins | ||
34 | * will be given the value returned by the constructor and is expected to return | ||
35 | * a NULL pointer. | ||
36 | * | ||
37 | * @{ | ||
38 | */ | ||
39 | #ifndef PLUGIN_TRANSPORT_H | ||
40 | #define PLUGIN_TRANSPORT_H | ||
41 | |||
42 | |||
43 | #include "gnunet_configuration_lib.h" | ||
44 | #include "gnunet_scheduler_lib.h" | ||
45 | #include "gnunet_statistics_service.h" | ||
46 | #include "gnunet_transport_service.h" | ||
47 | #include "gnunet_ats_service.h" | ||
48 | |||
49 | #define TRANSPORT_SESSION_INBOUND_STRING "<inbound>" | ||
50 | |||
51 | /** | ||
52 | * Opaque pointer that plugins can use to distinguish specific | ||
53 | * connections to a given peer. Typically used by stateful plugins to | ||
54 | * allow the service to refer to specific streams instead of a more | ||
55 | * general notion of "some connection" to the given peer. This is | ||
56 | * useful since sometimes (e.g. for inbound TCP connections) a | ||
57 | * connection may not have an address that can be used for meaningful | ||
58 | * distinction between sessions to the same peer. | ||
59 | * | ||
60 | * Each 'struct GNUNET_ATS_Session' MUST start with the 'struct GNUNET_PeerIdentity' | ||
61 | * of the peer the session is for (which will be used for some error | ||
62 | * checking by the ATS code). | ||
63 | */ | ||
64 | struct GNUNET_ATS_Session; | ||
65 | |||
66 | |||
67 | /** | ||
68 | * Function that will be called whenever the plugin internally | ||
69 | * cleans up a session pointer and hence the service needs to | ||
70 | * discard all of those sessions as well. Plugins that do not | ||
71 | * use sessions can simply omit calling this function and always | ||
72 | * use NULL wherever a session pointer is needed. This function | ||
73 | * should be called BEFORE a potential "TransmitContinuation" | ||
74 | * from the "TransmitFunction". | ||
75 | * | ||
76 | * @param cls closure | ||
77 | * @param peer which peer was the session for | ||
78 | * @param session which session is being destroyed | ||
79 | */ | ||
80 | typedef void | ||
81 | (*GNUNET_TRANSPORT_SessionEnd) (void *cls, | ||
82 | const struct GNUNET_HELLO_Address *address, | ||
83 | struct GNUNET_ATS_Session *session); | ||
84 | |||
85 | |||
86 | /** | ||
87 | * Plugin tells transport service about a new inbound session | ||
88 | * | ||
89 | * @param cls unused | ||
90 | * @param address the address | ||
91 | * @param session the new session | ||
92 | * @param net network information | ||
93 | */ | ||
94 | typedef void | ||
95 | (*GNUNET_TRANSPORT_SessionStart) (void *cls, | ||
96 | const struct GNUNET_HELLO_Address *address, | ||
97 | struct GNUNET_ATS_Session *session, | ||
98 | enum GNUNET_NetworkType net); | ||
99 | |||
100 | |||
101 | /** | ||
102 | * Function called by the transport for each received message. | ||
103 | * This function should also be called with "NULL" for the | ||
104 | * message to signal that the other peer disconnected. | ||
105 | * | ||
106 | * @param cls closure | ||
107 | * @param peer (claimed) identity of the other peer | ||
108 | * @param message the message, NULL if we only care about | ||
109 | * learning about the delay until we should receive again | ||
110 | * @param session identifier used for this session (NULL for plugins | ||
111 | * that do not offer bi-directional communication to the sender | ||
112 | * using the same "connection") | ||
113 | * @param sender_address binary address of the sender (if we established the | ||
114 | * connection or are otherwise sure of it; should be NULL | ||
115 | * for inbound TCP/UDP connections since it it not clear | ||
116 | * that we could establish ourselves a connection to that | ||
117 | * IP address and get the same system) | ||
118 | * @param sender_address_len number of bytes in @a sender_address | ||
119 | * @return how long the plugin should wait until receiving more data; | ||
120 | * returning #GNUNET_TIME_UNIT_FOREVER_REL means that the | ||
121 | * connection should be closed | ||
122 | */ | ||
123 | typedef struct GNUNET_TIME_Relative | ||
124 | (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, | ||
125 | const struct | ||
126 | GNUNET_HELLO_Address *address, | ||
127 | struct GNUNET_ATS_Session *session, | ||
128 | const struct | ||
129 | GNUNET_MessageHeader *message); | ||
130 | |||
131 | |||
132 | /** | ||
133 | * Function that can be called by plugins to figure if an address is | ||
134 | * an loopback, LAN or WAN address. Ultimately invokes | ||
135 | * #GNUNET_ATS_address_get_type(). | ||
136 | * | ||
137 | * @param cls closure | ||
138 | * @param addr binary address | ||
139 | * @param addrlen length of the @a addr | ||
140 | * @return type of the network the address belongs to | ||
141 | */ | ||
142 | typedef enum GNUNET_NetworkType | ||
143 | (*GNUNET_TRANSPORT_AddressToType)(void *cls, | ||
144 | const struct sockaddr *addr, | ||
145 | size_t addrlen); | ||
146 | |||
147 | |||
148 | /** | ||
149 | * Function called when distance of an address changes. | ||
150 | * | ||
151 | * @param cls closure | ||
152 | * @param peer peer | ||
153 | * @param distance new distance | ||
154 | */ | ||
155 | typedef void | ||
156 | (*GNUNET_TRANSPORT_UpdateAddressDistance) (void *cls, | ||
157 | const struct | ||
158 | GNUNET_HELLO_Address *address, | ||
159 | uint32_t distance); | ||
160 | |||
161 | |||
162 | /** | ||
163 | * Function that will be called for each address the transport | ||
164 | * is aware that it might be reachable under. | ||
165 | * | ||
166 | * @param cls closure | ||
167 | * @param add_remove should the address added (#GNUNET_YES) or removed (#GNUNET_NO) from the | ||
168 | * set of valid addresses? | ||
169 | * @param address the address to add or remove | ||
170 | */ | ||
171 | typedef void | ||
172 | (*GNUNET_TRANSPORT_AddressNotification) (void *cls, | ||
173 | int add_remove, | ||
174 | const struct | ||
175 | GNUNET_HELLO_Address *address); | ||
176 | |||
177 | |||
178 | /** | ||
179 | * Function that will be called whenever the plugin receives data over | ||
180 | * the network and wants to determine how long it should wait until | ||
181 | * the next time it reads from the given peer. Note that some plugins | ||
182 | * (such as UDP) may not be able to wait (for a particular peer), so | ||
183 | * the waiting part is optional. Plugins that can wait should call | ||
184 | * this function, sleep the given amount of time, and call it again | ||
185 | * (with zero bytes read) UNTIL it returns zero and only then read. | ||
186 | * | ||
187 | * @param cls closure | ||
188 | * @param peer which peer did we read data from | ||
189 | * @param amount_recved number of bytes read (can be zero) | ||
190 | * @return how long to wait until reading more from this peer | ||
191 | * (to enforce inbound quotas); returning #GNUNET_TIME_UNIT_FOREVER_REL | ||
192 | * means that the connection should be closed | ||
193 | */ | ||
194 | typedef struct GNUNET_TIME_Relative | ||
195 | (*GNUNET_TRANSPORT_TrafficReport) (void *cls, | ||
196 | const struct GNUNET_PeerIdentity *peer, | ||
197 | size_t amount_recved); | ||
198 | |||
199 | |||
200 | /** | ||
201 | * Function that returns a HELLO message. | ||
202 | * | ||
203 | * @return HELLO message (FIXME with what?) | ||
204 | */ | ||
205 | typedef const struct GNUNET_MessageHeader * | ||
206 | (*GNUNET_TRANSPORT_GetHelloCallback) (void); | ||
207 | |||
208 | |||
209 | /** | ||
210 | * The transport service will pass a pointer to a struct | ||
211 | * of this type as the first and only argument to the | ||
212 | * entry point of each transport plugin. | ||
213 | */ | ||
214 | struct GNUNET_TRANSPORT_PluginEnvironment | ||
215 | { | ||
216 | /** | ||
217 | * Configuration to use. | ||
218 | */ | ||
219 | const struct GNUNET_CONFIGURATION_Handle *cfg; | ||
220 | |||
221 | /** | ||
222 | * Identity of this peer. | ||
223 | */ | ||
224 | const struct GNUNET_PeerIdentity *my_identity; | ||
225 | |||
226 | /** | ||
227 | * Closure for the various callbacks. | ||
228 | */ | ||
229 | void *cls; | ||
230 | |||
231 | /** | ||
232 | * Handle for reporting statistics. | ||
233 | */ | ||
234 | struct GNUNET_STATISTICS_Handle *stats; | ||
235 | |||
236 | /** | ||
237 | * Function that should be called by the transport plugin | ||
238 | * whenever a message is received. If this field is "NULL", | ||
239 | * the plugin should load in 'stub' mode and NOT fully | ||
240 | * initialize and instead only return an API with the | ||
241 | * @e address_pretty_printer, @e address_to_string and | ||
242 | * @e string_to_address functions. | ||
243 | */ | ||
244 | GNUNET_TRANSPORT_PluginReceiveCallback receive; | ||
245 | |||
246 | /** | ||
247 | * Function that returns our HELLO. | ||
248 | */ | ||
249 | GNUNET_TRANSPORT_GetHelloCallback get_our_hello; | ||
250 | |||
251 | /** | ||
252 | * Function that must be called by each plugin to notify the | ||
253 | * transport service about the addresses under which the transport | ||
254 | * provided by the plugin can be reached. | ||
255 | */ | ||
256 | GNUNET_TRANSPORT_AddressNotification notify_address; | ||
257 | |||
258 | /** | ||
259 | * Function that must be called by the plugin when a non-NULL | ||
260 | * session handle stops being valid (is destroyed). | ||
261 | */ | ||
262 | GNUNET_TRANSPORT_SessionEnd session_end; | ||
263 | |||
264 | /** | ||
265 | * Function called by the plugin when a new (incoming) session was created | ||
266 | * not explicitly created using the the get_session function | ||
267 | */ | ||
268 | GNUNET_TRANSPORT_SessionStart session_start; | ||
269 | |||
270 | /** | ||
271 | * Function that will be called to figure if an address is an loopback, | ||
272 | * LAN, WAN etc. address | ||
273 | */ | ||
274 | GNUNET_TRANSPORT_AddressToType get_address_type; | ||
275 | |||
276 | /** | ||
277 | * Function that will be called by DV to update distance for | ||
278 | * an address. | ||
279 | */ | ||
280 | GNUNET_TRANSPORT_UpdateAddressDistance update_address_distance; | ||
281 | |||
282 | /** | ||
283 | * What is the maximum number of connections that this transport | ||
284 | * should allow? Transports that do not have sessions (such as | ||
285 | * UDP) can ignore this value. | ||
286 | */ | ||
287 | uint32_t max_connections; | ||
288 | }; | ||
289 | |||
290 | |||
291 | /** | ||
292 | * Function called by the #GNUNET_TRANSPORT_TransmitFunction | ||
293 | * upon "completion". In the case that a peer disconnects, | ||
294 | * this function must be called for each pending request | ||
295 | * (with a 'failure' indication) AFTER notifying the service | ||
296 | * about the disconnect event (so that the service won't try | ||
297 | * to transmit more messages, believing the connection still | ||
298 | * exists...). | ||
299 | * | ||
300 | * @param cls closure | ||
301 | * @param target who was the recipient of the message? | ||
302 | * @param result #GNUNET_OK on success | ||
303 | * #GNUNET_SYSERR if the target disconnected; | ||
304 | * disconnect will ALSO be signalled using | ||
305 | * the ReceiveCallback. | ||
306 | * @param size_payload bytes of payload from transport service in message | ||
307 | * @param size_on_wire bytes required on wire for transmission, | ||
308 | * 0 if result == #GNUNET_SYSERR | ||
309 | */ | ||
310 | typedef void | ||
311 | (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls, | ||
312 | const struct | ||
313 | GNUNET_PeerIdentity *target, | ||
314 | int result, | ||
315 | size_t size_payload, | ||
316 | size_t size_on_wire); | ||
317 | |||
318 | |||
319 | /** | ||
320 | * The new send function with just the session and no address | ||
321 | * | ||
322 | * Function that can be used by the transport service to transmit | ||
323 | * a message using the plugin. Note that in the case of a | ||
324 | * peer disconnecting, the continuation MUST be called | ||
325 | * prior to the disconnect notification itself. This function | ||
326 | * will be called with this peer's HELLO message to initiate | ||
327 | * a fresh connection to another peer. | ||
328 | * | ||
329 | * @param cls closure | ||
330 | * @param session which session must be used | ||
331 | * @param msgbuf the message to transmit | ||
332 | * @param msgbuf_size number of bytes in @a msgbuf | ||
333 | * @param priority how important is the message (most plugins will | ||
334 | * ignore message priority and just FIFO) | ||
335 | * @param to how long to wait at most for the transmission (does not | ||
336 | * require plugins to discard the message after the timeout, | ||
337 | * just advisory for the desired delay; most plugins will ignore | ||
338 | * this as well) | ||
339 | * @param cont continuation to call once the message has | ||
340 | * been transmitted (or if the transport is ready | ||
341 | * for the next transmission call; or if the | ||
342 | * peer disconnected...); can be NULL | ||
343 | * @param cont_cls closure for @a cont | ||
344 | * @return number of bytes used (on the physical network, with overheads); | ||
345 | * -1 on hard errors (i.e. address invalid); 0 is a legal value | ||
346 | * and does NOT mean that the message was not transmitted (DV) | ||
347 | */ | ||
348 | typedef ssize_t | ||
349 | (*GNUNET_TRANSPORT_TransmitFunction) (void *cls, | ||
350 | struct GNUNET_ATS_Session *session, | ||
351 | const char *msgbuf, | ||
352 | size_t msgbuf_size, | ||
353 | unsigned int priority, | ||
354 | struct GNUNET_TIME_Relative to, | ||
355 | GNUNET_TRANSPORT_TransmitContinuation cont, | ||
356 | void *cont_cls); | ||
357 | |||
358 | |||
359 | /** | ||
360 | * Function that can be called to force a disconnect from the | ||
361 | * specified neighbour for the given session only. . This should | ||
362 | * also cancel all previously scheduled transmissions for this | ||
363 | * session. Obviously the transmission may have been partially | ||
364 | * completed already, which is OK. The plugin is supposed to close | ||
365 | * the connection (if applicable). | ||
366 | * | ||
367 | * @param cls closure with the `struct Plugin` | ||
368 | * @param session session to destroy | ||
369 | * @return #GNUNET_OK on success | ||
370 | */ | ||
371 | typedef int | ||
372 | (*GNUNET_TRANSPORT_DisconnectSessionFunction) (void *cls, | ||
373 | struct GNUNET_ATS_Session * | ||
374 | session); | ||
375 | |||
376 | |||
377 | /** | ||
378 | * Function that is called to get the keepalive factor. | ||
379 | * #GNUNET_CONSTANTS_IDLE_CONNECTION_TIMEOUT is divided by this number to | ||
380 | * calculate the interval between keepalive packets. | ||
381 | * | ||
382 | * @param cls closure with the `struct Plugin` | ||
383 | * @return keepalive factor | ||
384 | */ | ||
385 | typedef unsigned int | ||
386 | (*GNUNET_TRANSPORT_QueryKeepaliveFactorFunction) (void *cls); | ||
387 | |||
388 | |||
389 | /** | ||
390 | * Function that can be called to force a disconnect from the | ||
391 | * specified neighbour. This should also cancel all previously | ||
392 | * scheduled transmissions. Obviously the transmission may have been | ||
393 | * partially completed already, which is OK. The plugin is supposed | ||
394 | * to close the connection (if applicable) and no longer call the | ||
395 | * transmit continuation(s). | ||
396 | * | ||
397 | * @param cls closure | ||
398 | * @param target peer for which the last transmission is | ||
399 | * to be cancelled | ||
400 | */ | ||
401 | typedef void | ||
402 | (*GNUNET_TRANSPORT_DisconnectPeerFunction) (void *cls, | ||
403 | const struct | ||
404 | GNUNET_PeerIdentity *target); | ||
405 | |||
406 | |||
407 | /** | ||
408 | * Function called by the pretty printer for the resolved address for | ||
409 | * each human-readable address obtained. The callback can be called | ||
410 | * several times. The last invocation must be with a @a address of | ||
411 | * NULL and a @a res of #GNUNET_OK. Thus, to indicate conversion | ||
412 | * errors, the callback might be called first with @a address NULL and | ||
413 | * @a res being #GNUNET_SYSERR. In that case, there must still be a | ||
414 | * subsequent call later with @a address NULL and @a res #GNUNET_OK. | ||
415 | * | ||
416 | * @param cls closure | ||
417 | * @param address one of the names for the host, NULL on last callback | ||
418 | * @param res #GNUNET_OK if conversion was successful, #GNUNET_SYSERR on failure, | ||
419 | * #GNUNET_OK on last callback | ||
420 | */ | ||
421 | typedef void | ||
422 | (*GNUNET_TRANSPORT_AddressStringCallback) (void *cls, | ||
423 | const char *address, | ||
424 | int res); | ||
425 | |||
426 | |||
427 | /** | ||
428 | * Convert the transports address to a nice, human-readable | ||
429 | * format. | ||
430 | * | ||
431 | * @param cls closure | ||
432 | * @param type name of the transport that generated the address | ||
433 | * @param addr one of the addresses of the host, NULL for the last address | ||
434 | * the specific address format depends on the transport | ||
435 | * @param addrlen length of the @a addr | ||
436 | * @param numeric should (IP) addresses be displayed in numeric form? | ||
437 | * @param timeout after how long should we give up? | ||
438 | * @param asc function to call on each string | ||
439 | * @param asc_cls closure for @a asc | ||
440 | */ | ||
441 | typedef void | ||
442 | (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls, | ||
443 | const char *type, | ||
444 | const void *addr, | ||
445 | size_t addrlen, | ||
446 | int numeric, | ||
447 | struct GNUNET_TIME_Relative timeout, | ||
448 | GNUNET_TRANSPORT_AddressStringCallback | ||
449 | asc, | ||
450 | void *asc_cls); | ||
451 | |||
452 | |||
453 | /** | ||
454 | * Another peer has suggested an address for this peer and transport | ||
455 | * plugin. Check that this could be a valid address. This function | ||
456 | * is not expected to 'validate' the address in the sense of trying to | ||
457 | * connect to it but simply to see if the binary format is technically | ||
458 | * legal for establishing a connection to this peer (and make sure that | ||
459 | * the address really corresponds to our network connection/settings | ||
460 | * and not some potential man-in-the-middle). | ||
461 | * | ||
462 | * @param addr pointer to the address | ||
463 | * @param addrlen length of @a addr | ||
464 | * @return #GNUNET_OK if this is a plausible address for this peer | ||
465 | * and transport, #GNUNET_SYSERR if not | ||
466 | */ | ||
467 | typedef int | ||
468 | (*GNUNET_TRANSPORT_CheckAddress) (void *cls, | ||
469 | const void *addr, | ||
470 | size_t addrlen); | ||
471 | |||
472 | |||
473 | /** | ||
474 | * Create a new session to transmit data to the target | ||
475 | * This session will used to send data to this peer and the plugin will | ||
476 | * notify us by calling the env->session_end function | ||
477 | * | ||
478 | * @param cls the plugin | ||
479 | * @param address the hello address | ||
480 | * @return the session if the address is valid, NULL otherwise | ||
481 | */ | ||
482 | typedef struct GNUNET_ATS_Session * | ||
483 | (*GNUNET_TRANSPORT_CreateSession) (void *cls, | ||
484 | const struct GNUNET_HELLO_Address *address); | ||
485 | |||
486 | |||
487 | /** | ||
488 | * Function that will be called whenever the transport service wants to | ||
489 | * notify the plugin that a session is still active and in use and | ||
490 | * therefore the session timeout for this session has to be updated | ||
491 | * | ||
492 | * @param cls closure | ||
493 | * @param peer which peer was the session for | ||
494 | * @param session which session is being updated | ||
495 | */ | ||
496 | typedef void | ||
497 | (*GNUNET_TRANSPORT_UpdateSessionTimeout) (void *cls, | ||
498 | const struct | ||
499 | GNUNET_PeerIdentity *peer, | ||
500 | struct GNUNET_ATS_Session *session); | ||
501 | |||
502 | |||
503 | /** | ||
504 | * Function that will be called whenever the transport service wants to | ||
505 | * notify the plugin that the inbound quota changed and that the plugin | ||
506 | * should update it's delay for the next receive value | ||
507 | * | ||
508 | * @param cls closure | ||
509 | * @param peer which peer was the session for | ||
510 | * @param session which session is being updated | ||
511 | * @param delay new delay to use for receiving | ||
512 | */ | ||
513 | typedef void | ||
514 | (*GNUNET_TRANSPORT_UpdateInboundDelay) (void *cls, | ||
515 | const struct GNUNET_PeerIdentity *peer, | ||
516 | struct GNUNET_ATS_Session *session, | ||
517 | struct GNUNET_TIME_Relative delay); | ||
518 | |||
519 | |||
520 | /** | ||
521 | * Function called for a quick conversion of the binary address to | ||
522 | * a numeric address. Note that the caller must not free the | ||
523 | * address and that the next call to this function is allowed | ||
524 | * to override the address again. | ||
525 | * | ||
526 | * @param cls closure | ||
527 | * @param addr binary address | ||
528 | * @param addr_len length of the @a addr | ||
529 | * @return string representing the same address | ||
530 | */ | ||
531 | typedef const char * | ||
532 | (*GNUNET_TRANSPORT_AddressToString) (void *cls, | ||
533 | const void *addr, | ||
534 | size_t addrlen); | ||
535 | |||
536 | |||
537 | /** | ||
538 | * Function called to convert a string address to | ||
539 | * a binary address. | ||
540 | * | ||
541 | * @param cls closure (`struct Plugin*`) | ||
542 | * @param addr string address | ||
543 | * @param addrlen length of the @a addr including \0 termination | ||
544 | * @param buf location to store the buffer | ||
545 | * If the function returns #GNUNET_SYSERR, its contents are undefined. | ||
546 | * @param added length of created address | ||
547 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | ||
548 | */ | ||
549 | typedef int | ||
550 | (*GNUNET_TRANSPORT_StringToAddress) (void *cls, | ||
551 | const char *addr, | ||
552 | uint16_t addrlen, | ||
553 | void **buf, | ||
554 | size_t *added); | ||
555 | |||
556 | |||
557 | /** | ||
558 | * Function to obtain the network type for a session | ||
559 | * | ||
560 | * @param cls closure (`struct Plugin *`) | ||
561 | * @param session the session | ||
562 | * @return the network type | ||
563 | */ | ||
564 | typedef enum GNUNET_NetworkType | ||
565 | (*GNUNET_TRANSPORT_GetNetworkType)(void *cls, | ||
566 | struct GNUNET_ATS_Session *session); | ||
567 | |||
568 | |||
569 | /** | ||
570 | * Function to obtain the network type for an address. | ||
571 | * | ||
572 | * @param cls closure (`struct Plugin *`) | ||
573 | * @param address the address | ||
574 | * @return the network type | ||
575 | */ | ||
576 | typedef enum GNUNET_NetworkType | ||
577 | (*GNUNET_TRANSPORT_GetNetworkTypeForAddress)(void *cls, | ||
578 | const struct | ||
579 | GNUNET_HELLO_Address *address); | ||
580 | |||
581 | |||
582 | /** | ||
583 | * Function called by the plugin with information about the | ||
584 | * current sessions managed by the plugin (for monitoring). | ||
585 | * | ||
586 | * @param cls closure | ||
587 | * @param session session handle this information is about, | ||
588 | * NULL to indicate that we are "in sync" (initial | ||
589 | * iteration complete) | ||
590 | * @param info information about the state of the session, | ||
591 | * NULL if @a session is also NULL and we are | ||
592 | * merely signalling that the initial iteration is over | ||
593 | */ | ||
594 | typedef void | ||
595 | (*GNUNET_TRANSPORT_SessionInfoCallback) (void *cls, | ||
596 | struct GNUNET_ATS_Session *session, | ||
597 | const struct | ||
598 | GNUNET_TRANSPORT_SessionInfo *info); | ||
599 | |||
600 | |||
601 | /** | ||
602 | * Begin monitoring sessions of a plugin. There can only | ||
603 | * be one active monitor per plugin (i.e. if there are | ||
604 | * multiple monitors, the transport service needs to | ||
605 | * multiplex the generated events over all of them). | ||
606 | * | ||
607 | * @param cls closure of the plugin | ||
608 | * @param sic callback to invoke, NULL to disable monitor; | ||
609 | * plugin will being by iterating over all active | ||
610 | * sessions immediately and then enter monitor mode | ||
611 | * @param sic_cls closure for @a sic | ||
612 | */ | ||
613 | typedef void | ||
614 | (*GNUNET_TRANSPORT_SessionMonitorSetup) (void *cls, | ||
615 | GNUNET_TRANSPORT_SessionInfoCallback | ||
616 | sic, | ||
617 | void *sic_cls); | ||
618 | |||
619 | |||
620 | /** | ||
621 | * Each plugin is required to return a pointer to a struct of this | ||
622 | * type as the return value from its entry point. | ||
623 | */ | ||
624 | struct GNUNET_TRANSPORT_PluginFunctions | ||
625 | { | ||
626 | /** | ||
627 | * Closure for all of the callbacks. | ||
628 | */ | ||
629 | void *cls; | ||
630 | |||
631 | /** | ||
632 | * Function that the transport service will use to transmit data to | ||
633 | * another peer. May be NULL for plugins that only support | ||
634 | * receiving data. After this call, the plugin call the specified | ||
635 | * continuation with success or error before notifying us about the | ||
636 | * target having disconnected. | ||
637 | */ | ||
638 | GNUNET_TRANSPORT_TransmitFunction send; | ||
639 | |||
640 | /** | ||
641 | * Function that can be used to force the plugin to disconnect from | ||
642 | * the given peer and cancel all previous transmissions (and their | ||
643 | * continuations). | ||
644 | */ | ||
645 | GNUNET_TRANSPORT_DisconnectPeerFunction disconnect_peer; | ||
646 | |||
647 | /** | ||
648 | * Function that can be used to force the plugin to disconnect from | ||
649 | * the given peer and cancel all previous transmissions (and their | ||
650 | * continuations). | ||
651 | */ | ||
652 | GNUNET_TRANSPORT_DisconnectSessionFunction disconnect_session; | ||
653 | |||
654 | /** | ||
655 | * Function that will be called whenever the transport service wants to | ||
656 | * notify the plugin that a session is still active and in use and | ||
657 | * therefore the session timeout for this session has to be updated | ||
658 | */ | ||
659 | GNUNET_TRANSPORT_UpdateSessionTimeout update_session_timeout; | ||
660 | |||
661 | /** | ||
662 | * Function that will be called whenever the transport service wants to | ||
663 | * notify the plugin that the inbound quota changed and that the plugin | ||
664 | * should update it's delay for the next receive value | ||
665 | */ | ||
666 | GNUNET_TRANSPORT_UpdateInboundDelay update_inbound_delay; | ||
667 | |||
668 | /** | ||
669 | * Function that is used to query keepalive factor. | ||
670 | * #GNUNET_CONSTANTS_IDLE_CONNECTION_TIMEOUT is divided by this number to | ||
671 | * calculate the interval between keepalive packets. | ||
672 | */ | ||
673 | GNUNET_TRANSPORT_QueryKeepaliveFactorFunction query_keepalive_factor; | ||
674 | |||
675 | /** | ||
676 | * Function to pretty-print addresses. | ||
677 | */ | ||
678 | GNUNET_TRANSPORT_AddressPrettyPrinter address_pretty_printer; | ||
679 | |||
680 | /** | ||
681 | * Function that will be called to check if a binary address | ||
682 | * for this plugin is well-formed and corresponds to an | ||
683 | * address for THIS peer (as per our configuration). Naturally, | ||
684 | * if absolutely necessary, plugins can be a bit conservative in | ||
685 | * their answer, but in general plugins should make sure that the | ||
686 | * address does not redirect traffic to a 3rd party that might | ||
687 | * try to man-in-the-middle our traffic. | ||
688 | */ | ||
689 | GNUNET_TRANSPORT_CheckAddress check_address; | ||
690 | |||
691 | /** | ||
692 | * Function that will be called to convert a binary address | ||
693 | * to a string (numeric conversion only). | ||
694 | */ | ||
695 | GNUNET_TRANSPORT_AddressToString address_to_string; | ||
696 | |||
697 | /** | ||
698 | * Function that will be called to convert a string address | ||
699 | * to binary (numeric conversion only). | ||
700 | */ | ||
701 | GNUNET_TRANSPORT_StringToAddress string_to_address; | ||
702 | |||
703 | /** | ||
704 | * Function that will be called tell the plugin to create a session | ||
705 | * object. | ||
706 | */ | ||
707 | GNUNET_TRANSPORT_CreateSession get_session; | ||
708 | |||
709 | /** | ||
710 | * Function to obtain the network type for a session | ||
711 | */ | ||
712 | GNUNET_TRANSPORT_GetNetworkType get_network; | ||
713 | |||
714 | /** | ||
715 | * Function to obtain the network type for an address | ||
716 | */ | ||
717 | GNUNET_TRANSPORT_GetNetworkTypeForAddress get_network_for_address; | ||
718 | |||
719 | /** | ||
720 | * Function to monitor the sessions managed by the plugin. | ||
721 | */ | ||
722 | GNUNET_TRANSPORT_SessionMonitorSetup setup_monitor; | ||
723 | }; | ||
724 | |||
725 | |||
726 | /*#ifndef PLUGIN_TRANSPORT_H*/ | ||
727 | #endif | ||
728 | |||
729 | /** @} */ /* end of group */ | ||
730 | |||
731 | /** @} */ /* end of group addition */ | ||
732 | |||
733 | /* end of gnunet_transport_plugin.h */ | ||