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_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 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:

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

cls	closure
session	which session must be used
msgbuf	the message to transmit
msgbuf_size	number of bytes in msgbuf
priority	how important is the message (most plugins will ignore message priority and just FIFO)
to	how long to wait at most for the transmission (does not require plugins to discard the message after the timeout, just advisory for the desired delay; most plugins will ignore this as well)
cont	continuation to call once the message has been transmitted (or if the transport is ready for the next transmission call; or if the peer disconnected...); can be NULL
cont_cls	closure 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.

{
  /*  struct Plugin *plugin = cls; */
  ssize_t bytes_sent = 0;
 
  return bytes_sent;
}

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

cls	closure
target	peer from which to disconnect

Definition at line 241 of file plugin_transport_template.c.

{
  // struct Plugin *plugin = cls;
  // FIXME
}

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

cls	closure
session	session from which to disconnect

Returns

GNUNET_OK on success

Definition at line 259 of file plugin_transport_template.c.

{
  // struct Plugin *plugin = cls;
  // FIXME
  return 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

cls	closure with the struct Plugin

Returns

keepalive factor

Definition at line 277 of file plugin_transport_template.c.

{
  return 3;
}

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

cls	closure ('struct Plugin*')
session	the session

Returns

the network type in HBO or GNUNET_SYSERR

Definition at line 277 of file plugin_transport_template.c.

{
  GNUNET_assert (NULL != session);
  return GNUNET_NT_UNSPECIFIED; /* Change to correct network type */
}

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

cls	closure (struct Plugin *)
address	the address

Returns

the network type

Definition at line 277 of file plugin_transport_template.c.

{
  return GNUNET_NT_WAN; /* FOR NOW */
}

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

cls	closure
type	name of the transport that generated the address
addr	one of the addresses of the host, NULL for the last address the specific address format depends on the transport
addrlen	length of the address
numeric	should (IP) addresses be displayed in numeric form?
timeout	after how long should we give up?
asc	function to call on each string
asc_cls	closure for asc

Definition at line 330 of file plugin_transport_template.c.

{
  asc (asc_cls, "converted address", GNUNET_OK);  /* return address */
  asc (asc_cls, NULL, GNUNET_OK);  /* done */
}

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

cls	closure
addr	pointer to the address
addrlen	length 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.

{
  /* struct Plugin *plugin = cls; */
 
  /* check if the address is belonging to the plugin*/
  return GNUNET_OK;
}

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

cls	closure
addr	binary address
addrlen	length of the address

Returns

string representing the same address

Definition at line 376 of file plugin_transport_template.c.

{
  /*
   * Print address in format template.options.address
   */
 
  if (0 == addrlen)
  {
    return TRANSPORT_SESSION_INBOUND_STRING;
  }
 
  GNUNET_break (0);
  return NULL;
}

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

cls	closure ('struct Plugin*')
addr	string address
addrlen	length of the addr
buf	location to store the buffer
added	location 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.

{
  /*
   * Parse string in format template.options.address
   */
  GNUNET_break (0);
  return GNUNET_SYSERR;
}

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

cls	closure
address	pointer 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.

{
  GNUNET_break (0);
  return NULL;
}

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.

{
}

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

cls	closure of the plugin
sic	callback to invoke, NULL to disable monitor; plugin will being by iterating over all active sessions immediately and then enter monitor mode
sic_cls	closure for sic

Definition at line 485 of file plugin_transport_template.c.

{
  struct Plugin *plugin = cls;
 
  plugin->sic = sic;
  plugin->sic_cls = sic_cls;
  if (NULL != sic)
  {
#if 0
    GNUNET_CONTAINER_multipeermap_iterate (NULL /* FIXME */,
                                           &send_session_info_iter,
                                           plugin);
#endif
    /* signal end of first iteration */
    sic (sic_cls, NULL, NULL);
  }
}

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.

{
  struct GNUNET_TRANSPORT_PluginEnvironment *env = cls;
  struct GNUNET_TRANSPORT_PluginFunctions *api;
  struct Plugin *plugin;
 
  if (NULL == env->receive)
  {
    /* run in 'stub' mode (i.e. as part of gnunet-peerinfo), don't fully
       initialize the plugin or the API */
    api = GNUNET_new (struct GNUNET_TRANSPORT_PluginFunctions);
    api->cls = NULL;
    api->address_to_string = &template_plugin_address_to_string;
    api->string_to_address = &template_plugin_string_to_address;
    api->address_pretty_printer = &template_plugin_address_pretty_printer;
    return api;
  }
 
  plugin = GNUNET_new (struct Plugin);
  plugin->env = env;
  api = GNUNET_new (struct GNUNET_TRANSPORT_PluginFunctions);
  api->cls = plugin;
  api->send = &template_plugin_send;
  api->disconnect_peer = &template_plugin_disconnect_peer;
  api->disconnect_session = &template_plugin_disconnect_session;
  api->query_keepalive_factor = &template_plugin_query_keepalive_factor;
  api->address_pretty_printer = &template_plugin_address_pretty_printer;
  api->check_address = &template_plugin_address_suggested;
  api->address_to_string = &template_plugin_address_to_string;
  api->string_to_address = &template_plugin_string_to_address;
  api->get_session = &template_plugin_get_session;
  api->get_network = &template_plugin_get_network;
  api->get_network_for_address = &template_plugin_get_network_for_address;
  api->update_session_timeout = &template_plugin_update_session_timeout;
  api->setup_monitor = &template_plugin_setup_monitor;
  LOG (GNUNET_ERROR_TYPE_INFO, "Template plugin successfully loaded\n");
  return api;
}

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.

{
  struct GNUNET_TRANSPORT_PluginFunctions *api = cls;
  struct Plugin *plugin = api->cls;
 
  GNUNET_free (plugin);
  GNUNET_free (api);
  return NULL;
}