X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_transport_plugin.h;h=d95e9f4e9cf411b0d6521bfa9134faf8a7f3be1f;hb=a6fb0db57f2a70a05bdb6ef7ccf69a044268dee6;hp=d367779e1b86b74b152fdca49cf2b56059d37b17;hpb=d4268281ba652162cf234670bc628d7f50681ac4;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_transport_plugin.h b/src/include/gnunet_transport_plugin.h index d367779e1..d95e9f4e9 100644 --- a/src/include/gnunet_transport_plugin.h +++ b/src/include/gnunet_transport_plugin.h @@ -19,7 +19,7 @@ */ /** - * @file transport/gnunet_transport_plugin.h + * @file include/gnunet_transport_plugin.h * @brief API for the transport services. This header * specifies the struct that is given to the plugin's entry * method and the other struct that must be returned. @@ -36,341 +36,6 @@ #include "gnunet_statistics_service.h" #include "gnunet_transport_service.h" - -/** - * The structs defined here are used by the transport plugin to tell ATS about - * the transport's properties like cost and quality and on the other side - * the structs are used by highlevel components to communicate the constraints - * they have for a transport to ATS - * - * +---+ - * +-----------+ Constraints | | Plugin properties +---------+ - * | Highlevel |------------> |ATS| <------------------|Transport| - * | Component | ATS struct | | ATS struct | Plugin | - * +-----------+ | | +---------+ - * +---+ - * - */ - -#define GNUNET_TRANSPORT_ATS_ARRAY_TERMINATOR 0 - -/** - * Enum defining all known property types for ATS - * Enum values are used in the GNUNET_TRANSPORT_ATS_Information struct as (key,value)-pair - * - * Cost are always stored in uint32_t, so all units used to define costs - * have to be normalized to fit in uint32_t [0 .. 4.294.967.295] - * - * To keep the elements ordered - * 1..1024 : Values with a relation to cost - * 1025..2048 : Values with a relation to quality - * 2049..3072 : Values with a relation to availability - * - */ -enum GNUNET_TRANSPORT_ATS_Property -{ - - /* Cost related values */ - /* =================== */ - - /** - * Volume based cost in financial units to transmit data - * - * Note: This value is not bound to a specific currency or unit and only - * used locally. - * "cent" just refers the smallest amount of money in the respective - * currency. - * - * Unit: [cent/MB] - * - * Interpretation: less is better - * - * Examples: - * LAN: 0 [cent/MB] - * 2G : 10 [cent/MB] - */ - GNUNET_TRANSPORT_ATS_COST_FINANCIAL_PER_VOLUME = 1, - - /** - * Time based cost in financial units to transmit data - * - * Note: This value is not bound to a specific currency or unit and only - * used locally. - * "cent" just refers the smallest amount of money in the respective - * currency. - * - * Unit: [cent/h] - * - * Interpretation: less is better - * - * Examples: - * LAN : 0 [cent/h] - * Dialup: 10 [cent/h] - */ - GNUNET_TRANSPORT_ATS_COST_FINANCIAL_PER_TIME = 2, - - /** - * Computational costs - * - * Effort of preparing data to be sent with this transport - * Includes encoding, encryption and conversion of data - * Partial values can be summed up: c_sum = c_enc + c_enc + c_conv - * Resulting values depend on local system properties, e.g. CPU - * - * Unit: [ms/GB] - * - * Interpretation: less is better - * - * Examples: - * - * HTTPS with AES CBC-256: 7,382 - * HTTPS with AES CBC-128: 5,279 - * HTTPS with RC4-1024: 2,652 - */ - GNUNET_TRANSPORT_ATS_COST_COMPUTATIONAL = 3, - - /** - * Energy consumption - * - * Energy consumption using this transport when sending with a certain - * power at a certain bitrate. This is only an approximation based on: - * Energy consumption E = P / D - * - * with: - * Power P in Watt (J/s) - * Datarate D in MBit/s - * - * Conversion between power P and dBm used by WLAN in radiotap's dBm TX power: - * - * Lp(dbm) = 10 log10 (P/ 1mW) - * - * => P = 1 mW * 10^(Lp(dbm)/10) - * - * Unit: [mJ/MB] - * - * Interpretation: less is better - * - * Examples: - * - * LAN: 0 - * WLAN: 89 (600 mW @ 802.11g /w 54 MBit/s) - * Bluetooth: 267 (100 mW @ BT2.0 EDR /w 3 MBit/s) - */ - GNUNET_TRANSPORT_ATS_COST_ENERGY_CONSUMPTION = 4, - - /** - * Connect cost - * How many bytes are transmitted to initiate a new connection using - * this transport? - * - * Unit: [bytes] - * - * Interpretation: less is better - * - * Examples: - * - * UDP (No connection) : - * 0 bytes - * TCP (TCP 3-Way handshake): - * 220 bytes Ethernet, 172 bytes TCP/IP, 122 bytes TCP - * HTTP (TCP + Header) : - * 477 bytes Ethernet, 429 bytes TCP/IP, 374 bytes TCP, 278 bytes HTTP - * HTTPS HTTP+TLS Handshake: - * 2129 bytes Ethernet, 1975 bytes TCP/IP, 1755 bytes TCP, 1403 bytes HTTPS - * - * */ - GNUNET_TRANSPORT_ATS_COST_CONNECT = 5, - - /** - * Bandwidth cost - * - * How many bandwidth is available to consume? - * Used to calculate which impact sending data with this transport has - * - * Unit: [kB/s] - * - * Interpretation: more is better - * - * Examples: - * LAN: 12,800 (100 MBit/s) - * WLAN: 6,912 (54 MBit/s) - * Dial-up: 8 (64 Kbit/s) - * - */ - GNUNET_TRANSPORT_ATS_COST_BANDWITH_AVAILABLE = 6, - - /** - * Network overhead - * - * How many bytes are sent over the wire when 1 kilobyte (1024 bytes) - * of application data is transmitted? - * A factor used with connect cost, bandwidth cost and energy cost - * to describe the overhead produced by the transport protocol - * - * Unit: [bytes/kb] - * - * Interpretation: less is better - * - * Examples: - * - * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb] - * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb] - * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb] - * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb] - */ - GNUNET_TRANSPORT_ATS_COST_NETWORK_OVERHEAD = 7, - - - /* Quality related values */ - /* ====================== */ - - /* Physical layer quality properties */ - - /** - * Signal strength on physical layer - * - * Unit: [dBm] - */ - GNUNET_TRANSPORT_ATS_QUALITY_PHY_SIGNAL_STRENGTH = 1025, - - /** - * Collision rate on physical layer - * - * Unit: [B/s] - */ - GNUNET_TRANSPORT_ATS_QUALITY_PHY_COLLISION_RATE = 1026, - - /** - * Error rate on physical layer - * - * Unit: [B/s] - */ - GNUNET_TRANSPORT_ATS_QUALITY_PHY_ERROR_RATE = 1027, - - /* Network layer quality properties */ - - /** - * Delay - * Time between when the time packet is sent and the packet arrives - * - * Unit: [μs] - * - * Examples: - * - * LAN : 180 - * Dialup: 4000 - * WLAN : 7000 - */ - GNUNET_TRANSPORT_ATS_QUALITY_NET_DELAY = 1028, - - /** - * Jitter - * Time variations of the delay - * 1st derivative of a delay function - * - * Unit: [μs] - */ - GNUNET_TRANSPORT_ATS_QUALITY_NET_JITTER = 1029, - - /** - * Error rate on network layer - * - * Unit: [B/s] - * - * Examples: - * - * LAN : 0 - * WLAN : 400 - * Bluetooth : 100 - * Note: This numbers are just assumptions as an example, not - * measured or somehow determined - */ - GNUNET_TRANSPORT_ATS_QUALITY_NET_ERRORRATE = 1030, - - /** - * Drop rate on network layer - * Bytes actively dismissed by a network component during transmission - * Reasons for dropped data can be full queues, congestion, quota violations... - * - * Unit: [B/s] - * - * Examples: - * - * LAN : 0 - * WLAN : 400 - * Bluetooth : 100 - * Note: This numbers are just assumptions as an example, not - * measured or somehow determined - */ - GNUNET_TRANSPORT_ATS_QUALITY_NET_DROPRATE = 1031, - - /** - * Loss rate on network layer - * Bytes lost during transmission - * Reasons can be collisions, ... - * - * Unit: [B/s] - * - * Examples: - * - * LAN : 0 - * WLAN : 40 - * Bluetooth : 10 - * Note: This numbers are just assumptions as an example, not measured - * or somehow determined - */ - GNUNET_TRANSPORT_ATS_QUALITY_NET_LOSSRATE = 1032, - - /** - * Throughput on network layer - * - * Unit: [kB/s] - * - * Examples: - * - * LAN : 3400 - * WLAN : 1200 - * Dialup: 4 - * - */ - GNUNET_TRANSPORT_ATS_QUALITY_NET_THROUGHPUT = 1033, - - /* Availability related values */ - /* =========================== */ - - /** - * Is a peer reachable? - */ - GNUNET_TRANSPORT_ATS_AVAILABILITY_REACHABLE = 2048, - - /** - * Is there a connection established to a peer using this transport - */ - GNUNET_TRANSPORT_ATS_AVAILABILITY_CONNECTED = 2049 -}; - -/** - * This structure will be used by plugins to communicate costs to ATS or by - * higher level components to tell ATS their constraints. - * Always a pair of (GNUNET_TRANSPORT_ATS_Property, uint32_t value). - * Value is always uint32_t, so all units used to define costs have to - * be normalized to fit uint32_t. - */ -struct GNUNET_TRANSPORT_ATS_Information -{ - /** - * ATS property type - */ - uint32_t type; - - /** - * ATS property value - */ - uint32_t value; -}; - - - /** * Opaque pointer that plugins can use to distinguish specific * connections to a given peer. Typically used by stateful plugins to @@ -398,7 +63,7 @@ struct SessionHeader * Expiration time for signature. Do not use in the plugin! */ struct GNUNET_TIME_Absolute pong_sig_expires; - + }; /** @@ -406,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); /** @@ -425,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") @@ -439,37 +105,57 @@ 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, - uint32_t distance, - 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 * is aware that it might be reachable under. * * @param cls closure - * @param name name of the transport that generated the address - * @param addr one of the addresses of the host, NULL for the last address + * @param add_remove should the address added (YES) or removed (NO) from the + * set of valid addresses? + * @param addr one of the addresses of the host * the specific address format depends on the transport * @param addrlen length of the address - * @param expires when should this address automatically expire? */ -typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls, - const char *name, +typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls, int add_remove, const void *addr, - uint16_t addrlen, - struct - GNUNET_TIME_Relative - expires); + size_t addrlen); + /** * Function that will be called whenever the plugin receives data over @@ -486,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 @@ -527,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. */ @@ -549,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 @@ -556,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). @@ -569,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 @@ -585,7 +260,12 @@ struct GNUNET_TRANSPORT_PluginEnvironment /** * Function called by the GNUNET_TRANSPORT_TransmitFunction - * upon "completion". + * upon "completion". In the case that a peer disconnects, + * this function must be called for each pending request + * (with a 'failure' indication) AFTER notifying the service + * about the disconnect event (so that the service won't try + * to transmit more messages, believing the connection still + * exists...). * * @param cls closure * @param target who was the recipient of the message? @@ -594,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 @@ -636,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); /** @@ -668,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); /** @@ -700,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); /** @@ -726,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); /** @@ -768,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; @@ -801,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; };