diff options
author | ng0 <ng0@n0.is> | 2019-04-29 13:01:19 +0000 |
---|---|---|
committer | ng0 <ng0@n0.is> | 2019-04-29 13:01:19 +0000 |
commit | ca3490588cff768b56ae75f0de69fd89529dc6dd (patch) | |
tree | 6614fc2b03483468c78aec28ad6ff3088703d17a /src/include/gnunet_transport_service.h | |
parent | 2586e14e12b6c939ed5fad3f69f86b4ee7df4b6e (diff) | |
parent | a443a9c5fd148b7f4f01159964b5f69748d632f2 (diff) | |
download | gnunet-ca3490588cff768b56ae75f0de69fd89529dc6dd.tar.gz gnunet-ca3490588cff768b56ae75f0de69fd89529dc6dd.zip |
Merge branch 'master' of gnunet.org:gnunet
Diffstat (limited to 'src/include/gnunet_transport_service.h')
-rw-r--r-- | src/include/gnunet_transport_service.h | 232 |
1 files changed, 174 insertions, 58 deletions
diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h index c5cb10ad8..80949b417 100644 --- a/src/include/gnunet_transport_service.h +++ b/src/include/gnunet_transport_service.h | |||
@@ -11,7 +11,7 @@ | |||
11 | WITHOUT ANY WARRANTY; without even the implied warranty of | 11 | WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | 12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Affero General Public License for more details. | 13 | Affero General Public License for more details. |
14 | 14 | ||
15 | You should have received a copy of the GNU Affero General Public License | 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/>. | 16 | along with this program. If not, see <http://www.gnu.org/licenses/>. |
17 | 17 | ||
@@ -36,9 +36,8 @@ | |||
36 | #define GNUNET_TRANSPORT_SERVICE_H | 36 | #define GNUNET_TRANSPORT_SERVICE_H |
37 | 37 | ||
38 | #ifdef __cplusplus | 38 | #ifdef __cplusplus |
39 | extern "C" | 39 | extern "C" { |
40 | { | 40 | #if 0 /* keep Emacsens' auto-indent happy */ |
41 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
42 | } | 41 | } |
43 | #endif | 42 | #endif |
44 | #endif | 43 | #endif |
@@ -71,8 +70,8 @@ struct GNUNET_TRANSPORT_OfferHelloHandle; | |||
71 | * tc reason #GNUNET_SCHEDULER_REASON_TIMEOUT for fail | 70 | * tc reason #GNUNET_SCHEDULER_REASON_TIMEOUT for fail |
72 | * tc reasong #GNUNET_SCHEDULER_REASON_READ_READY for success | 71 | * tc reasong #GNUNET_SCHEDULER_REASON_READ_READY for success |
73 | * @param cont_cls closure for @a cont | 72 | * @param cont_cls closure for @a cont |
74 | * @return a `struct GNUNET_TRANSPORT_OfferHelloHandle` handle or NULL on failure, | 73 | * @return a `struct GNUNET_TRANSPORT_OfferHelloHandle` handle or NULL on |
75 | * in case of failure @a cont will not be called | 74 | * failure, in case of failure @a cont will not be called |
76 | * | 75 | * |
77 | */ | 76 | */ |
78 | struct GNUNET_TRANSPORT_OfferHelloHandle * | 77 | struct GNUNET_TRANSPORT_OfferHelloHandle * |
@@ -88,7 +87,8 @@ GNUNET_TRANSPORT_offer_hello (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
88 | * @param ohh the `struct GNUNET_TRANSPORT_OfferHelloHandle` to cancel | 87 | * @param ohh the `struct GNUNET_TRANSPORT_OfferHelloHandle` to cancel |
89 | */ | 88 | */ |
90 | void | 89 | void |
91 | GNUNET_TRANSPORT_offer_hello_cancel (struct GNUNET_TRANSPORT_OfferHelloHandle *ohh); | 90 | GNUNET_TRANSPORT_offer_hello_cancel ( |
91 | struct GNUNET_TRANSPORT_OfferHelloHandle *ohh); | ||
92 | 92 | ||
93 | 93 | ||
94 | /* *********************** Address to String ******************* */ | 94 | /* *********************** Address to String ******************* */ |
@@ -115,10 +115,9 @@ struct GNUNET_TRANSPORT_AddressToStringContext; | |||
115 | * if #GNUNET_NO: address was invalid (or not supported) | 115 | * if #GNUNET_NO: address was invalid (or not supported) |
116 | * if #GNUNET_SYSERR: communication error (IPC error) | 116 | * if #GNUNET_SYSERR: communication error (IPC error) |
117 | */ | 117 | */ |
118 | typedef void | 118 | typedef void (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls, |
119 | (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls, | 119 | const char *address, |
120 | const char *address, | 120 | int res); |
121 | int res); | ||
122 | 121 | ||
123 | 122 | ||
124 | /** | 123 | /** |
@@ -134,12 +133,13 @@ typedef void | |||
134 | * @return handle to cancel the operation, NULL on error | 133 | * @return handle to cancel the operation, NULL on error |
135 | */ | 134 | */ |
136 | struct GNUNET_TRANSPORT_AddressToStringContext * | 135 | struct GNUNET_TRANSPORT_AddressToStringContext * |
137 | GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle *cfg, | 136 | GNUNET_TRANSPORT_address_to_string ( |
138 | const struct GNUNET_HELLO_Address *address, | 137 | const struct GNUNET_CONFIGURATION_Handle *cfg, |
139 | int numeric, | 138 | const struct GNUNET_HELLO_Address *address, |
140 | struct GNUNET_TIME_Relative timeout, | 139 | int numeric, |
141 | GNUNET_TRANSPORT_AddressToStringCallback aluc, | 140 | struct GNUNET_TIME_Relative timeout, |
142 | void *aluc_cls); | 141 | GNUNET_TRANSPORT_AddressToStringCallback aluc, |
142 | void *aluc_cls); | ||
143 | 143 | ||
144 | 144 | ||
145 | /** | 145 | /** |
@@ -148,14 +148,16 @@ GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle *cf | |||
148 | * @param alc the context handle | 148 | * @param alc the context handle |
149 | */ | 149 | */ |
150 | void | 150 | void |
151 | GNUNET_TRANSPORT_address_to_string_cancel (struct GNUNET_TRANSPORT_AddressToStringContext *alc); | 151 | GNUNET_TRANSPORT_address_to_string_cancel ( |
152 | struct GNUNET_TRANSPORT_AddressToStringContext *alc); | ||
152 | 153 | ||
153 | 154 | ||
154 | /* *********************** Monitoring ************************** */ | 155 | /* *********************** Monitoring ************************** */ |
155 | 156 | ||
156 | 157 | ||
157 | /** | 158 | /** |
158 | * Possible state of a neighbour. Initially, we are #GNUNET_TRANSPORT_PS_NOT_CONNECTED. | 159 | * Possible state of a neighbour. Initially, we are |
160 | * #GNUNET_TRANSPORT_PS_NOT_CONNECTED. | ||
159 | * | 161 | * |
160 | * Then, there are two main paths. If we receive a SYN message, we give | 162 | * Then, there are two main paths. If we receive a SYN message, we give |
161 | * the inbound address to ATS. After the check we ask ATS for a suggestion | 163 | * the inbound address to ATS. After the check we ask ATS for a suggestion |
@@ -174,14 +176,14 @@ GNUNET_TRANSPORT_address_to_string_cancel (struct GNUNET_TRANSPORT_AddressToStri | |||
174 | * #GNUNET_TRANSPORT_PS_DISCONNECT. | 176 | * #GNUNET_TRANSPORT_PS_DISCONNECT. |
175 | * | 177 | * |
176 | * If the session is in trouble (i.e. transport-level disconnect or | 178 | * If the session is in trouble (i.e. transport-level disconnect or |
177 | * timeout), we go to #GNUNET_TRANSPORT_PS_RECONNECT_ATS where we ask ATS for a new | 179 | * timeout), we go to #GNUNET_TRANSPORT_PS_RECONNECT_ATS where we ask ATS for a |
178 | * address (we don't notify anyone about the disconnect yet). Once we | 180 | * new address (we don't notify anyone about the disconnect yet). Once we have |
179 | * have a new address, we enter #GNUNET_TRANSPORT_PS_RECONNECT_SENT and send a | 181 | * a new address, we enter #GNUNET_TRANSPORT_PS_RECONNECT_SENT and send a SYN |
180 | * SYN message. If we receive a | 182 | * message. If we receive a SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED |
181 | * SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED and nobody noticed that we had | 183 | * and nobody noticed that we had trouble; we also send a ACK at this time just |
182 | * trouble; we also send a ACK at this time just in case. If | 184 | * in case. If the operation times out, we go to |
183 | * the operation times out, we go to #GNUNET_TRANSPORT_PS_DISCONNECT (and notify everyone | 185 | * #GNUNET_TRANSPORT_PS_DISCONNECT (and notify everyone about the lost |
184 | * about the lost connection). | 186 | * connection). |
185 | * | 187 | * |
186 | * If ATS decides to switch addresses while we have a normal | 188 | * If ATS decides to switch addresses while we have a normal |
187 | * connection, we go to #GNUNET_TRANSPORT_PS_CONNECTED_SWITCHING_SYN_SENT | 189 | * connection, we go to #GNUNET_TRANSPORT_PS_CONNECTED_SWITCHING_SYN_SENT |
@@ -189,13 +191,14 @@ GNUNET_TRANSPORT_address_to_string_cancel (struct GNUNET_TRANSPORT_AddressToStri | |||
189 | * primary connection to the suggested alternative from ATS, go back | 191 | * primary connection to the suggested alternative from ATS, go back |
190 | * to #GNUNET_TRANSPORT_PS_CONNECTED and send a ACK to the other peer just to be | 192 | * to #GNUNET_TRANSPORT_PS_CONNECTED and send a ACK to the other peer just to be |
191 | * sure. If the operation times out | 193 | * sure. If the operation times out |
192 | * we go to #GNUNET_TRANSPORT_PS_CONNECTED (and notify ATS that the given alternative | 194 | * we go to #GNUNET_TRANSPORT_PS_CONNECTED (and notify ATS that the given |
193 | * address is "invalid"). | 195 | * alternative address is "invalid"). |
194 | * | 196 | * |
195 | * Once a session is in #GNUNET_TRANSPORT_PS_DISCONNECT, it is cleaned up and then goes | 197 | * Once a session is in #GNUNET_TRANSPORT_PS_DISCONNECT, it is cleaned up and |
196 | * to (#GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED). If we receive an explicit disconnect | 198 | * then goes to (#GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED). If we receive an |
197 | * request, we can go from any state to #GNUNET_TRANSPORT_PS_DISCONNECT, possibly after | 199 | * explicit disconnect request, we can go from any state to |
198 | * generating disconnect notifications. | 200 | * #GNUNET_TRANSPORT_PS_DISCONNECT, possibly after generating disconnect |
201 | * notifications. | ||
199 | * | 202 | * |
200 | * Note that it is quite possible that while we are in any of these | 203 | * Note that it is quite possible that while we are in any of these |
201 | * states, we could receive a 'SYN' request from the other peer. | 204 | * states, we could receive a 'SYN' request from the other peer. |
@@ -323,12 +326,12 @@ struct GNUNET_TRANSPORT_PeerMonitoringContext; | |||
323 | * @param state current state this peer is in | 326 | * @param state current state this peer is in |
324 | * @param state_timeout timeout for the current state of the peer | 327 | * @param state_timeout timeout for the current state of the peer |
325 | */ | 328 | */ |
326 | typedef void | 329 | typedef void (*GNUNET_TRANSPORT_PeerIterateCallback) ( |
327 | (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls, | 330 | void *cls, |
328 | const struct GNUNET_PeerIdentity *peer, | 331 | const struct GNUNET_PeerIdentity *peer, |
329 | const struct GNUNET_HELLO_Address *address, | 332 | const struct GNUNET_HELLO_Address *address, |
330 | enum GNUNET_TRANSPORT_PeerState state, | 333 | enum GNUNET_TRANSPORT_PeerState state, |
331 | struct GNUNET_TIME_Absolute state_timeout); | 334 | struct GNUNET_TIME_Absolute state_timeout); |
332 | 335 | ||
333 | 336 | ||
334 | /** | 337 | /** |
@@ -352,17 +355,18 @@ typedef void | |||
352 | * @param cfg configuration to use | 355 | * @param cfg configuration to use |
353 | * @param peer a specific peer identity to obtain information for, | 356 | * @param peer a specific peer identity to obtain information for, |
354 | * NULL for all peers | 357 | * NULL for all peers |
355 | * @param one_shot #GNUNET_YES to return the current state and then end (with NULL+NULL), | 358 | * @param one_shot #GNUNET_YES to return the current state and then end (with |
356 | * #GNUNET_NO to monitor peers continuously | 359 | * NULL+NULL), #GNUNET_NO to monitor peers continuously |
357 | * @param peer_callback function to call with the results | 360 | * @param peer_callback function to call with the results |
358 | * @param peer_callback_cls closure for @a peer_callback | 361 | * @param peer_callback_cls closure for @a peer_callback |
359 | */ | 362 | */ |
360 | struct GNUNET_TRANSPORT_PeerMonitoringContext * | 363 | struct GNUNET_TRANSPORT_PeerMonitoringContext * |
361 | GNUNET_TRANSPORT_monitor_peers (const struct GNUNET_CONFIGURATION_Handle *cfg, | 364 | GNUNET_TRANSPORT_monitor_peers ( |
362 | const struct GNUNET_PeerIdentity *peer, | 365 | const struct GNUNET_CONFIGURATION_Handle *cfg, |
363 | int one_shot, | 366 | const struct GNUNET_PeerIdentity *peer, |
364 | GNUNET_TRANSPORT_PeerIterateCallback peer_callback, | 367 | int one_shot, |
365 | void *peer_callback_cls); | 368 | GNUNET_TRANSPORT_PeerIterateCallback peer_callback, |
369 | void *peer_callback_cls); | ||
366 | 370 | ||
367 | 371 | ||
368 | /** | 372 | /** |
@@ -371,7 +375,8 @@ GNUNET_TRANSPORT_monitor_peers (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
371 | * @param pic handle for the request to cancel | 375 | * @param pic handle for the request to cancel |
372 | */ | 376 | */ |
373 | void | 377 | void |
374 | GNUNET_TRANSPORT_monitor_peers_cancel (struct GNUNET_TRANSPORT_PeerMonitoringContext *pic); | 378 | GNUNET_TRANSPORT_monitor_peers_cancel ( |
379 | struct GNUNET_TRANSPORT_PeerMonitoringContext *pic); | ||
375 | 380 | ||
376 | 381 | ||
377 | /* *********************** Blacklisting ************************ */ | 382 | /* *********************** Blacklisting ************************ */ |
@@ -389,9 +394,9 @@ struct GNUNET_TRANSPORT_Blacklist; | |||
389 | * @param pid peer to approve or disapproave | 394 | * @param pid peer to approve or disapproave |
390 | * @return #GNUNET_OK if the connection is allowed, #GNUNET_SYSERR if not | 395 | * @return #GNUNET_OK if the connection is allowed, #GNUNET_SYSERR if not |
391 | */ | 396 | */ |
392 | typedef int | 397 | typedef int (*GNUNET_TRANSPORT_BlacklistCallback) ( |
393 | (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls, | 398 | void *cls, |
394 | const struct GNUNET_PeerIdentity *pid); | 399 | const struct GNUNET_PeerIdentity *pid); |
395 | 400 | ||
396 | 401 | ||
397 | /** | 402 | /** |
@@ -539,11 +544,11 @@ struct GNUNET_TRANSPORT_SessionInfo | |||
539 | * NULL with @a session being non-NULL if the monitor | 544 | * NULL with @a session being non-NULL if the monitor |
540 | * was being cancelled while sessions were active | 545 | * was being cancelled while sessions were active |
541 | */ | 546 | */ |
542 | typedef void | 547 | typedef void (*GNUNET_TRANSPORT_SessionMonitorCallback) ( |
543 | (*GNUNET_TRANSPORT_SessionMonitorCallback) (void *cls, | 548 | void *cls, |
544 | struct GNUNET_TRANSPORT_PluginSession *session, | 549 | struct GNUNET_TRANSPORT_PluginSession *session, |
545 | void **session_ctx, | 550 | void **session_ctx, |
546 | const struct GNUNET_TRANSPORT_SessionInfo *info); | 551 | const struct GNUNET_TRANSPORT_SessionInfo *info); |
547 | 552 | ||
548 | 553 | ||
549 | /** | 554 | /** |
@@ -569,11 +574,122 @@ GNUNET_TRANSPORT_monitor_plugins (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
569 | * @param pm handle of the request that is to be cancelled | 574 | * @param pm handle of the request that is to be cancelled |
570 | */ | 575 | */ |
571 | void | 576 | void |
572 | GNUNET_TRANSPORT_monitor_plugins_cancel (struct GNUNET_TRANSPORT_PluginMonitor *pm); | 577 | GNUNET_TRANSPORT_monitor_plugins_cancel ( |
578 | struct GNUNET_TRANSPORT_PluginMonitor *pm); | ||
579 | |||
580 | |||
581 | /** | ||
582 | * Opaque handle to the service. | ||
583 | */ | ||
584 | struct GNUNET_TRANSPORT_CoreHandle; | ||
585 | |||
586 | |||
587 | /** | ||
588 | * Function called to notify transport users that another | ||
589 | * peer connected to us. | ||
590 | * | ||
591 | * @param cls closure | ||
592 | * @param peer the identity of the peer that connected; this | ||
593 | * pointer will remain valid until the disconnect, hence | ||
594 | * applications do not necessarily have to make a copy | ||
595 | * of the value if they only need it until disconnect | ||
596 | * @param mq message queue to use to transmit to @a peer | ||
597 | * @return closure to use in MQ handlers | ||
598 | */ | ||
599 | typedef void *(*GNUNET_TRANSPORT_NotifyConnect) ( | ||
600 | void *cls, | ||
601 | const struct GNUNET_PeerIdentity *peer, | ||
602 | struct GNUNET_MQ_Handle *mq); | ||
603 | |||
604 | |||
605 | /** | ||
606 | * Function called to notify transport users that another peer | ||
607 | * disconnected from us. The message queue that was given to the | ||
608 | * connect notification will be destroyed and must not be used | ||
609 | * henceforth. | ||
610 | * | ||
611 | * @param cls closure from #GNUNET_TRANSPORT_core_connect | ||
612 | * @param peer the peer that disconnected | ||
613 | * @param handlers_cls closure of the handlers, was returned from the | ||
614 | * connect notification callback | ||
615 | */ | ||
616 | typedef void (*GNUNET_TRANSPORT_NotifyDisconnect) ( | ||
617 | void *cls, | ||
618 | const struct GNUNET_PeerIdentity *peer, | ||
619 | void *handler_cls); | ||
620 | |||
621 | |||
622 | /** | ||
623 | * Function called if we have "excess" bandwidth to a peer. | ||
624 | * The notification will happen the first time we have excess | ||
625 | * bandwidth, and then only again after the client has performed | ||
626 | * some transmission to the peer. | ||
627 | * | ||
628 | * Excess bandwidth is defined as being allowed (by ATS) to send | ||
629 | * more data, and us reaching the limit of the capacity build-up | ||
630 | * (which, if we go past it, means we don't use available bandwidth). | ||
631 | * See also the "max carry" in `struct GNUNET_BANDWIDTH_Tracker`. | ||
632 | * | ||
633 | * @param cls the closure | ||
634 | * @param neighbour peer that we have excess bandwidth to | ||
635 | * @param handlers_cls closure of the handlers, was returned from the | ||
636 | * connect notification callback | ||
637 | */ | ||
638 | typedef void (*GNUNET_TRANSPORT_NotifyExcessBandwidth) ( | ||
639 | void *cls, | ||
640 | const struct GNUNET_PeerIdentity *neighbour, | ||
641 | void *handlers_cls); | ||
642 | |||
643 | |||
644 | /** | ||
645 | * Connect to the transport service. Note that the connection may | ||
646 | * complete (or fail) asynchronously. | ||
647 | * | ||
648 | * @param cfg configuration to use | ||
649 | * @param self our own identity (API should check that it matches | ||
650 | * the identity found by transport), or NULL (no check) | ||
651 | * @param handlers array of message handlers; note that the | ||
652 | * closures provided will be ignored and replaced | ||
653 | * with the respective return value from @a nc | ||
654 | * @param handlers array with handlers to call when we receive messages, or NULL | ||
655 | * @param cls closure for the @a nc, @a nd and @a neb callbacks | ||
656 | * @param nc function to call on connect events, or NULL | ||
657 | * @param nd function to call on disconnect events, or NULL | ||
658 | * @param neb function to call if we have excess bandwidth to a peer, or NULL | ||
659 | * @return NULL on error | ||
660 | */ | ||
661 | struct GNUNET_TRANSPORT_CoreHandle * | ||
662 | GNUNET_TRANSPORT_core_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
663 | const struct GNUNET_PeerIdentity *self, | ||
664 | const struct GNUNET_MQ_MessageHandler *handlers, | ||
665 | void *cls, | ||
666 | GNUNET_TRANSPORT_NotifyConnect nc, | ||
667 | GNUNET_TRANSPORT_NotifyDisconnect nd, | ||
668 | GNUNET_TRANSPORT_NotifyExcessBandwidth neb); | ||
669 | |||
670 | |||
671 | /** | ||
672 | * Disconnect from the transport service. | ||
673 | * | ||
674 | * @param handle handle returned from connect | ||
675 | */ | ||
676 | void | ||
677 | GNUNET_TRANSPORT_core_disconnect (struct GNUNET_TRANSPORT_CoreHandle *handle); | ||
573 | 678 | ||
574 | 679 | ||
680 | /** | ||
681 | * Checks if a given peer is connected to us and get the message queue. | ||
682 | * | ||
683 | * @param handle connection to transport service | ||
684 | * @param peer the peer to check | ||
685 | * @return NULL if disconnected, otherwise message queue for @a peer | ||
686 | */ | ||
687 | struct GNUNET_MQ_Handle * | ||
688 | GNUNET_TRANSPORT_core_get_mq (struct GNUNET_TRANSPORT_CoreHandle *handle, | ||
689 | const struct GNUNET_PeerIdentity *peer); | ||
690 | |||
575 | 691 | ||
576 | #if 0 /* keep Emacsens' auto-indent happy */ | 692 | #if 0 /* keep Emacsens' auto-indent happy */ |
577 | { | 693 | { |
578 | #endif | 694 | #endif |
579 | #ifdef __cplusplus | 695 | #ifdef __cplusplus |
@@ -583,6 +699,6 @@ GNUNET_TRANSPORT_monitor_plugins_cancel (struct GNUNET_TRANSPORT_PluginMonitor * | |||
583 | /* ifndef GNUNET_TRANSPORT_SERVICE_H */ | 699 | /* ifndef GNUNET_TRANSPORT_SERVICE_H */ |
584 | #endif | 700 | #endif |
585 | 701 | ||
586 | /** @} */ /* end of group */ | 702 | /** @} */ /* end of group */ |
587 | 703 | ||
588 | /* end of gnunet_transport_service.h */ | 704 | /* end of gnunet_transport_service.h */ |