GNUnet  0.11.x
Data Structures | Macros | Typedefs
Transport Service plugin API

Specifies the struct that is given to the plugin's entry method and the other struct that must be returned. More...

Data Structures

struct  GNUNET_TRANSPORT_PluginEnvironment
 The transport service will pass a pointer to a struct of this type as the first and only argument to the entry point of each transport plugin. More...
 
struct  GNUNET_TRANSPORT_PluginFunctions
 Each plugin is required to return a pointer to a struct of this type as the return value from its entry point. More...
 

Macros

#define TRANSPORT_SESSION_INBOUND_STRING   "<inbound>"
 

Typedefs

typedef void(* GNUNET_TRANSPORT_SessionEnd) (void *cls, const struct GNUNET_HELLO_Address *address, struct GNUNET_ATS_Session *session)
 Function that will be called whenever the plugin internally cleans up a session pointer and hence the service needs to discard all of those sessions as well. More...
 
typedef void(* GNUNET_TRANSPORT_SessionStart) (void *cls, const struct GNUNET_HELLO_Address *address, struct GNUNET_ATS_Session *session, enum GNUNET_NetworkType net)
 Plugin tells transport service about a new inbound session. More...
 
typedef struct GNUNET_TIME_Relative(* GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, const struct GNUNET_HELLO_Address *address, struct GNUNET_ATS_Session *session, const struct GNUNET_MessageHeader *message)
 Function called by the transport for each received message. More...
 
typedef enum GNUNET_NetworkType(* GNUNET_TRANSPORT_AddressToType) (void *cls, const struct sockaddr *addr, size_t addrlen)
 Function that can be called by plugins to figure if an address is an loopback, LAN or WAN address. More...
 
typedef void(* GNUNET_TRANSPORT_UpdateAddressDistance) (void *cls, const struct GNUNET_HELLO_Address *address, uint32_t distance)
 Function called when distance of an address changes. More...
 
typedef void(* GNUNET_TRANSPORT_AddressNotification) (void *cls, int add_remove, const struct GNUNET_HELLO_Address *address)
 Function that will be called for each address the transport is aware that it might be reachable under. More...
 
typedef struct GNUNET_TIME_Relative(* GNUNET_TRANSPORT_TrafficReport) (void *cls, const struct GNUNET_PeerIdentity *peer, size_t amount_recved)
 Function that will be called whenever the plugin receives data over the network and wants to determine how long it should wait until the next time it reads from the given peer. More...
 
typedef const struct GNUNET_MessageHeader *(* GNUNET_TRANSPORT_GetHelloCallback) (void)
 Function that returns a HELLO message. More...
 
typedef void(* GNUNET_TRANSPORT_TransmitContinuation) (void *cls, const struct GNUNET_PeerIdentity *target, int result, size_t size_payload, size_t size_on_wire)
 Function called by the GNUNET_TRANSPORT_TransmitFunction upon "completion". More...
 
typedef ssize_t(* GNUNET_TRANSPORT_TransmitFunction) (void *cls, struct GNUNET_ATS_Session *session, const char *msgbuf, size_t msgbuf_size, unsigned int priority, struct GNUNET_TIME_Relative to, GNUNET_TRANSPORT_TransmitContinuation cont, void *cont_cls)
 The new send function with just the session and no address. More...
 
typedef int(* GNUNET_TRANSPORT_DisconnectSessionFunction) (void *cls, struct GNUNET_ATS_Session *session)
 Function that can be called to force a disconnect from the specified neighbour for the given session only. More...
 
typedef unsigned int(* GNUNET_TRANSPORT_QueryKeepaliveFactorFunction) (void *cls)
 Function that is called to get the keepalive factor. More...
 
typedef void(* GNUNET_TRANSPORT_DisconnectPeerFunction) (void *cls, const struct GNUNET_PeerIdentity *target)
 Function that can be called to force a disconnect from the specified neighbour. More...
 
typedef void(* GNUNET_TRANSPORT_AddressStringCallback) (void *cls, const char *address, int res)
 Function called by the pretty printer for the resolved address for each human-readable address obtained. More...
 
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)
 Convert the transports address to a nice, human-readable format. More...
 
typedef int(* GNUNET_TRANSPORT_CheckAddress) (void *cls, const void *addr, size_t addrlen)
 Another peer has suggested an address for this peer and transport plugin. More...
 
typedef struct GNUNET_ATS_Session *(* GNUNET_TRANSPORT_CreateSession) (void *cls, const struct GNUNET_HELLO_Address *address)
 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. More...
 
typedef void(* GNUNET_TRANSPORT_UpdateSessionTimeout) (void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_ATS_Session *session)
 Function that will be called whenever the transport service wants to notify the plugin that a session is still active and in use and therefore the session timeout for this session has to be updated. More...
 
typedef void(* GNUNET_TRANSPORT_UpdateInboundDelay) (void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_ATS_Session *session, struct GNUNET_TIME_Relative delay)
 Function that will be called whenever the transport service wants to notify the plugin that the inbound quota changed and that the plugin should update it's delay for the next receive value. More...
 
typedef const char *(* GNUNET_TRANSPORT_AddressToString) (void *cls, const void *addr, size_t addrlen)
 Function called for a quick conversion of the binary address to a numeric address. More...
 
typedef int(* GNUNET_TRANSPORT_StringToAddress) (void *cls, const char *addr, uint16_t addrlen, void **buf, size_t *added)
 Function called to convert a string address to a binary address. More...
 
typedef enum GNUNET_NetworkType(* GNUNET_TRANSPORT_GetNetworkType) (void *cls, struct GNUNET_ATS_Session *session)
 Function to obtain the network type for a session. More...
 
typedef enum GNUNET_NetworkType(* GNUNET_TRANSPORT_GetNetworkTypeForAddress) (void *cls, const struct GNUNET_HELLO_Address *address)
 Function to obtain the network type for an address. More...
 
typedef void(* GNUNET_TRANSPORT_SessionInfoCallback) (void *cls, struct GNUNET_ATS_Session *session, const struct GNUNET_TRANSPORT_SessionInfo *info)
 Function called by the plugin with information about the current sessions managed by the plugin (for monitoring). More...
 
typedef void(* GNUNET_TRANSPORT_SessionMonitorSetup) (void *cls, GNUNET_TRANSPORT_SessionInfoCallback sic, void *sic_cls)
 Begin monitoring sessions of a plugin. More...
 

Detailed Description

Specifies the struct that is given to the plugin's entry method and the other struct that must be returned.

Note that the destructors of transport plugins will be given the value returned by the constructor and is expected to return a NULL pointer.

Macro Definition Documentation

◆ TRANSPORT_SESSION_INBOUND_STRING

#define TRANSPORT_SESSION_INBOUND_STRING   "<inbound>"

Definition at line 45 of file gnunet_transport_plugin.h.

Referenced by GST_plugins_a2s(), and template_plugin_address_to_string().

Typedef Documentation

◆ GNUNET_TRANSPORT_SessionEnd

typedef void(* GNUNET_TRANSPORT_SessionEnd) (void *cls, const struct GNUNET_HELLO_Address *address, struct GNUNET_ATS_Session *session)

Function that will be called whenever the plugin internally 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. This function should be called BEFORE a potential "TransmitContinuation" from the "TransmitFunction".

Parameters
clsclosure
peerwhich peer was the session for
sessionwhich session is being destroyed

Definition at line 77 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_SessionStart

typedef void(* GNUNET_TRANSPORT_SessionStart) (void *cls, const struct GNUNET_HELLO_Address *address, struct GNUNET_ATS_Session *session, enum GNUNET_NetworkType net)

Plugin tells transport service about a new inbound session.

Parameters
clsunused
addressthe address
sessionthe new session
netnetwork information

Definition at line 91 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_PluginReceiveCallback

typedef struct GNUNET_TIME_Relative(* GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, const struct GNUNET_HELLO_Address *address, struct GNUNET_ATS_Session *session, const struct GNUNET_MessageHeader *message)

Function called by the transport for each received message.

This function should also be called with "NULL" for the message to signal that the other peer disconnected.

Parameters
clsclosure
peer(claimed) identity of the other peer
messagethe message, NULL if we only care about learning about the delay until we should receive again
sessionidentifier used for this session (NULL for plugins that do not offer bi-directional communication to the sender using the same "connection")
sender_addressbinary address of the sender (if we established the connection or are otherwise sure of it; should be NULL for inbound TCP/UDP connections since it it not clear that we could establish ourselves a connection to that IP address and get the same system)
sender_address_lennumber of bytes in sender_address
Returns
how long the plugin should wait until receiving more data; returning GNUNET_TIME_UNIT_FOREVER_REL means that the connection should be closed

Definition at line 120 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_AddressToType

typedef enum GNUNET_NetworkType(* GNUNET_TRANSPORT_AddressToType) (void *cls, const struct sockaddr *addr, size_t addrlen)

Function that can be called by plugins to figure if an address is an loopback, LAN or WAN address.

Ultimately invokes #GNUNET_ATS_address_get_type().

Parameters
clsclosure
addrbinary address
addrlenlength of the addr
Returns
type of the network the address belongs to

Definition at line 139 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_UpdateAddressDistance

typedef void(* GNUNET_TRANSPORT_UpdateAddressDistance) (void *cls, const struct GNUNET_HELLO_Address *address, uint32_t distance)

Function called when distance of an address changes.

Parameters
clsclosure
peerpeer
distancenew distance

Definition at line 152 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_AddressNotification

typedef void(* GNUNET_TRANSPORT_AddressNotification) (void *cls, int add_remove, const struct GNUNET_HELLO_Address *address)

Function that will be called for each address the transport is aware that it might be reachable under.

Parameters
clsclosure
add_removeshould the address added (GNUNET_YES) or removed (GNUNET_NO) from the set of valid addresses?
addressthe address to add or remove

Definition at line 168 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_TrafficReport

typedef struct GNUNET_TIME_Relative(* GNUNET_TRANSPORT_TrafficReport) (void *cls, const struct GNUNET_PeerIdentity *peer, size_t amount_recved)

Function that will be called whenever the plugin receives data over the network and wants to determine how long it should wait until the next time it reads from the given peer.

Note that some plugins (such as UDP) may not be able to wait (for a particular peer), so the waiting part is optional. Plugins that can wait should call this function, sleep the given amount of time, and call it again (with zero bytes read) UNTIL it returns zero and only then read.

Parameters
clsclosure
peerwhich peer did we read data from
amount_recvednumber of bytes read (can be zero)
Returns
how long to wait until reading more from this peer (to enforce inbound quotas); returning GNUNET_TIME_UNIT_FOREVER_REL means that the connection should be closed

Definition at line 191 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_GetHelloCallback

typedef const struct GNUNET_MessageHeader*(* GNUNET_TRANSPORT_GetHelloCallback) (void)

Function that returns a HELLO message.

Returns
HELLO message (FIXME with what?)

Definition at line 202 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_TransmitContinuation

typedef void(* GNUNET_TRANSPORT_TransmitContinuation) (void *cls, const struct GNUNET_PeerIdentity *target, int result, size_t size_payload, size_t size_on_wire)

Function called by the GNUNET_TRANSPORT_TransmitFunction 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...).

Parameters
clsclosure
targetwho was the recipient of the message?
resultGNUNET_OK on success GNUNET_SYSERR if the target disconnected; disconnect will ALSO be signalled using the ReceiveCallback.
size_payloadbytes of payload from transport service in message
size_on_wirebytes required on wire for transmission, 0 if result == GNUNET_SYSERR

Definition at line 307 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_TransmitFunction

typedef ssize_t(* GNUNET_TRANSPORT_TransmitFunction) (void *cls, struct GNUNET_ATS_Session *session, const char *msgbuf, size_t msgbuf_size, unsigned int priority, struct GNUNET_TIME_Relative to, 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 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.

Parameters
clsclosure
sessionwhich session must be used
msgbufthe message to transmit
msgbuf_sizenumber of bytes in msgbuf
priorityhow important is the message (most plugins will ignore message priority and just FIFO)
tohow 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)
contcontinuation 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
cont_clsclosure for cont
Returns
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)

Definition at line 345 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_DisconnectSessionFunction

typedef int(* GNUNET_TRANSPORT_DisconnectSessionFunction) (void *cls, struct GNUNET_ATS_Session *session)

Function that can be called to force a disconnect from the specified neighbour for the given session only.

. This should also cancel all previously scheduled transmissions for this session. Obviously the transmission may have been partially completed already, which is OK. The plugin is supposed to close the connection (if applicable).

Parameters
clsclosure with the struct Plugin
sessionsession to destroy
Returns
GNUNET_OK on success

Definition at line 368 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_QueryKeepaliveFactorFunction

typedef unsigned int(* GNUNET_TRANSPORT_QueryKeepaliveFactorFunction) (void *cls)

Function that is called to get the keepalive factor.

GNUNET_CONSTANTS_IDLE_CONNECTION_TIMEOUT is divided by this number to calculate the interval between keepalive packets.

Parameters
clsclosure with the struct Plugin
Returns
keepalive factor

Definition at line 382 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_DisconnectPeerFunction

typedef void(* GNUNET_TRANSPORT_DisconnectPeerFunction) (void *cls, const struct GNUNET_PeerIdentity *target)

Function that can be called to force a disconnect from the specified neighbour.

This should also cancel all previously scheduled transmissions. Obviously the transmission may have been partially completed already, which is OK. The plugin is supposed to close the connection (if applicable) and no longer call the transmit continuation(s).

Parameters
clsclosure
targetpeer for which the last transmission is to be cancelled

Definition at line 398 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_AddressStringCallback

typedef void(* GNUNET_TRANSPORT_AddressStringCallback) (void *cls, const char *address, int res)

Function called by the pretty printer for the resolved address for each human-readable address obtained.

The callback can be called several times. The last invocation must be with a address of NULL and a res of GNUNET_OK. Thus, to indicate conversion errors, the callback might be called first with address NULL and res being GNUNET_SYSERR. In that case, there must still be a subsequent call later with address NULL and res GNUNET_OK.

Parameters
clsclosure
addressone of the names for the host, NULL on last callback
resGNUNET_OK if conversion was successful, GNUNET_SYSERR on failure, GNUNET_OK on last callback

Definition at line 418 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_AddressPrettyPrinter

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)

Convert the transports address to a nice, human-readable format.

Parameters
clsclosure
typename of the transport that generated the address
addrone of the addresses of the host, NULL for the last address the specific address format depends on the transport
addrlenlength of the addr
numericshould (IP) addresses be displayed in numeric form?
timeoutafter how long should we give up?
ascfunction to call on each string
asc_clsclosure for asc

Definition at line 438 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_CheckAddress

typedef int(* GNUNET_TRANSPORT_CheckAddress) (void *cls, const void *addr, size_t addrlen)

Another peer has suggested an address for this peer and transport plugin.

Check that this could be a valid address. This function is not expected to 'validate' the address in the sense of trying to connect to it but simply to see if the binary format is technically legal for establishing a connection to this peer (and make sure that the address really corresponds to our network connection/settings and not some potential man-in-the-middle).

Parameters
addrpointer to the address
addrlenlength of addr
Returns
GNUNET_OK if this is a plausible address for this peer and transport, GNUNET_SYSERR if not

Definition at line 464 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_CreateSession

typedef struct GNUNET_ATS_Session*(* GNUNET_TRANSPORT_CreateSession) (void *cls, const struct GNUNET_HELLO_Address *address)

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.

Parameters
clsthe plugin
addressthe hello address
Returns
the session if the address is valid, NULL otherwise

Definition at line 479 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_UpdateSessionTimeout

typedef void(* GNUNET_TRANSPORT_UpdateSessionTimeout) (void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_ATS_Session *session)

Function that will be called whenever the transport service wants to notify the plugin that a session is still active and in use and therefore the session timeout for this session has to be updated.

Parameters
clsclosure
peerwhich peer was the session for
sessionwhich session is being updated

Definition at line 493 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_UpdateInboundDelay

typedef void(* GNUNET_TRANSPORT_UpdateInboundDelay) (void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_ATS_Session *session, struct GNUNET_TIME_Relative delay)

Function that will be called whenever the transport service wants to notify the plugin that the inbound quota changed and that the plugin should update it's delay for the next receive value.

Parameters
clsclosure
peerwhich peer was the session for
sessionwhich session is being updated
delaynew delay to use for receiving

Definition at line 510 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_AddressToString

typedef const char*(* GNUNET_TRANSPORT_AddressToString) (void *cls, 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 address and that the next call to this function is allowed to override the address again.

Parameters
clsclosure
addrbinary address
addr_lenlength of the addr
Returns
string representing the same address

Definition at line 528 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_StringToAddress

typedef int(* GNUNET_TRANSPORT_StringToAddress) (void *cls, const char *addr, uint16_t addrlen, void **buf, size_t *added)

Function called to convert a string address to a binary address.

Parameters
clsclosure (struct Plugin*)
addrstring address
addrlenlength of the addr including \0 termination
buflocation to store the buffer If the function returns GNUNET_SYSERR, its contents are undefined.
addedlength of created address
Returns
GNUNET_OK on success, GNUNET_SYSERR on failure

Definition at line 546 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_GetNetworkType

typedef enum GNUNET_NetworkType(* GNUNET_TRANSPORT_GetNetworkType) (void *cls, struct GNUNET_ATS_Session *session)

Function to obtain the network type for a session.

Parameters
clsclosure (struct Plugin *)
sessionthe session
Returns
the network type

Definition at line 561 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_GetNetworkTypeForAddress

typedef enum GNUNET_NetworkType(* GNUNET_TRANSPORT_GetNetworkTypeForAddress) (void *cls, const struct GNUNET_HELLO_Address *address)

Function to obtain the network type for an address.

Parameters
clsclosure (struct Plugin *)
addressthe address
Returns
the network type

Definition at line 573 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_SessionInfoCallback

typedef void(* GNUNET_TRANSPORT_SessionInfoCallback) (void *cls, struct GNUNET_ATS_Session *session, const struct GNUNET_TRANSPORT_SessionInfo *info)

Function called by the plugin with information about the current sessions managed by the plugin (for monitoring).

Parameters
clsclosure
sessionsession handle this information is about, NULL to indicate that we are "in sync" (initial iteration complete)
infoinformation about the state of the session, NULL if session is also NULL and we are merely signalling that the initial iteration is over

Definition at line 591 of file gnunet_transport_plugin.h.

◆ GNUNET_TRANSPORT_SessionMonitorSetup

typedef void(* GNUNET_TRANSPORT_SessionMonitorSetup) (void *cls, GNUNET_TRANSPORT_SessionInfoCallback sic, void *sic_cls)

Begin monitoring sessions of a plugin.

There can only be one active monitor per plugin (i.e. if there are multiple monitors, the transport service needs to multiplex the generated events over all of them).

Parameters
clsclosure of the plugin
siccallback to invoke, NULL to disable monitor; plugin will being by iterating over all active sessions immediately and then enter monitor mode
sic_clsclosure for sic

Definition at line 610 of file gnunet_transport_plugin.h.