GNUnet  0.11.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
 Session handle for connections. 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
 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
Value:
#define GNUNET_TIME_UNIT_HOURS
One hour.
struct GNUNET_TIME_Relative GNUNET_TIME_relative_multiply(struct GNUNET_TIME_Relative rel, unsigned long long factor)
Multiply relative time by a given factor.
Definition: time.c:442

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

Referenced by libgnunet_plugin_transport_template_init().

224 {
225  /* struct Plugin *plugin = cls; */
226  ssize_t bytes_sent = 0;
227 
228  return bytes_sent;
229 }
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 241 of file plugin_transport_template.c.

Referenced by libgnunet_plugin_transport_template_init().

243 {
244  // struct Plugin *plugin = cls;
245  // FIXME
246 }
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 259 of file plugin_transport_template.c.

References GNUNET_SYSERR.

Referenced by libgnunet_plugin_transport_template_init().

261 {
262  // struct Plugin *plugin = cls;
263  // FIXME
264  return GNUNET_SYSERR;
265 }
#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 277 of file plugin_transport_template.c.

Referenced by libgnunet_plugin_transport_template_init().

278 {
279  return 3;
280 }
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 291 of file plugin_transport_template.c.

References GNUNET_assert, and GNUNET_NT_UNSPECIFIED.

Referenced by libgnunet_plugin_transport_template_init().

293 {
294  GNUNET_assert (NULL != session);
295  return GNUNET_NT_UNSPECIFIED; /* Change to correct network type */
296 }
#define GNUNET_assert(cond)
Use this for fatal errors that cannot be handled.
Category of last resort.
Definition: gnunet_nt_lib.h:40
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 307 of file plugin_transport_template.c.

References GNUNET_NT_WAN.

Referenced by libgnunet_plugin_transport_template_init().

310 {
311  return GNUNET_NT_WAN; /* FOR NOW */
312 }
Wide area network (i.e.
Definition: gnunet_nt_lib.h:55
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 330 of file plugin_transport_template.c.

References GNUNET_OK.

Referenced by libgnunet_plugin_transport_template_init().

336 {
337  asc (asc_cls, "converted address", GNUNET_OK); /* return address */
338  asc (asc_cls, NULL, GNUNET_OK); /* done */
339 }
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 355 of file plugin_transport_template.c.

References GNUNET_OK.

Referenced by libgnunet_plugin_transport_template_init().

356 {
357  /* struct Plugin *plugin = cls; */
358 
359  /* check if the address is belonging to the plugin*/
360  return GNUNET_OK;
361 }
#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 376 of file plugin_transport_template.c.

References GNUNET_break, and TRANSPORT_SESSION_INBOUND_STRING.

Referenced by libgnunet_plugin_transport_template_init().

377 {
378  /*
379  * Print address in format template.options.address
380  */
381 
382  if (0 == addrlen)
383  {
385  }
386 
387  GNUNET_break (0);
388  return NULL;
389 }
#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 405 of file plugin_transport_template.c.

References GNUNET_break, and GNUNET_SYSERR.

Referenced by libgnunet_plugin_transport_template_init().

409 {
410  /*
411  * Parse string in format template.options.address
412  */
413  GNUNET_break (0);
414  return GNUNET_SYSERR;
415 }
#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 428 of file plugin_transport_template.c.

References GNUNET_break.

Referenced by libgnunet_plugin_transport_template_init().

430 {
431  GNUNET_break (0);
432  return NULL;
433 }
#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 437 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().

440 {
441 }
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 485 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().

488 {
489  struct Plugin *plugin = cls;
490 
491  plugin->sic = sic;
492  plugin->sic_cls = sic_cls;
493  if (NULL != sic)
494  {
495 #if 0
496  GNUNET_CONTAINER_multipeermap_iterate (NULL /* FIXME */,
498  plugin);
499 #endif
500  /* signal end of first iteration */
501  sic (sic_cls, NULL, NULL);
502  }
503 }
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 char * plugin
Solver plugin name as string.
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 510 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.

511 {
514  struct Plugin *plugin;
515 
516  if (NULL == env->receive)
517  {
518  /* run in 'stub' mode (i.e. as part of gnunet-peerinfo), don't fully
519  initialze the plugin or the API */
521  api->cls = NULL;
525  return api;
526  }
527 
528  plugin = GNUNET_new (struct Plugin);
529  plugin->env = env;
531  api->cls = plugin;
532  api->send = &template_plugin_send;
545  LOG (GNUNET_ERROR_TYPE_INFO, "Template plugin successfully loaded\n");
546  return api;
547 }
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:47
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...
#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 char * plugin
Solver plugin name as string.
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 554 of file plugin_transport_template.c.

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

555 {
557  struct Plugin *plugin = api->cls;
558 
559  GNUNET_free (plugin);
560  GNUNET_free (api);
561  return NULL;
562 }
Each plugin is required to return a pointer to a struct of this type as the return value from its ent...
void * cls
Closure for all of the callbacks.
static char * plugin
Solver plugin name as string.
Handle for a plugin.
Definition: block.c:37
#define GNUNET_free(ptr)
Wrapper around free.