diff options
author | Christian Grothoff <christian@grothoff.org> | 2013-12-12 11:51:03 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2013-12-12 11:51:03 +0000 |
commit | 95659c78f10bb8a925bd2ba2e5287fa36562633b (patch) | |
tree | 954c4044c3d154ec82b0f0ec9b58d08ab43da67d /src/include/gnunet_transport_plugin.h | |
parent | cee16bdcf34ba0ea19b190464e41c62f1c467832 (diff) | |
download | gnunet-95659c78f10bb8a925bd2ba2e5287fa36562633b.tar.gz gnunet-95659c78f10bb8a925bd2ba2e5287fa36562633b.zip |
-extend transport plugin API with capability to just disconnect a single session (not yet used)
Diffstat (limited to 'src/include/gnunet_transport_plugin.h')
-rw-r--r-- | src/include/gnunet_transport_plugin.h | 209 |
1 files changed, 124 insertions, 85 deletions
diff --git a/src/include/gnunet_transport_plugin.h b/src/include/gnunet_transport_plugin.h index 7df04edfe..6bf365243 100644 --- a/src/include/gnunet_transport_plugin.h +++ b/src/include/gnunet_transport_plugin.h | |||
@@ -62,6 +62,7 @@ struct SessionHeader | |||
62 | /* empty, for now */ | 62 | /* empty, for now */ |
63 | }; | 63 | }; |
64 | 64 | ||
65 | |||
65 | /** | 66 | /** |
66 | * Function that will be called whenever the plugin internally | 67 | * Function that will be called whenever the plugin internally |
67 | * cleans up a session pointer and hence the service needs to | 68 | * cleans up a session pointer and hence the service needs to |
@@ -75,9 +76,10 @@ struct SessionHeader | |||
75 | * @param peer which peer was the session for | 76 | * @param peer which peer was the session for |
76 | * @param session which session is being destoyed | 77 | * @param session which session is being destoyed |
77 | */ | 78 | */ |
78 | typedef void (*GNUNET_TRANSPORT_SessionEnd) (void *cls, | 79 | typedef void |
79 | const struct GNUNET_PeerIdentity *peer, | 80 | (*GNUNET_TRANSPORT_SessionEnd) (void *cls, |
80 | struct Session * session); | 81 | const struct GNUNET_PeerIdentity *peer, |
82 | struct Session *session); | ||
81 | 83 | ||
82 | 84 | ||
83 | /** | 85 | /** |
@@ -93,17 +95,18 @@ typedef void (*GNUNET_TRANSPORT_SessionEnd) (void *cls, | |||
93 | * @param address_len length of the @a address | 95 | * @param address_len length of the @a address |
94 | * @param session session | 96 | * @param session session |
95 | * @param ats ATS information | 97 | * @param ats ATS information |
96 | * @param ats_count number of ATS information contained | 98 | * @param ats_count number of entries in @a ats array |
97 | */ | 99 | */ |
98 | typedef void | 100 | typedef void |
99 | (*GNUNET_TRANSPORT_SessionStart) (void *cls, | 101 | (*GNUNET_TRANSPORT_SessionStart) (void *cls, |
100 | const struct GNUNET_PeerIdentity *peer, | 102 | const struct GNUNET_PeerIdentity *peer, |
101 | const char *plugin, | 103 | const char *plugin, |
102 | const void *address, | 104 | const void *address, |
103 | uint16_t address_len, | 105 | uint16_t address_len, |
104 | struct Session *session, | 106 | struct Session *session, |
105 | const struct GNUNET_ATS_Information *ats, | 107 | const struct GNUNET_ATS_Information *ats, |
106 | uint32_t ats_count); | 108 | uint32_t ats_count); |
109 | |||
107 | 110 | ||
108 | /** | 111 | /** |
109 | * Function called by the transport for each received message. | 112 | * Function called by the transport for each received message. |
@@ -123,16 +126,17 @@ typedef void | |||
123 | * that we could establish ourselves a connection to that | 126 | * that we could establish ourselves a connection to that |
124 | * IP address and get the same system) | 127 | * IP address and get the same system) |
125 | * @param sender_address_len number of bytes in @a sender_address | 128 | * @param sender_address_len number of bytes in @a sender_address |
126 | * @return how long the plugin should wait until receiving more data | 129 | * @return how long the plugin should wait until receiving more data; |
127 | * (plugins that do not support this, can ignore the return value) | 130 | * returning #GNUNET_TIME_UNIT_FOREVER_REL means that the |
131 | * connection should be closed | ||
128 | */ | 132 | */ |
129 | typedef struct | 133 | typedef struct GNUNET_TIME_Relative |
130 | GNUNET_TIME_Relative (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, | 134 | (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, |
131 | const struct GNUNET_PeerIdentity *peer, | 135 | const struct GNUNET_PeerIdentity *peer, |
132 | const struct GNUNET_MessageHeader *message, | 136 | const struct GNUNET_MessageHeader *message, |
133 | struct Session *session, | 137 | struct Session *session, |
134 | const char *sender_address, | 138 | const char *sender_address, |
135 | uint16_t sender_address_len); | 139 | uint16_t sender_address_len); |
136 | 140 | ||
137 | 141 | ||
138 | /** | 142 | /** |
@@ -159,7 +163,7 @@ typedef struct GNUNET_ATS_Information | |||
159 | * @param address_len length of the @a address | 163 | * @param address_len length of the @a address |
160 | * @param session session | 164 | * @param session session |
161 | * @param ats ATS information | 165 | * @param ats ATS information |
162 | * @param ats_count number of ATS information contained in @a ats | 166 | * @param ats_count number entries in the @a ats array |
163 | */ | 167 | */ |
164 | typedef void | 168 | typedef void |
165 | (*GNUNET_TRANSPORT_UpdateAddressMetrics) (void *cls, | 169 | (*GNUNET_TRANSPORT_UpdateAddressMetrics) (void *cls, |
@@ -175,18 +179,19 @@ typedef void | |||
175 | * is aware that it might be reachable under. | 179 | * is aware that it might be reachable under. |
176 | * | 180 | * |
177 | * @param cls closure | 181 | * @param cls closure |
178 | * @param add_remove should the address added (YES) or removed (NO) from the | 182 | * @param add_remove should the address added (#GNUNET_YES) or removed (#GNUNET_NO) from the |
179 | * set of valid addresses? | 183 | * set of valid addresses? |
180 | * @param addr one of the addresses of the host | 184 | * @param addr one of the addresses of the host |
181 | * the specific address format depends on the transport | 185 | * the specific address format depends on the transport |
182 | * @param addrlen length of the address | 186 | * @param addrlen length of the @a addr |
183 | * @param dest_plugin plugin to use this address with | 187 | * @param dest_plugin plugin to use this address with |
184 | */ | 188 | */ |
185 | typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls, | 189 | typedef void |
186 | int add_remove, | 190 | (*GNUNET_TRANSPORT_AddressNotification) (void *cls, |
187 | const void *addr, | 191 | int add_remove, |
188 | size_t addrlen, | 192 | const void *addr, |
189 | const char *dest_plugin); | 193 | size_t addrlen, |
194 | const char *dest_plugin); | ||
190 | 195 | ||
191 | 196 | ||
192 | /** | 197 | /** |
@@ -202,18 +207,20 @@ typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls, | |||
202 | * @param peer which peer did we read data from | 207 | * @param peer which peer did we read data from |
203 | * @param amount_recved number of bytes read (can be zero) | 208 | * @param amount_recved number of bytes read (can be zero) |
204 | * @return how long to wait until reading more from this peer | 209 | * @return how long to wait until reading more from this peer |
205 | * (to enforce inbound quotas) | 210 | * (to enforce inbound quotas); returning #GNUNET_TIME_UNIT_FOREVER_REL |
211 | * means that the connection should be closed | ||
206 | */ | 212 | */ |
207 | typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_TrafficReport) (void *cls, | 213 | typedef struct GNUNET_TIME_Relative |
208 | const struct GNUNET_PeerIdentity* peer, | 214 | (*GNUNET_TRANSPORT_TrafficReport) (void *cls, |
209 | size_t amount_recved); | 215 | const struct GNUNET_PeerIdentity *peer, |
216 | size_t amount_recved); | ||
210 | 217 | ||
211 | 218 | ||
212 | /** | 219 | /** |
213 | * Function that returns a HELLO message. | 220 | * Function that returns a HELLO message. |
214 | */ | 221 | */ |
215 | typedef const struct GNUNET_MessageHeader * | 222 | typedef const struct GNUNET_MessageHeader * |
216 | (*GNUNET_TRANSPORT_GetHelloCallback) (void); | 223 | (*GNUNET_TRANSPORT_GetHelloCallback) (void); |
217 | 224 | ||
218 | 225 | ||
219 | /** | 226 | /** |
@@ -253,7 +260,6 @@ struct GNUNET_TRANSPORT_PluginEnvironment | |||
253 | */ | 260 | */ |
254 | GNUNET_TRANSPORT_PluginReceiveCallback receive; | 261 | GNUNET_TRANSPORT_PluginReceiveCallback receive; |
255 | 262 | ||
256 | |||
257 | /** | 263 | /** |
258 | * Function that returns our HELLO. | 264 | * Function that returns our HELLO. |
259 | */ | 265 | */ |
@@ -302,7 +308,7 @@ struct GNUNET_TRANSPORT_PluginEnvironment | |||
302 | 308 | ||
303 | 309 | ||
304 | /** | 310 | /** |
305 | * Function called by the GNUNET_TRANSPORT_TransmitFunction | 311 | * Function called by the #GNUNET_TRANSPORT_TransmitFunction |
306 | * upon "completion". In the case that a peer disconnects, | 312 | * upon "completion". In the case that a peer disconnects, |
307 | * this function must be called for each pending request | 313 | * this function must be called for each pending request |
308 | * (with a 'failure' indication) AFTER notifying the service | 314 | * (with a 'failure' indication) AFTER notifying the service |
@@ -320,11 +326,13 @@ struct GNUNET_TRANSPORT_PluginEnvironment | |||
320 | * @param size_on_wire bytes required on wire for transmission, | 326 | * @param size_on_wire bytes required on wire for transmission, |
321 | * 0 if result == #GNUNET_SYSERR | 327 | * 0 if result == #GNUNET_SYSERR |
322 | */ | 328 | */ |
323 | typedef void (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls, | 329 | typedef void |
324 | const struct GNUNET_PeerIdentity *target, | 330 | (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls, |
325 | int result, | 331 | const struct GNUNET_PeerIdentity *target, |
326 | size_t size_payload, | 332 | int result, |
327 | size_t size_on_wire); | 333 | size_t size_payload, |
334 | size_t size_on_wire); | ||
335 | |||
328 | 336 | ||
329 | /** | 337 | /** |
330 | * The new send function with just the session and no address | 338 | * The new send function with just the session and no address |
@@ -350,19 +358,37 @@ typedef void (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls, | |||
350 | * been transmitted (or if the transport is ready | 358 | * been transmitted (or if the transport is ready |
351 | * for the next transmission call; or if the | 359 | * for the next transmission call; or if the |
352 | * peer disconnected...); can be NULL | 360 | * peer disconnected...); can be NULL |
353 | * @param cont_cls closure for cont | 361 | * @param cont_cls closure for @a cont |
354 | * @return number of bytes used (on the physical network, with overheads); | 362 | * @return number of bytes used (on the physical network, with overheads); |
355 | * -1 on hard errors (i.e. address invalid); 0 is a legal value | 363 | * -1 on hard errors (i.e. address invalid); 0 is a legal value |
356 | * and does NOT mean that the message was not transmitted (DV) | 364 | * and does NOT mean that the message was not transmitted (DV) |
357 | */ | 365 | */ |
358 | typedef ssize_t (*GNUNET_TRANSPORT_TransmitFunction) (void *cls, | 366 | typedef ssize_t |
359 | struct Session *session, | 367 | (*GNUNET_TRANSPORT_TransmitFunction) (void *cls, |
360 | const char *msgbuf, | 368 | struct Session *session, |
361 | size_t msgbuf_size, | 369 | const char *msgbuf, |
362 | unsigned int priority, | 370 | size_t msgbuf_size, |
363 | struct GNUNET_TIME_Relative to, | 371 | unsigned int priority, |
364 | GNUNET_TRANSPORT_TransmitContinuation cont, | 372 | struct GNUNET_TIME_Relative to, |
365 | void *cont_cls); | 373 | GNUNET_TRANSPORT_TransmitContinuation cont, |
374 | void *cont_cls); | ||
375 | |||
376 | |||
377 | /** | ||
378 | * Function that can be called to force a disconnect from the | ||
379 | * specified neighbour for the given session only. . This should | ||
380 | * also cancel all previously scheduled transmissions for this | ||
381 | * session. Obviously the transmission may have been partially | ||
382 | * completed already, which is OK. The plugin is supposed to close | ||
383 | * the connection (if applicable). | ||
384 | * | ||
385 | * @param cls closure with the `struct Plugin` | ||
386 | * @param session session to destroy | ||
387 | * @return #GNUNET_OK on success | ||
388 | */ | ||
389 | typedef int | ||
390 | (*GNUNET_TRANSPORT_DisconnectSessionFunction) (void *cls, | ||
391 | struct Session *session); | ||
366 | 392 | ||
367 | 393 | ||
368 | /** | 394 | /** |
@@ -373,16 +399,13 @@ typedef ssize_t (*GNUNET_TRANSPORT_TransmitFunction) (void *cls, | |||
373 | * to close the connection (if applicable) and no longer call the | 399 | * to close the connection (if applicable) and no longer call the |
374 | * transmit continuation(s). | 400 | * transmit continuation(s). |
375 | * | 401 | * |
376 | * Finally, plugin MUST NOT call the services's receive function to | ||
377 | * notify the service that the connection to the specified target was | ||
378 | * closed after a getting this call. | ||
379 | * | ||
380 | * @param cls closure | 402 | * @param cls closure |
381 | * @param target peer for which the last transmission is | 403 | * @param target peer for which the last transmission is |
382 | * to be cancelled | 404 | * to be cancelled |
383 | */ | 405 | */ |
384 | typedef void (*GNUNET_TRANSPORT_DisconnectFunction) (void *cls, | 406 | typedef void |
385 | const struct GNUNET_PeerIdentity *target); | 407 | (*GNUNET_TRANSPORT_DisconnectPeerFunction) (void *cls, |
408 | const struct GNUNET_PeerIdentity *target); | ||
386 | 409 | ||
387 | 410 | ||
388 | /** | 411 | /** |
@@ -393,8 +416,9 @@ typedef void (*GNUNET_TRANSPORT_DisconnectFunction) (void *cls, | |||
393 | * @param address one of the names for the host, NULL | 416 | * @param address one of the names for the host, NULL |
394 | * on the last call to the callback | 417 | * on the last call to the callback |
395 | */ | 418 | */ |
396 | typedef void (*GNUNET_TRANSPORT_AddressStringCallback) (void *cls, | 419 | typedef void |
397 | const char *address); | 420 | (*GNUNET_TRANSPORT_AddressStringCallback) (void *cls, |
421 | const char *address); | ||
398 | 422 | ||
399 | 423 | ||
400 | /** | 424 | /** |
@@ -405,20 +429,21 @@ typedef void (*GNUNET_TRANSPORT_AddressStringCallback) (void *cls, | |||
405 | * @param type name of the transport that generated the address | 429 | * @param type name of the transport that generated the address |
406 | * @param addr one of the addresses of the host, NULL for the last address | 430 | * @param addr one of the addresses of the host, NULL for the last address |
407 | * the specific address format depends on the transport | 431 | * the specific address format depends on the transport |
408 | * @param addrlen length of the address | 432 | * @param addrlen length of the @a addr |
409 | * @param numeric should (IP) addresses be displayed in numeric form? | 433 | * @param numeric should (IP) addresses be displayed in numeric form? |
410 | * @param timeout after how long should we give up? | 434 | * @param timeout after how long should we give up? |
411 | * @param asc function to call on each string | 435 | * @param asc function to call on each string |
412 | * @param asc_cls closure for @a asc | 436 | * @param asc_cls closure for @a asc |
413 | */ | 437 | */ |
414 | typedef void (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls, | 438 | typedef void |
415 | const char *type, | 439 | (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls, |
416 | const void *addr, | 440 | const char *type, |
417 | size_t addrlen, | 441 | const void *addr, |
418 | int numeric, | 442 | size_t addrlen, |
419 | struct GNUNET_TIME_Relative timeout, | 443 | int numeric, |
420 | GNUNET_TRANSPORT_AddressStringCallback asc, | 444 | struct GNUNET_TIME_Relative timeout, |
421 | void *asc_cls); | 445 | GNUNET_TRANSPORT_AddressStringCallback asc, |
446 | void *asc_cls); | ||
422 | 447 | ||
423 | 448 | ||
424 | /** | 449 | /** |
@@ -435,9 +460,11 @@ typedef void (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls, | |||
435 | * @return #GNUNET_OK if this is a plausible address for this peer | 460 | * @return #GNUNET_OK if this is a plausible address for this peer |
436 | * and transport, #GNUNET_SYSERR if not | 461 | * and transport, #GNUNET_SYSERR if not |
437 | */ | 462 | */ |
438 | typedef int (*GNUNET_TRANSPORT_CheckAddress) (void *cls, | 463 | typedef int |
439 | const void *addr, | 464 | (*GNUNET_TRANSPORT_CheckAddress) (void *cls, |
440 | size_t addrlen); | 465 | const void *addr, |
466 | size_t addrlen); | ||
467 | |||
441 | 468 | ||
442 | /** | 469 | /** |
443 | * Create a new session to transmit data to the target | 470 | * Create a new session to transmit data to the target |
@@ -448,8 +475,9 @@ typedef int (*GNUNET_TRANSPORT_CheckAddress) (void *cls, | |||
448 | * @param address the hello address | 475 | * @param address the hello address |
449 | * @return the session if the address is valid, NULL otherwise | 476 | * @return the session if the address is valid, NULL otherwise |
450 | */ | 477 | */ |
451 | typedef struct Session * (*GNUNET_TRANSPORT_CreateSession) (void *cls, | 478 | typedef struct Session * |
452 | const struct GNUNET_HELLO_Address *address); | 479 | (*GNUNET_TRANSPORT_CreateSession) (void *cls, |
480 | const struct GNUNET_HELLO_Address *address); | ||
453 | 481 | ||
454 | 482 | ||
455 | /** | 483 | /** |
@@ -460,30 +488,33 @@ typedef struct Session * (*GNUNET_TRANSPORT_CreateSession) (void *cls, | |||
460 | * | 488 | * |
461 | * @param cls closure | 489 | * @param cls closure |
462 | * @param addr binary address | 490 | * @param addr binary address |
463 | * @param addr_len length of the address | 491 | * @param addr_len length of the @a addr |
464 | * @return string representing the same address | 492 | * @return string representing the same address |
465 | */ | 493 | */ |
466 | typedef const char *(*GNUNET_TRANSPORT_AddressToString) (void *cls, | 494 | typedef const char * |
467 | const void *addr, | 495 | (*GNUNET_TRANSPORT_AddressToString) (void *cls, |
468 | size_t addrlen); | 496 | const void *addr, |
497 | size_t addrlen); | ||
498 | |||
469 | 499 | ||
470 | /** | 500 | /** |
471 | * Function called to convert a string address to | 501 | * Function called to convert a string address to |
472 | * a binary address. | 502 | * a binary address. |
473 | * | 503 | * |
474 | * @param cls closure ('struct Plugin*') | 504 | * @param cls closure (`struct Plugin*`) |
475 | * @param addr string address | 505 | * @param addr string address |
476 | * @param addrlen length of the address including '\0' termination | 506 | * @param addrlen length of the @a addr including \0 termination |
477 | * @param buf location to store the buffer | 507 | * @param buf location to store the buffer |
478 | * If the function returns #GNUNET_SYSERR, its contents are undefined. | 508 | * If the function returns #GNUNET_SYSERR, its contents are undefined. |
479 | * @param added length of created address | 509 | * @param added length of created address |
480 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | 510 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
481 | */ | 511 | */ |
482 | typedef int (*GNUNET_TRANSPORT_StringToAddress) (void *cls, | 512 | typedef int |
483 | const char *addr, | 513 | (*GNUNET_TRANSPORT_StringToAddress) (void *cls, |
484 | uint16_t addrlen, | 514 | const char *addr, |
485 | void **buf, | 515 | uint16_t addrlen, |
486 | size_t *added); | 516 | void **buf, |
517 | size_t *added); | ||
487 | 518 | ||
488 | 519 | ||
489 | /** | 520 | /** |
@@ -493,8 +524,9 @@ typedef int (*GNUNET_TRANSPORT_StringToAddress) (void *cls, | |||
493 | * @param session the session | 524 | * @param session the session |
494 | * @return the network type | 525 | * @return the network type |
495 | */ | 526 | */ |
496 | typedef enum GNUNET_ATS_Network_Type (*GNUNET_TRANSPORT_GetNetworkType) (void *cls, | 527 | typedef enum GNUNET_ATS_Network_Type |
497 | struct Session *session); | 528 | (*GNUNET_TRANSPORT_GetNetworkType) (void *cls, |
529 | struct Session *session); | ||
498 | 530 | ||
499 | 531 | ||
500 | /** | 532 | /** |
@@ -523,7 +555,14 @@ struct GNUNET_TRANSPORT_PluginFunctions | |||
523 | * the given peer and cancel all previous transmissions (and their | 555 | * the given peer and cancel all previous transmissions (and their |
524 | * continuations). | 556 | * continuations). |
525 | */ | 557 | */ |
526 | GNUNET_TRANSPORT_DisconnectFunction disconnect; | 558 | GNUNET_TRANSPORT_DisconnectPeerFunction disconnect_peer; |
559 | |||
560 | /** | ||
561 | * Function that can be used to force the plugin to disconnect from | ||
562 | * the given peer and cancel all previous transmissions (and their | ||
563 | * continuations). | ||
564 | */ | ||
565 | GNUNET_TRANSPORT_DisconnectSessionFunction disconnect_session; | ||
527 | 566 | ||
528 | /** | 567 | /** |
529 | * Function to pretty-print addresses. NOTE: this function is not | 568 | * Function to pretty-print addresses. NOTE: this function is not |