GNUnet  0.10.x
Data Structures | Macros | Functions
plugin_transport_template.c File Reference

template for a new transport service More...

#include "platform.h"
#include "gnunet_util_lib.h"
#include "gnunet_protocols.h"
#include "gnunet_statistics_service.h"
#include "gnunet_transport_service.h"
#include "gnunet_transport_plugin.h"
Include dependency graph for plugin_transport_template.c:

Go to the source code of this file.

Data Structures

struct  GNUNET_ATS_Session
 Information about ongoing sessions of the transport client. More...
 
struct  TemplateAddress
 
struct  Plugin
 Handle for a plugin. More...
 

Macros

#define LOG(kind, ...)   GNUNET_log_from(kind, "transport-template", __VA_ARGS__)
 
#define LEARNED_ADDRESS_EXPIRATION   GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_HOURS, 6)
 After how long do we expire an address that we learned from another peer if it is not reconfirmed by anyone? More...
 
#define PLUGIN_NAME   "template"
 

Functions

static ssize_t template_plugin_send (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)
 Function that can be used by the transport service to transmit a message using the plugin. More...
 
static void template_plugin_disconnect_peer (void *cls, const struct GNUNET_PeerIdentity *target)
 Function that can be used to force the plugin to disconnect from the given peer and cancel all previous transmissions (and their continuationc). More...
 
static int template_plugin_disconnect_session (void *cls, struct GNUNET_ATS_Session *session)
 Function that can be used to force the plugin to disconnect from the given peer and cancel all previous transmissions (and their continuationc). More...
 
static unsigned int template_plugin_query_keepalive_factor (void *cls)
 Function that is called to get the keepalive factor. More...
 
static enum GNUNET_NetworkType template_plugin_get_network (void *cls, struct GNUNET_ATS_Session *session)
 Function obtain the network type for a session. More...
 
static enum GNUNET_NetworkType template_plugin_get_network_for_address (void *cls, const struct GNUNET_HELLO_Address *address)
 Function obtain the network type for an address. More...
 
static void template_plugin_address_pretty_printer (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...
 
static int template_plugin_address_suggested (void *cls, const void *addr, size_t addrlen)
 Another peer has suggested an address for this peer and transport plugin. More...
 
static const char * template_plugin_address_to_string (void *cls, const void *addr, size_t addrlen)
 Function called for a quick conversion of the binary address to a numeric address. More...
 
static int template_plugin_string_to_address (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...
 
static struct GNUNET_ATS_Sessiontemplate_plugin_get_session (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...
 
static void template_plugin_update_session_timeout (void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_ATS_Session *session)
 
static void template_plugin_setup_monitor (void *cls, GNUNET_TRANSPORT_SessionInfoCallback sic, void *sic_cls)
 Begin monitoring sessions of a plugin. More...
 
void * libgnunet_plugin_transport_template_init (void *cls)
 Entry point for the plugin. More...
 
void * libgnunet_plugin_transport_template_done (void *cls)
 Exit point from the plugin. More...
 

Detailed Description

template for a new transport service

Author
Christian Grothoff

Definition in file plugin_transport_template.c.

Macro Definition Documentation

◆ LOG

#define LOG (   kind,
  ... 
)    GNUNET_log_from(kind, "transport-template", __VA_ARGS__)

◆ LEARNED_ADDRESS_EXPIRATION

#define LEARNED_ADDRESS_EXPIRATION   GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_HOURS, 6)

After how long do we expire an address that we learned from another peer if it is not reconfirmed by anyone?

Definition at line 41 of file plugin_transport_template.c.

◆ PLUGIN_NAME

#define PLUGIN_NAME   "template"

Definition at line 43 of file plugin_transport_template.c.

Function Documentation

◆ template_plugin_send()

static ssize_t template_plugin_send ( 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 
)
static

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 210 of file plugin_transport_template.c.

Referenced by libgnunet_plugin_transport_template_init().

218 {
219  /* struct Plugin *plugin = cls; */
220  ssize_t bytes_sent = 0;
221 
222  return bytes_sent;
223 }
Here is the caller graph for this function:

◆ template_plugin_disconnect_peer()

static void template_plugin_disconnect_peer ( void *  cls,
const struct GNUNET_PeerIdentity target 
)
static

Function that can be used to force the plugin to disconnect from the given peer and cancel all previous transmissions (and their continuationc).

Parameters
clsclosure
targetpeer from which to disconnect

Definition at line 235 of file plugin_transport_template.c.

Referenced by libgnunet_plugin_transport_template_init().

237 {
238  // struct Plugin *plugin = cls;
239  // FIXME
240 }
Here is the caller graph for this function:

◆ template_plugin_disconnect_session()

static int template_plugin_disconnect_session ( void *  cls,
struct GNUNET_ATS_Session session 
)
static

Function that can be used to force the plugin to disconnect from the given peer and cancel all previous transmissions (and their continuationc).

Parameters
clsclosure
sessionsession from which to disconnect
Returns
GNUNET_OK on success

Definition at line 253 of file plugin_transport_template.c.

References GNUNET_SYSERR.

Referenced by libgnunet_plugin_transport_template_init().

255 {
256  // struct Plugin *plugin = cls;
257  // FIXME
258  return GNUNET_SYSERR;
259 }
#define GNUNET_SYSERR
Definition: gnunet_common.h:76
Here is the caller graph for this function:

◆ template_plugin_query_keepalive_factor()

static unsigned int template_plugin_query_keepalive_factor ( void *  cls)
static

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 271 of file plugin_transport_template.c.

Referenced by libgnunet_plugin_transport_template_init().

272 {
273  return 3;
274 }
Here is the caller graph for this function:

◆ template_plugin_get_network()

static enum GNUNET_NetworkType template_plugin_get_network ( void *  cls,
struct GNUNET_ATS_Session session 
)
static

Function obtain the network type for a session.

Parameters
clsclosure ('struct Plugin*')
sessionthe session
Returns
the network type in HBO or GNUNET_SYSERR

Definition at line 285 of file plugin_transport_template.c.

References GNUNET_assert, and GNUNET_NT_UNSPECIFIED.

Referenced by libgnunet_plugin_transport_template_init().

287 {
288  GNUNET_assert(NULL != session);
289  return GNUNET_NT_UNSPECIFIED; /* Change to correct network type */
290 }
#define GNUNET_assert(cond)
Use this for fatal errors that cannot be handled.
Category of last resort.
Definition: gnunet_nt_lib.h:39
Here is the caller graph for this function:

◆ template_plugin_get_network_for_address()

static enum GNUNET_NetworkType template_plugin_get_network_for_address ( void *  cls,
const struct GNUNET_HELLO_Address address 
)
static

Function obtain the network type for an address.

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

Definition at line 301 of file plugin_transport_template.c.

References GNUNET_NT_WAN.

Referenced by libgnunet_plugin_transport_template_init().

303 {
304  return GNUNET_NT_WAN; /* FOR NOW */
305 }
Wide area network (i.e.
Definition: gnunet_nt_lib.h:54
Here is the caller graph for this function:

◆ template_plugin_address_pretty_printer()

static void template_plugin_address_pretty_printer ( 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 
)
static

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 address
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 323 of file plugin_transport_template.c.

References GNUNET_OK.

Referenced by libgnunet_plugin_transport_template_init().

329 {
330  asc(asc_cls, "converted address", GNUNET_OK); /* return address */
331  asc(asc_cls, NULL, GNUNET_OK); /* done */
332 }
GNUNET_TRANSPORT_AddressStringCallback asc
Function to call with the result.
#define GNUNET_OK
Named constants for return values.
Definition: gnunet_common.h:75
void * asc_cls
Clsoure for asc.
Here is the caller graph for this function:

◆ template_plugin_address_suggested()

static int template_plugin_address_suggested ( void *  cls,
const void *  addr,
size_t  addrlen 
)
static

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

Check that this could be a valid address. If so, consider adding it to the list of addresses.

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

Definition at line 349 of file plugin_transport_template.c.

References GNUNET_OK.

Referenced by libgnunet_plugin_transport_template_init().

350 {
351  /* struct Plugin *plugin = cls; */
352 
353  /* check if the address is belonging to the plugin*/
354  return GNUNET_OK;
355 }
#define GNUNET_OK
Named constants for return values.
Definition: gnunet_common.h:75
Here is the caller graph for this function:

◆ template_plugin_address_to_string()

static const char* template_plugin_address_to_string ( void *  cls,
const void *  addr,
size_t  addrlen 
)
static

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
addrlenlength of the address
Returns
string representing the same address

Definition at line 370 of file plugin_transport_template.c.

References GNUNET_break, and TRANSPORT_SESSION_INBOUND_STRING.

Referenced by libgnunet_plugin_transport_template_init().

371 {
372  /*
373  * Print address in format template.options.address
374  */
375 
376  if (0 == addrlen)
377  {
379  }
380 
381  GNUNET_break(0);
382  return NULL;
383 }
#define TRANSPORT_SESSION_INBOUND_STRING
#define GNUNET_break(cond)
Use this for internal assertion violations that are not fatal (can be handled) but should not occur...
Here is the caller graph for this function:

◆ template_plugin_string_to_address()

static int template_plugin_string_to_address ( void *  cls,
const char *  addr,
uint16_t  addrlen,
void **  buf,
size_t *  added 
)
static

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

Parameters
clsclosure ('struct Plugin*')
addrstring address
addrlenlength of the addr
buflocation to store the buffer
addedlocation to store the number of bytes in the buffer. If the function returns GNUNET_SYSERR, its contents are undefined.
Returns
GNUNET_OK on success, GNUNET_SYSERR on failure

Definition at line 399 of file plugin_transport_template.c.

References GNUNET_break, and GNUNET_SYSERR.

Referenced by libgnunet_plugin_transport_template_init().

403 {
404  /*
405  * Parse string in format template.options.address
406  */
407  GNUNET_break(0);
408  return GNUNET_SYSERR;
409 }
#define GNUNET_break(cond)
Use this for internal assertion violations that are not fatal (can be handled) but should not occur...
#define GNUNET_SYSERR
Definition: gnunet_common.h:76
Here is the caller graph for this function:

◆ template_plugin_get_session()

static struct GNUNET_ATS_Session* template_plugin_get_session ( void *  cls,
const struct GNUNET_HELLO_Address address 
)
static

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
clsclosure
addresspointer to the GNUNET_HELLO_Address
Returns
the session if the address is valid, NULL otherwise

Definition at line 422 of file plugin_transport_template.c.

References GNUNET_break.

Referenced by libgnunet_plugin_transport_template_init().

424 {
425  GNUNET_break(0);
426  return NULL;
427 }
#define GNUNET_break(cond)
Use this for internal assertion violations that are not fatal (can be handled) but should not occur...
Here is the caller graph for this function:

◆ template_plugin_update_session_timeout()

static void template_plugin_update_session_timeout ( void *  cls,
const struct GNUNET_PeerIdentity peer,
struct GNUNET_ATS_Session session 
)
static

Definition at line 431 of file plugin_transport_template.c.

References GNUNET_OK, GNUNET_TRANSPORT_SS_UP, notify_session_monitor(), peer, GNUNET_ATS_Session::plugin, send_session_info_iter(), and value.

Referenced by libgnunet_plugin_transport_template_init().

434 {
435 }
Here is the call graph for this function:
Here is the caller graph for this function:

◆ template_plugin_setup_monitor()

static void template_plugin_setup_monitor ( void *  cls,
GNUNET_TRANSPORT_SessionInfoCallback  sic,
void *  sic_cls 
)
static

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 477 of file plugin_transport_template.c.

References GNUNET_CONTAINER_multipeermap_iterate(), GNUNET_ATS_Session::plugin, send_session_info_iter(), Plugin::sic, and Plugin::sic_cls.

Referenced by libgnunet_plugin_transport_template_init().

480 {
481  struct Plugin *plugin = cls;
482 
483  plugin->sic = sic;
484  plugin->sic_cls = sic_cls;
485  if (NULL != sic)
486  {
487 #if 0
488  GNUNET_CONTAINER_multipeermap_iterate(NULL /* FIXME */,
490  plugin);
491 #endif
492  /* signal end of first iteration */
493  sic(sic_cls, NULL, NULL);
494  }
495 }
GNUNET_TRANSPORT_SessionInfoCallback sic
Function to call about session status changes.
static int send_session_info_iter(void *cls, const struct GNUNET_PeerIdentity *peer, void *value)
Return information about the given session to the monitor callback.
static struct GNUNET_ATS_SolverFunctions * plugin
Our solver.
int GNUNET_CONTAINER_multipeermap_iterate(struct GNUNET_CONTAINER_MultiPeerMap *map, GNUNET_CONTAINER_PeerMapIterator it, void *it_cls)
Iterate over all entries in the map.
Handle for a plugin.
Definition: block.c:37
void * sic_cls
Closure for sic.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ libgnunet_plugin_transport_template_init()

void* libgnunet_plugin_transport_template_init ( void *  cls)

Entry point for the plugin.

Definition at line 502 of file plugin_transport_template.c.

References GNUNET_TRANSPORT_PluginFunctions::address_pretty_printer, GNUNET_TRANSPORT_PluginFunctions::address_to_string, Plugin::api, GNUNET_TRANSPORT_PluginFunctions::check_address, GNUNET_TRANSPORT_PluginEnvironment::cls, GNUNET_TRANSPORT_PluginFunctions::cls, GNUNET_TRANSPORT_PluginFunctions::disconnect_peer, GNUNET_TRANSPORT_PluginFunctions::disconnect_session, env, Plugin::env, GNUNET_TRANSPORT_PluginFunctions::get_network, GNUNET_TRANSPORT_PluginFunctions::get_network_for_address, GNUNET_TRANSPORT_PluginFunctions::get_session, GNUNET_ERROR_TYPE_INFO, GNUNET_new, LOG, GNUNET_ATS_Session::plugin, GNUNET_TRANSPORT_PluginFunctions::query_keepalive_factor, GNUNET_TRANSPORT_PluginEnvironment::receive, GNUNET_TRANSPORT_PluginFunctions::send, GNUNET_TRANSPORT_PluginFunctions::setup_monitor, GNUNET_TRANSPORT_PluginFunctions::string_to_address, template_plugin_address_pretty_printer(), template_plugin_address_suggested(), template_plugin_address_to_string(), template_plugin_disconnect_peer(), template_plugin_disconnect_session(), template_plugin_get_network(), template_plugin_get_network_for_address(), template_plugin_get_session(), template_plugin_query_keepalive_factor(), template_plugin_send(), template_plugin_setup_monitor(), template_plugin_string_to_address(), template_plugin_update_session_timeout(), and GNUNET_TRANSPORT_PluginFunctions::update_session_timeout.

503 {
506  struct Plugin *plugin;
507 
508  if (NULL == env->receive)
509  {
510  /* run in 'stub' mode (i.e. as part of gnunet-peerinfo), don't fully
511  initialze the plugin or the API */
513  api->cls = NULL;
517  return api;
518  }
519 
520  plugin = GNUNET_new(struct Plugin);
521  plugin->env = env;
523  api->cls = plugin;
524  api->send = &template_plugin_send;
537  LOG(GNUNET_ERROR_TYPE_INFO, "Template plugin successfully loaded\n");
538  return api;
539 }
static int template_plugin_address_suggested(void *cls, const void *addr, size_t addrlen)
Another peer has suggested an address for this peer and transport plugin.
static int template_plugin_disconnect_session(void *cls, struct GNUNET_ATS_Session *session)
Function that can be used to force the plugin to disconnect from the given peer and cancel all previo...
GNUNET_TRANSPORT_CreateSession get_session
Function that will be called tell the plugin to create a session object.
GNUNET_TRANSPORT_AddressToString address_to_string
Function that will be called to convert a binary address to a string (numeric conversion only)...
GNUNET_TRANSPORT_TransmitFunction send
Function that the transport service will use to transmit data to another peer.
GNUNET_TRANSPORT_DisconnectPeerFunction disconnect_peer
Function that can be used to force the plugin to disconnect from the given peer and cancel all previo...
static void template_plugin_setup_monitor(void *cls, GNUNET_TRANSPORT_SessionInfoCallback sic, void *sic_cls)
Begin monitoring sessions of a plugin.
GNUNET_TRANSPORT_DisconnectSessionFunction disconnect_session
Function that can be used to force the plugin to disconnect from the given peer and cancel all previo...
Each plugin is required to return a pointer to a struct of this type as the return value from its ent...
GNUNET_TRANSPORT_SessionMonitorSetup setup_monitor
Function to monitor the sessions managed by the plugin.
static void template_plugin_disconnect_peer(void *cls, const struct GNUNET_PeerIdentity *target)
Function that can be used to force the plugin to disconnect from the given peer and cancel all previo...
#define GNUNET_new(type)
Allocate a struct or union of the given type.
static int template_plugin_string_to_address(void *cls, const char *addr, uint16_t addrlen, void **buf, size_t *added)
Function called to convert a string address to a binary address.
struct GNUNET_BLOCK_PluginFunctions * api
Plugin API.
Definition: block.c:46
GNUNET_TRANSPORT_PluginReceiveCallback receive
Function that should be called by the transport plugin whenever a message is received.
GNUNET_TRANSPORT_UpdateSessionTimeout update_session_timeout
Function that will be called whenever the transport service wants to notify the plugin that a session...
static struct GNUNET_ATS_SolverFunctions * plugin
Our solver.
#define LOG(kind,...)
void * cls
Closure for the various callbacks.
void * cls
Closure for all of the callbacks.
GNUNET_TRANSPORT_StringToAddress string_to_address
Function that will be called to convert a string address to binary (numeric conversion only)...
struct GNUNET_DATACACHE_PluginEnvironment * env
Our execution environment.
The transport service will pass a pointer to a struct of this type as the first and only argument to ...
GNUNET_TRANSPORT_GetNetworkType get_network
Function to obtain the network type for a session.
static enum GNUNET_NetworkType template_plugin_get_network_for_address(void *cls, const struct GNUNET_HELLO_Address *address)
Function obtain the network type for an address.
static enum GNUNET_NetworkType template_plugin_get_network(void *cls, struct GNUNET_ATS_Session *session)
Function obtain the network type for a session.
static unsigned int template_plugin_query_keepalive_factor(void *cls)
Function that is called to get the keepalive factor.
struct GNUNET_MQ_Envelope * env
Definition: 005.c:1
static void template_plugin_update_session_timeout(void *cls, const struct GNUNET_PeerIdentity *peer, struct GNUNET_ATS_Session *session)
static struct GNUNET_ATS_Session * template_plugin_get_session(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 ...
static const char * template_plugin_address_to_string(void *cls, const void *addr, size_t addrlen)
Function called for a quick conversion of the binary address to a numeric address.
GNUNET_TRANSPORT_QueryKeepaliveFactorFunction query_keepalive_factor
Function that is used to query keepalive factor.
static void template_plugin_address_pretty_printer(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.
Handle for a plugin.
Definition: block.c:37
static ssize_t template_plugin_send(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)
Function that can be used by the transport service to transmit a message using the plugin...
GNUNET_TRANSPORT_AddressPrettyPrinter address_pretty_printer
Function to pretty-print addresses.
GNUNET_TRANSPORT_CheckAddress check_address
Function that will be called to check if a binary address for this plugin is well-formed and correspo...
GNUNET_TRANSPORT_GetNetworkTypeForAddress get_network_for_address
Function to obtain the network type for an address.
Here is the call graph for this function:

◆ libgnunet_plugin_transport_template_done()

void* libgnunet_plugin_transport_template_done ( void *  cls)

Exit point from the plugin.

Definition at line 546 of file plugin_transport_template.c.

References GNUNET_TRANSPORT_PluginFunctions::cls, GNUNET_free, and GNUNET_ATS_Session::plugin.

547 {
549  struct Plugin *plugin = api->cls;
550 
551  GNUNET_free(plugin);
552  GNUNET_free(api);
553  return NULL;
554 }
Each plugin is required to return a pointer to a struct of this type as the return value from its ent...
static struct GNUNET_ATS_SolverFunctions * plugin
Our solver.
void * cls
Closure for all of the callbacks.
Handle for a plugin.
Definition: block.c:37
#define GNUNET_free(ptr)
Wrapper around free.