GNUnet  0.19.5
plugin_transport_template.c File Reference

template for a new transport service More...

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__)

Definition at line 34 of file plugin_transport_template.c.

◆ 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:484

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.

224 {
225  /* struct Plugin *plugin = cls; */
226  ssize_t bytes_sent = 0;
227 
228  return bytes_sent;
229 }

Referenced by libgnunet_plugin_transport_template_init().

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.

243 {
244  // struct Plugin *plugin = cls;
245  // FIXME
246 }

Referenced by libgnunet_plugin_transport_template_init().

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.

261 {
262  // struct Plugin *plugin = cls;
263  // FIXME
264  return GNUNET_SYSERR;
265 }
@ GNUNET_SYSERR

References GNUNET_SYSERR.

Referenced by libgnunet_plugin_transport_template_init().

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.

278 {
279  return 3;
280 }

Referenced by libgnunet_plugin_transport_template_init().

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

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.
@ GNUNET_NT_UNSPECIFIED
Category of last resort.
Definition: gnunet_nt_lib.h:43

Referenced by libgnunet_plugin_transport_template_init().

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

310 {
311  return GNUNET_NT_WAN; /* FOR NOW */
312 }
@ GNUNET_NT_WAN
Wide area network (i.e.
Definition: gnunet_nt_lib.h:58

Referenced by libgnunet_plugin_transport_template_init().

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.

336 {
337  asc (asc_cls, "converted address", GNUNET_OK); /* return address */
338  asc (asc_cls, NULL, GNUNET_OK); /* done */
339 }
@ GNUNET_OK

References GNUNET_OK.

Referenced by libgnunet_plugin_transport_template_init().

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.

356 {
357  /* struct Plugin *plugin = cls; */
358 
359  /* check if the address is belonging to the plugin*/
360  return GNUNET_OK;
361 }

References GNUNET_OK.

Referenced by libgnunet_plugin_transport_template_init().

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.

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 GNUNET_break(cond)
Use this for internal assertion violations that are not fatal (can be handled) but should not occur.
#define TRANSPORT_SESSION_INBOUND_STRING

References GNUNET_break, and TRANSPORT_SESSION_INBOUND_STRING.

Referenced by libgnunet_plugin_transport_template_init().

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.

409 {
410  /*
411  * Parse string in format template.options.address
412  */
413  GNUNET_break (0);
414  return GNUNET_SYSERR;
415 }

References GNUNET_break, and GNUNET_SYSERR.

Referenced by libgnunet_plugin_transport_template_init().

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.

430 {
431  GNUNET_break (0);
432  return NULL;
433 }

References GNUNET_break.

Referenced by libgnunet_plugin_transport_template_init().

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.

440 {
441 }

Referenced by libgnunet_plugin_transport_template_init().

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.

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 }
struct TestcasePlugin * plugin
The process handle to the testbed service.
int GNUNET_CONTAINER_multipeermap_iterate(struct GNUNET_CONTAINER_MultiPeerMap *map, GNUNET_CONTAINER_PeerMapIterator it, void *it_cls)
Iterate over all entries in the map.
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.
Handle for a plugin.
Definition: block.c:38
void * sic_cls
Closure for sic.
GNUNET_TRANSPORT_SessionInfoCallback sic
Function to call about session status changes.

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

Referenced by libgnunet_plugin_transport_template_init().

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.

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  initialize the plugin or the API */
521  api->cls = NULL;
522  api->address_to_string = &template_plugin_address_to_string;
523  api->string_to_address = &template_plugin_string_to_address;
524  api->address_pretty_printer = &template_plugin_address_pretty_printer;
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;
533  api->disconnect_peer = &template_plugin_disconnect_peer;
534  api->disconnect_session = &template_plugin_disconnect_session;
535  api->query_keepalive_factor = &template_plugin_query_keepalive_factor;
536  api->address_pretty_printer = &template_plugin_address_pretty_printer;
537  api->check_address = &template_plugin_address_suggested;
538  api->address_to_string = &template_plugin_address_to_string;
539  api->string_to_address = &template_plugin_string_to_address;
540  api->get_session = &template_plugin_get_session;
541  api->get_network = &template_plugin_get_network;
542  api->get_network_for_address = &template_plugin_get_network_for_address;
543  api->update_session_timeout = &template_plugin_update_session_timeout;
544  api->setup_monitor = &template_plugin_setup_monitor;
545  LOG (GNUNET_ERROR_TYPE_INFO, "Template plugin successfully loaded\n");
546  return api;
547 }
struct GNUNET_MQ_Envelope * env
Definition: 005.c:1
@ GNUNET_ERROR_TYPE_INFO
#define GNUNET_new(type)
Allocate a struct or union of the given type.
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.
static enum GNUNET_NetworkType template_plugin_get_network(void *cls, struct GNUNET_ATS_Session *session)
Function obtain the network type for a session.
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.
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...
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.
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...
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.
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 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 unsigned int template_plugin_query_keepalive_factor(void *cls)
Function that is called to get the keepalive factor.
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.
#define LOG(kind,...)
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.
void * cls
Closure for all of the callbacks.
The transport service will pass a pointer to a struct of this type as the first and only argument to ...
void * cls
Closure for the various callbacks.
Each plugin is required to return a pointer to a struct of this type as the return value from its ent...
struct GNUNET_BLOCK_PluginFunctions * api
Plugin API.
Definition: block.c:47

References Plugin::api, GNUNET_BLOCK_PluginFunctions::cls, GNUNET_TRANSPORT_PluginEnvironment::cls, env, GNUNET_ERROR_TYPE_INFO, GNUNET_new, LOG, plugin, 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(), and template_plugin_update_session_timeout().

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.

555 {
557  struct Plugin *plugin = api->cls;
558 
560  GNUNET_free (api);
561  return NULL;
562 }
#define GNUNET_free(ptr)
Wrapper around free.
void * cls
Closure for all of the callbacks.