X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_transport_plugin.h;h=d95e9f4e9cf411b0d6521bfa9134faf8a7f3be1f;hb=a6fb0db57f2a70a05bdb6ef7ccf69a044268dee6;hp=40f134db06b0bd7a843c9c6eaf1c5cdee77e1ed2;hpb=8a3016481ba6aeb36de3950a56e641dda53ca544;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_transport_plugin.h b/src/include/gnunet_transport_plugin.h index 40f134db0..d95e9f4e9 100644 --- a/src/include/gnunet_transport_plugin.h +++ b/src/include/gnunet_transport_plugin.h @@ -63,7 +63,7 @@ struct SessionHeader * Expiration time for signature. Do not use in the plugin! */ struct GNUNET_TIME_Absolute pong_sig_expires; - + }; /** @@ -71,15 +71,17 @@ struct SessionHeader * cleans up a session pointer and hence the service needs to * discard all of those sessions as well. Plugins that do not * use sessions can simply omit calling this function and always - * use NULL wherever a session pointer is needed. - * + * use NULL wherever a session pointer is needed. This function + * should be called BEFORE a potential "TransmitContinuation" + * from the "TransmitFunction". + * * @param cls closure - * @param peer which peer was the session for + * @param peer which peer was the session for * @param session which session is being destoyed */ typedef void (*GNUNET_TRANSPORT_SessionEnd) (void *cls, - const struct GNUNET_PeerIdentity *peer, - struct Session *session); + const struct GNUNET_PeerIdentity * + peer, struct Session * session); /** @@ -90,8 +92,7 @@ typedef void (*GNUNET_TRANSPORT_SessionEnd) (void *cls, * @param cls closure * @param peer (claimed) identity of the other peer * @param message the message, NULL if we only care about - * learning about the delay until we should receive again -- FIXME! - * @param distance in overlay hops; use 1 unless DV (or 0 if message == NULL) + * learning about the delay until we should receive again * @param session identifier used for this session (NULL for plugins * that do not offer bi-directional communication to the sender * using the same "connection") @@ -104,19 +105,41 @@ typedef void (*GNUNET_TRANSPORT_SessionEnd) (void *cls, * @return how long the plugin should wait until receiving more data * (plugins that do not support this, can ignore the return value) */ -typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, - const struct - GNUNET_PeerIdentity * - peer, - const struct - GNUNET_MessageHeader * - message, - const struct GNUNET_TRANSPORT_ATS_Information *ats, - uint32_t ats_count, - struct Session *session, - const char *sender_address, - uint16_t sender_address_len); +typedef struct + GNUNET_TIME_Relative (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, + const struct + GNUNET_PeerIdentity + * peer, + const struct + GNUNET_MessageHeader + * message, + const struct + GNUNET_ATS_Information + * ats, + uint32_t + ats_count, + struct + Session * + session, + const char + *sender_address, + uint16_t + sender_address_len); + +/** + * Function that will be called to figure if an address is an loopback, + * LAN, WAN etc. address + * + * @param cls closure + * @param addr binary address + * @param addrlen length of the address + * @return ATS Information containing the network type + */ +typedef const struct GNUNET_ATS_Information +(*GNUNET_TRANSPORT_AddressToType) (void *cls, + const struct sockaddr *addr, + size_t addrlen); /** * Function that will be called for each address the transport @@ -129,8 +152,7 @@ typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_PluginReceiveCallback) (v * the specific address format depends on the transport * @param addrlen length of the address */ -typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls, - int add_remove, +typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls, int add_remove, const void *addr, size_t addrlen); @@ -150,29 +172,22 @@ typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls, * @return how long to wait until reading more from this peer * (to enforce inbound quotas) */ -typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_TrafficReport) (void *cls, - const struct - GNUNET_PeerIdentity *peer, - size_t amount_recved); +typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_TrafficReport) (void + *cls, + const + struct + GNUNET_PeerIdentity + * peer, + size_t + amount_recved); + /** - * Function called whenever the plugin has to notify ATS about costs for using this transport - * - * The cost will be passed as struct GNUNET_TRANSPORT_ATS_Cost_Information[] - * This array is 0-terminated, so the last element will be a pair: - * ((cost->cost_type==GNUNET_TRANSPORT_ATS_ARRAY_TERMINATOR) && cost->cost_value==0)) - * - * @param cls closure - * @param peer peer - * @param addr peer address - * @param addrlen address length - * @param cost pointer to the first element of struct GNUNET_TRANSPORT_ATS_Cost_Information[] + * Function that returns a HELLO message. */ -typedef void (*GNUNET_TRANSPORT_CostReport) (void *cls, - const struct GNUNET_PeerIdentity *peer, - const void *addr, - uint16_t addrlen, - struct GNUNET_TRANSPORT_ATS_Information * cost); +typedef const struct GNUNET_MessageHeader + *(*GNUNET_TRANSPORT_GetHelloCallback) (void); + /** * The transport service will pass a pointer to a struct @@ -191,12 +206,6 @@ struct GNUNET_TRANSPORT_PluginEnvironment */ const struct GNUNET_PeerIdentity *my_identity; - /** - * Pointer (!) to our HELLO message. Note that the address - * referred to "*our_hello" might change over time. - */ - struct GNUNET_HELLO_Message *const*our_hello; - /** * Closure for the various callbacks. */ @@ -213,6 +222,12 @@ struct GNUNET_TRANSPORT_PluginEnvironment */ GNUNET_TRANSPORT_PluginReceiveCallback receive; + + /** + * Function that returns our HELLO. + */ + GNUNET_TRANSPORT_GetHelloCallback get_our_hello; + /** * Function that must be called by each plugin to notify the * transport service about the addresses under which the transport @@ -220,12 +235,6 @@ struct GNUNET_TRANSPORT_PluginEnvironment */ GNUNET_TRANSPORT_AddressNotification notify_address; - /** - * Inform service about traffic received, get information - * about when we might be willing to receive more. - */ - GNUNET_TRANSPORT_TrafficReport traffic_report; - /** * Function that must be called by the plugin when a non-NULL * session handle stops being valid (is destroyed). @@ -233,9 +242,11 @@ struct GNUNET_TRANSPORT_PluginEnvironment GNUNET_TRANSPORT_SessionEnd session_end; /** - * Inform service about costs for using this transport plugin + * Function that will be called to figure if an address is an loopback, + * LAN, WAN etc. address */ - GNUNET_TRANSPORT_CostReport cost_report; + GNUNET_TRANSPORT_AddressToType get_address_type; + /** * What is the maximum number of connections that this transport @@ -263,13 +274,69 @@ struct GNUNET_TRANSPORT_PluginEnvironment * disconnect will ALSO be signalled using * the ReceiveCallback. */ -typedef void - (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls, - const struct GNUNET_PeerIdentity * - target, int result); +typedef void (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls, + const struct + GNUNET_PeerIdentity * + target, int result); + + +/** + * Function that can be used by the transport service to transmit + * a message using the plugin. Note that in the case of a + * peer disconnecting, the continuation MUST be called + * prior to the disconnect notification itself. This function + * will be called with this peer's HELLO message to initiate + * a fresh connection to another peer. + * + * @param cls closure + * @param target who should receive this message + * @param msgbuf the message to transmit + * @param msgbuf_size number of bytes in 'msgbuf' + * @param priority how important is the message (most plugins will + * ignore message priority and just FIFO) + * @param timeout how long to wait at most for the transmission (does not + * require plugins to discard the message after the timeout, + * just advisory for the desired delay; most plugins will ignore + * this as well) + * @param session which session must be used (or NULL for "any") + * @param addr the address to use (can be NULL if the plugin + * is "on its own" (i.e. re-use existing TCP connection)) + * @param addrlen length of the address in bytes + * @param force_address GNUNET_YES if the plugin MUST use the given address, + * GNUNET_NO means the plugin may use any other address and + * GNUNET_SYSERR means that only reliable existing + * bi-directional connections should be used (regardless + * of address) + * @param cont continuation to call once the message has + * been transmitted (or if the transport is ready + * for the next transmission call; or if the + * peer disconnected...); can be NULL + * @param cont_cls closure for cont + * @return number of bytes used (on the physical network, with overheads); + * -1 on hard errors (i.e. address invalid); 0 is a legal value + * and does NOT mean that the message was not transmitted (DV) + */ +typedef ssize_t (*GNUNET_TRANSPORT_TransmitFunction) (void *cls, + const struct + GNUNET_PeerIdentity * + target, + const char *msgbuf, + size_t msgbuf_size, + uint32_t priority, + struct + GNUNET_TIME_Relative + timeout, + struct Session * session, + const void *addr, + size_t addrlen, + int force_address, + GNUNET_TRANSPORT_TransmitContinuation + cont, void *cont_cls); /** + * The new send function with just the session and no address + * * Function that can be used by the transport service to transmit * a message using the plugin. Note that in the case of a * peer disconnecting, the continuation MUST be called @@ -305,20 +372,17 @@ typedef void * -1 on hard errors (i.e. address invalid); 0 is a legal value * and does NOT mean that the message was not transmitted (DV) */ -typedef ssize_t - (*GNUNET_TRANSPORT_TransmitFunction) (void *cls, - const struct GNUNET_PeerIdentity * - target, - const char *msgbuf, - size_t msgbuf_size, - uint32_t priority, - struct GNUNET_TIME_Relative timeout, - struct Session *session, - const void *addr, - size_t addrlen, - int force_address, - GNUNET_TRANSPORT_TransmitContinuation - cont, void *cont_cls); +typedef ssize_t (*GNUNET_TRANSPORT_TransmitFunctionWithSession) (void *cls, + const struct + GNUNET_PeerIdentity * + target, + const char *msgbuf, + size_t msgbuf_size, + uint32_t priority, + struct GNUNET_TIME_Relative timeout, + struct Session * session, + GNUNET_TRANSPORT_TransmitContinuation + cont, void *cont_cls); /** @@ -337,10 +401,10 @@ typedef ssize_t * @param target peer for which the last transmission is * to be cancelled */ -typedef void - (*GNUNET_TRANSPORT_DisconnectFunction) (void *cls, - const struct GNUNET_PeerIdentity * - target); +typedef void (*GNUNET_TRANSPORT_DisconnectFunction) (void *cls, + const struct + GNUNET_PeerIdentity * + target); /** @@ -369,16 +433,16 @@ typedef void (*GNUNET_TRANSPORT_AddressStringCallback) (void *cls, * @param asc function to call on each string * @param asc_cls closure for asc */ -typedef void - (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls, - const char *type, - const void *addr, - size_t addrlen, - int numeric, - struct GNUNET_TIME_Relative - timeout, - GNUNET_TRANSPORT_AddressStringCallback - asc, void *asc_cls); +typedef void (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls, + const char *type, + const void *addr, + size_t addrlen, + int numeric, + struct + GNUNET_TIME_Relative + timeout, + GNUNET_TRANSPORT_AddressStringCallback + asc, void *asc_cls); /** @@ -395,25 +459,40 @@ typedef void * @return GNUNET_OK if this is a plausible address for this peer * and transport, GNUNET_SYSERR if not */ -typedef int -(*GNUNET_TRANSPORT_CheckAddress) (void *cls, - const void *addr, size_t addrlen); +typedef int (*GNUNET_TRANSPORT_CheckAddress) (void *cls, const void *addr, + size_t addrlen); + +/** + * Create a new session to transmit data to the target + * This session will used to send data to this peer and the plugin will + * notify us by calling the env->session_end function + * + * @param cls closure + * @param target the neighbour id + * @param addr pointer to the address + * @param addrlen length of addr + * @return the session if the address is valid, NULL otherwise + */ +typedef const void * (*GNUNET_TRANSPORT_CreateSession) (void *cls, + const struct GNUNET_PeerIdentity *target, + const void *addr, + size_t addrlen); /** * Function called for a quick conversion of the binary address to - * a numeric address. Note that the caller must not free the + * a numeric address. Note that the caller must not free the * address and that the next call to this function is allowed * to override the address again. * * @param cls closure * @param addr binary address * @param addr_len length of the address - * @return string representing the same address + * @return string representing the same address */ -typedef const char* (*GNUNET_TRANSPORT_AddressToString) (void *cls, - const void *addr, - size_t addrlen); +typedef const char *(*GNUNET_TRANSPORT_AddressToString) (void *cls, + const void *addr, + size_t addrlen); /** @@ -437,12 +516,17 @@ struct GNUNET_TRANSPORT_PluginFunctions */ GNUNET_TRANSPORT_TransmitFunction send; + /** + * New send function + * Will be renamed to "send" when implementation is done + */ + + GNUNET_TRANSPORT_TransmitFunctionWithSession send_with_session; + /** * Function that can be used to force the plugin to disconnect from * the given peer and cancel all previous transmissions (and their - * continuations). Note that if the transport does not have - * sessions / persistent connections (for example, UDP), this - * function may very well do nothing. + * continuations). */ GNUNET_TRANSPORT_DisconnectFunction disconnect; @@ -470,6 +554,11 @@ struct GNUNET_TRANSPORT_PluginFunctions */ GNUNET_TRANSPORT_AddressToString address_to_string; + /** + * Function that will be called tell the plugin to create a session + * object + */ + GNUNET_TRANSPORT_CreateSession create_session; };