LibFlute::Transmitter Class Reference

FLUTE transmitter class. More...

#include <Transmitter.h>

Classes
class	FileDescription
	File Description object. More...

Public Types
using	FdtNamespace = FileDeliveryTable::FdtNamespace
	FDT namespace enumeration. More...
typedef std::function< void(uint32_t)>	completion_callback_t
	Definition of a file transmission completion callback function that can be registered through ::register_completion_callback. More...

Public Member Functions
	Transmitter (const std::string &destination_address, short port, uint64_t tsi, unsigned short mtu, uint32_t rate_limit, boost::asio::io_context &io_context, const std::optional< boost::asio::ip::udp::endpoint > &tunnel_endpoint=std::nullopt, FdtNamespace fdt_namespace=FileDeliveryTable::FDT_NS_NONE, bool active=true, const std::optional< std::string > &source_address=std::nullopt)
	Constructor. More...
virtual	~Transmitter ()
	Default destructor. More...
const std::optional< boost::asio::ip::udp::endpoint > &	udp_tunnel_address () const
	Get UDP Tunnel Address. More...
Transmitter &	udp_tunnel_address (const boost::asio::ip::udp::endpoint &new_tunnel_endpoint)
	Set UDP Tunnel Address. More...
Transmitter &	udp_tunnel_address (boost::asio::ip::udp::endpoint &&new_tunnel_endpoint)
	Set UDP Tunnel Address. More...
Transmitter &	udp_tunnel_address (const std::optional< boost::asio::ip::udp::endpoint > &new_tunnel_endpoint)
	Set UDP Tunnel Address. More...
Transmitter &	udp_tunnel_address (std::optional< boost::asio::ip::udp::endpoint > &&new_tunnel_endpoint)
	Set UDP Tunnel Address. More...
Transmitter &	udp_tunnel_address (const std::nullopt_t &)
	Unset UDP Tunnel Address. More...
uint32_t	rate_limit () const
	Get Maximum Bit Rate. More...
Transmitter &	rate_limit (uint32_t limit)
	Set Maximum Bit Rate. More...
const boost::asio::ip::udp::endpoint &	endpoint () const
	Get UDP Address for FLUTE session. More...
Transmitter &	endpoint (const std::string &address, uint32_t port)
	Set UDP Address for FLUTE session. More...
const std::optional< boost::asio::ip::address > &	source_address () const
	Get the optional source address for the FLUTE session. More...
void	enable_ipsec (uint32_t spi, const std::string &aes_key)
	Enable IPSEC ESP encryption of FLUTE payloads. More...
uint16_t	send (const std::string &content_location, const std::string &content_type, uint32_t expires, char *data, size_t length)
	Transmit a file (deprecated). More...
uint16_t	send (const std::shared_ptr< FileDescription > &file_description)
	Transmit a file. More...
uint64_t	seconds_since_epoch ()
	Convenience function to get the current timestamp for expiry calculation. More...
void	register_completion_callback (completion_callback_t cb)
	Register a callback for file transmission completion notifications. More...
void	activate ()
	Activate the FLUTE session. More...
void	deactivate (bool finish_file_transmissions=false)
	Deactivate the FLUTE session. More...
size_t	number_of_files ()
	Get number of files currently in queue for sending. More...
Transmitter &	endpoint (const boost::asio::ip::udp::endpoint &destination)
	Set UDP Address for FLUTE session. More...
Transmitter &	endpoint (boost::asio::ip::udp::endpoint &&destination)
Transmitter &	source_address (const std::optional< boost::asio::ip::address > &source)
	Set the source address for FLUTE session. More...
Transmitter &	source_address (std::optional< boost::asio::ip::address > &&source)

Detailed Description

FLUTE transmitter class.

Construct an instance of this to send data through a FLUTE/ALC session.

The session can be active (sending packets) or inactive (sending of packets paused). This allows the FLUTE session to be suspended using the deactivate() method and later resumed using activate().

Definition at line 41 of file Transmitter.h.

Member Typedef Documentation

completion_callback_t

typedef std::function<void(uint32_t)> LibFlute::Transmitter::completion_callback_t

Definition of a file transmission completion callback function that can be registered through ::register_completion_callback.

Parameters

toi	TOI of the file that has completed transmission

Definition at line 384 of file Transmitter.h.

FdtNamespace

using LibFlute::Transmitter::FdtNamespace = FileDeliveryTable::FdtNamespace

FDT namespace enumeration.

Definition at line 46 of file Transmitter.h.

Constructor & Destructor Documentation

Transmitter()

LibFlute::Transmitter::Transmitter	(	const std::string &	destination_address,
		short	port,
		uint64_t	tsi,
		unsigned short	mtu,
		uint32_t	rate_limit,
		boost::asio::io_context &	io_context,
		const std::optional< boost::asio::ip::udp::endpoint > &	tunnel_endpoint = std::nullopt,
		Transmitter::FdtNamespace	fdt_namespace = FileDeliveryTable::FDT_NS_NONE,
		bool	active = true,
		const std::optional< std::string > &	source_address = std::nullopt
	)

Constructor.

Creates a Transmitter object.

If tunnel_endpoint is given a value then:

• destination_address is the encapsulated destination IP addresses.
• If source_address has a value then this is used as the encapsulated source IP address, if not then the source address of the connection to tunnel_endpoint is used.

If tunnel_endpoint is not given a value then:

• destination_address is the destination address for the connection.
• If source_address has a value then an attempt will be made to bind the local end of the connection to this address. If the attempt is unsuccessful then a std::runtime_error exception will be thrown.

Parameters

destination_address	Target (multicast) address, if tunnel_endpoint is given then this is the encapsulated destination IP address
port	Target port
tsi	TSI value for the session
mtu	Path MTU to size FLUTE packets for
rate_limit	Transmit rate limit (in kbps)
io_context	Boost io_context to run the socket operations in (must be provided by the caller)
tunnel_endpoint	Tunnelling endpoint address (default: no tunnelling)
fdt_namespace	Which XML namespace to use for the FDT (default: none)
active	Start as active/inactive FLUTE session (default: active)
source_address	Source address (default: automatically assign source address)

Exceptions

boost::system::system_error

When source_address is given a value and tunnel_endpoint has no value and the address in source_address could not be bound as the local end of the connection.

Definition at line 475 of file Transmitter.cpp.

    : _endpoint(boost::asio::ip::make_address(destination_address), port)
    , _source_address()
    , _socket(io_context, _endpoint.protocol())
    , _io_context(io_context)
    , _send_timer(io_context)
    , _fdt_timer(io_context)
    , _tsi(tsi)
    , _mtu(mtu)
    , _files()
    , _files_mutex()
    , _mcast_address(destination_address)
    , _rate_limit(rate_limit)
    , _tunnel_endpoint(tunnel_endpoint)
    , _tunnel_local_address()
    , _active(active)
{
  if (source_address) {
    _source_address = boost::asio::ip::make_address(source_address.value());
  }
  _max_payload = mtu -
    20 - // IPv4 header
     8 - // UDP header
    32 - // ALC Header with EXT_FDT and EXT_FTI
     4;  // SBN and ESI for compact no-code FEC
  if (_tunnel_endpoint.has_value()) {
    // Remove extra overhead for UDP tunnelling, if set
    _max_payload -= 20 + // IPv4 header
                    8; // UDP header
    boost::asio::ip::udp::socket local_socket(_io_context, _tunnel_endpoint.value().protocol());
    local_socket.connect(_tunnel_endpoint.value());
    _tunnel_local_address = local_socket.local_endpoint().address();
  }
  uint32_t max_source_block_length = 64;
 
  _socket.set_option(boost::asio::ip::multicast::enable_loopback(true));
  _socket.set_option(boost::asio::ip::udp::socket::reuse_address(true));
 
  if (_source_address && !_tunnel_endpoint) {
    _socket.bind(boost::asio::ip::udp::endpoint(_source_address.value(),0));
  }
 
  _fec_oti = FecOti{
    .encoding_id = FecScheme::CompactNoCode,
    .encoding_symbol_length = _max_payload,
    .max_source_block_length = max_source_block_length};
  _fdt = std::make_unique<FileDeliveryTable>(1, _fec_oti, fdt_namespace);
 
  if (_active) {
    start_fdt_repeat_timer();
    send_next_packet();
  }
}

~Transmitter()

LibFlute::Transmitter::~Transmitter ( )

virtualdefault

Default destructor.

Member Function Documentation

activate()

auto LibFlute::Transmitter::activate

(

)

Activate the FLUTE session.

If the Transmitter is currently deactivated then the state is set to active and the FLUTE stream will start transmitting. Sending of packets will start or resume until the deactivate() method is called or this Transmitter is destroyed.

Definition at line 858 of file Transmitter.cpp.

{
  if (!_active) {
    _deactivate_when_all_files_sent = false;
    _active = true;
    start_fdt_repeat_timer();
    send_next_packet();
  }
}

deactivate()

auto LibFlute::Transmitter::deactivate

(

bool

finish_file_transmissions = false

)

Deactivate the FLUTE session.

If the Transmitter is currently active then the FLUTE stream is halted and the state is changed to deactivated. Sending of packets will be halted until the activate() method is called. Note that this will pause File transmission part way through if a File is currently being transmitted.

When finish_file_transmissions is true the Transmitter will remain active until the queued transmissions have completed and will then become inactive. This allows applications to request deactivation without waiting for completion callbacks and checking number_of_files().

Parameters

finish_file_transmissions

If true, defer deactivation until all queued transmissions complete. If false (default), halt transmission immediately.

Definition at line 868 of file Transmitter.cpp.

{
  if (_active) {
    if (finish_file_transmissions) {
      std::lock_guard<std::mutex> guard(_files_mutex);
      if (!_files.empty()) {
        _deactivate_when_all_files_sent = true;
        return;
      }
 
      _complete_deactivation();
      return;
    }
 
    _complete_deactivation();
  }
}

enable_ipsec()

auto LibFlute::Transmitter::enable_ipsec	(	uint32_t	spi,
		const std::string &	aes_key
	)

Enable IPSEC ESP encryption of FLUTE payloads.

Parameters

spi	Security Parameter Index value to use
aes_key	AES key as a hex string (without leading 0x). Must be an even number of characters long.

Definition at line 616 of file Transmitter.cpp.

{
  IpSec::enable_esp(spi, _mcast_address, IpSec::Direction::Out, key);
}

endpoint() [1/4]

const boost::asio::ip::udp::endpoint& LibFlute::Transmitter::endpoint ( ) const

inline

Get UDP Address for FLUTE session.

Gets the destination address for the FLUTE session packets. If the UDP tunnel address is set then the packets will be tunnelled to the UDP tunnel address, otherwise packets are sent directly to the destination address.

Returns

The current destination address.

Definition at line 513 of file Transmitter.h.

{ return _endpoint; };

endpoint() [2/4]

auto LibFlute::Transmitter::endpoint

(

boost::asio::ip::udp::endpoint &&

destination

)

Definition at line 592 of file Transmitter.cpp.

{
  _endpoint = std::move(destination);
  return *this;
}

endpoint() [3/4]

auto LibFlute::Transmitter::endpoint

(

const boost::asio::ip::udp::endpoint &

destination

)

Set UDP Address for FLUTE session.

Sets the destination address for FLUTE session packets. If the UDP Tunnel Address is not set then FLUTE packets will be sent directly to this UDP endpoint. When a UDP Tunnel Address is set then FLUTE packets with this destination will be tunnelled to the UDP Tunnel Address.

Parameters

destination

The UDP endpoint to set as the FLUTE packet destination address and port.

Returns

This Transmitter object.

Definition at line 586 of file Transmitter.cpp.

{
  _endpoint = destination;
  return *this;
}

endpoint() [4/4]

auto LibFlute::Transmitter::endpoint	(	const std::string &	address,
		uint32_t	port
	)

Set UDP Address for FLUTE session.

Sets the destination address for FLUTE session packets. If the UDP Tunnel Address is not set then FLUTE packets will be sent directly to this UDP endpoint. When a UDP Tunnel Address is set then FLUTE packets with this destination will be tunnelled to the UDP Tunnel Address.

Parameters

address	The IP address or hostname to set as the FLUTE packet destination address.
port	The UDP port number to set as the FLUTE packet destination UDP port.

Returns

This Transmitter object.

Definition at line 581 of file Transmitter.cpp.

{
  return endpoint(boost::asio::ip::udp::endpoint(boost::asio::ip::make_address(address), port));
}

number_of_files()

size_t LibFlute::Transmitter::number_of_files ( )

inline

Get number of files currently in queue for sending.

Returns

The number of files in the queue for sending.

Definition at line 659 of file Transmitter.h.

{ std::lock_guard<std::mutex> guard(_files_mutex); return _files.size(); };

rate_limit() [1/2]

uint32_t LibFlute::Transmitter::rate_limit ( ) const

inline

Get Maximum Bit Rate.

Returns the maximum bit rate (MBR) value that the Transmitter is using. A 0 MBR means no limit.

Returns

The maximum bit rate.

Definition at line 493 of file Transmitter.h.

{ return _rate_limit; };

rate_limit() [2/2]

Transmitter& LibFlute::Transmitter::rate_limit ( uint32_t  limit )

inline

Set Maximum Bit Rate.

Sets the MBR for transmission. A value of 0 indicates no rate limit.

Parameters

limit

The new MBR to set.

Returns

This Transmitter object.

Definition at line 503 of file Transmitter.h.

{ _rate_limit = limit; return *this; };

register_completion_callback()

void LibFlute::Transmitter::register_completion_callback ( completion_callback_t  cb )

inline

Register a callback for file transmission completion notifications.

Parameters

cb	Function to call on file completion

Definition at line 628 of file Transmitter.h.

{ _completion_cb = cb; };

seconds_since_epoch()

auto LibFlute::Transmitter::seconds_since_epoch

(

)

Convenience function to get the current timestamp for expiry calculation.

Returns

seconds since the NTP epoch

Definition at line 627 of file Transmitter.cpp.

{
  return std::chrono::duration_cast<std::chrono::seconds>(
      std::chrono::system_clock::now().time_since_epoch()).count() +
      2'208'988'800; /* add the difference in seconds between the Unix epoch (1 January 1970, 00:00:00 UTC)
                        and the NTP epoch (1 January 1900, 00:00:00 UTC) */
}

send() [1/2]

uint16_t LibFlute::Transmitter::send

(

const std::shared_ptr< FileDescription > &

file_description

)

Transmit a file.

The caller must ensure the file description passed here remains valid until the completion callback for this file description is called.

The file description object passed in file_description may be updated by the Transmitter until the completion callback for this file description is called.

If a file description is reused then the TOI of the previous use is reused. This allows resends or updates to existing files to be transmitted.

Parameters

file_description

The file description object for the file to send

Returns

TOI of the file.

send() [2/2]

auto LibFlute::Transmitter::send	(	const std::string &	content_location,
		const std::string &	content_type,
		uint32_t	expires,
		char *	data,
		size_t	length
	)

Transmit a file (deprecated).

Deprecated:

send(FileDescription*) should be used instead.

The caller must ensure the data buffer passed here remains valid until the completion callback for this file is called.

Parameters

content_location	URI to set in the content location field of the generated FDT entry
content_type	MIME type to set in the content type field of the generated FDT entry
expires	Expiry timestamp (based on NTP epoch)
data	Pointer to the data buffer (managed by caller)
length	Length of the data buffer (in bytes)

Returns

TOI of the file

Definition at line 659 of file Transmitter.cpp.

{
  auto toi = _toi;
  _toi++;
  if (_toi == 0) _toi = 1; // clamp to >= 1 in case it wraps
 
  auto file = std::make_shared<File>(
        toi,
        _fec_oti,
        content_location,
        content_type,
        expires,
        data,
        length);
 
  _fdt->add(file->meta());
  send_fdt();
  {
    std::lock_guard<std::mutex> guard(_files_mutex);
    _files.insert({toi, file});
  }
  return toi;
}

source_address() [1/3]

const std::optional<boost::asio::ip::address>& LibFlute::Transmitter::source_address ( ) const

inline

Get the optional source address for the FLUTE session.

Returns

The optional source address being used.

Definition at line 550 of file Transmitter.h.

{ return _source_address; };

source_address() [2/3]

auto LibFlute::Transmitter::source_address

(

const std::optional< boost::asio::ip::address > &

source

)

Set the source address for FLUTE session.

Sets the optional source address to use for FLUTE session packets. If the UDP Tunnel Address is not set then the outgoing socket will be bound to this address, if set. When a UDP Tunnel Address is set then this provides the source address for encapsulated packets. If the source address is not set then a local address will be selected automatically.

Parameters

source

The IP source address to use for FLUTE packets.

Returns

This Transmitter object.

Exceptions

boost::system::system_error

If UDP tunnel is not used and the UDP socket cannot be bound to source.

Definition at line 598 of file Transmitter.cpp.

{
  _source_address = source_address;
  if (_source_address && !_tunnel_endpoint) {
    _socket.bind(boost::asio::ip::udp::endpoint(_source_address.value(),0));
  }
  return *this;
}

source_address() [3/3]

auto LibFlute::Transmitter::source_address

(

std::optional< boost::asio::ip::address > &&

source

)

Definition at line 607 of file Transmitter.cpp.

{
  _source_address = std::move(source_address);
  if (_source_address && !_tunnel_endpoint) {
    _socket.bind(boost::asio::ip::udp::endpoint(_source_address.value(),0));
  }
  return *this;
}

udp_tunnel_address() [1/6]

const std::optional<boost::asio::ip::udp::endpoint>& LibFlute::Transmitter::udp_tunnel_address ( ) const

inline

Get UDP Tunnel Address.

Returns

The optional UDP Tunnel Address for the Transmitter to use.

Definition at line 435 of file Transmitter.h.

{ return _tunnel_endpoint; };

udp_tunnel_address() [2/6]

auto LibFlute::Transmitter::udp_tunnel_address

(

boost::asio::ip::udp::endpoint &&

new_tunnel_endpoint

)

Set UDP Tunnel Address.

Sets the UDP tunnel endpoint to be new_tunnel_endpoint. This moves the value from new_tunnel_endpoint.

Parameters

new_tunnel_endpoint

The new UDP tunnel endpoint to set.

Returns

This Transmitter object.

Definition at line 541 of file Transmitter.cpp.

{
  return udp_tunnel_address(std::optional<boost::asio::ip::udp::endpoint>(std::move(new_tunnel_endpoint)));
}

udp_tunnel_address() [3/6]

auto LibFlute::Transmitter::udp_tunnel_address

(

const boost::asio::ip::udp::endpoint &

new_tunnel_endpoint

)

Set UDP Tunnel Address.

Sets the UDP tunnel endpoint to be a copy of new_tunnel_endpoint.

Parameters

new_tunnel_endpoint

The new UDP tunnel endpoint to set.

Returns

This Transmitter object.

Definition at line 536 of file Transmitter.cpp.

{
  return udp_tunnel_address(std::optional<boost::asio::ip::udp::endpoint>(new_tunnel_endpoint));
}

udp_tunnel_address() [4/6]

auto LibFlute::Transmitter::udp_tunnel_address

(

const std::nullopt_t &

)

Unset UDP Tunnel Address.

Removes the UDP tunnel endpoint. If the stream is active then it will switch back to multicast transmission.

Returns

This Transmitter object.

Definition at line 576 of file Transmitter.cpp.

{
  return udp_tunnel_address(std::optional<boost::asio::ip::udp::endpoint>(std::nullopt));
}

udp_tunnel_address() [5/6]

auto LibFlute::Transmitter::udp_tunnel_address

(

const std::optional< boost::asio::ip::udp::endpoint > &

new_tunnel_endpoint

)

Set UDP Tunnel Address.

Sets the UDP tunnel endpoint to be a copy of the optional new_tunnel_endpoint.

Parameters

new_tunnel_endpoint

The optional UDP tunnel endpoint to set.

Returns

This Transmitter object.

Definition at line 546 of file Transmitter.cpp.

{
  return udp_tunnel_address(std::move(std::optional<boost::asio::ip::udp::endpoint>(new_tunnel_endpoint)));
}

udp_tunnel_address() [6/6]

auto LibFlute::Transmitter::udp_tunnel_address

(

std::optional< boost::asio::ip::udp::endpoint > &&

new_tunnel_endpoint

)

Set UDP Tunnel Address.

Sets the UDP tunnel endpoint to be the optional new_tunnel_endpoint. This moves the value from new_tunnel_endpoint.

Parameters

new_tunnel_endpoint

The optional UDP tunnel endpoint to set.

Returns

This Transmitter object.

Definition at line 551 of file Transmitter.cpp.

{
  if (!!_tunnel_endpoint == !!new_tunnel_endpoint) {
    /* change existing tunnel */
    if (_tunnel_endpoint) _tunnel_endpoint = new_tunnel_endpoint;
  } else if (_tunnel_endpoint) {
    /* removing tunnel */
    _max_payload += 20 + // IPv4 header
                    8; // UDP header
    _tunnel_endpoint = std::nullopt;
  } else {
    /* new tunnel */
    _tunnel_endpoint = std::move(new_tunnel_endpoint);
    _max_payload -= 20 + // IPv4 header
                    8; // UDP header
  }
 
  if (_tunnel_endpoint) {
    boost::asio::ip::udp::socket local_socket(_io_context, _tunnel_endpoint.value().protocol());
    local_socket.connect(_tunnel_endpoint.value());
    _tunnel_local_address = local_socket.local_endpoint().address();
  }
  return *this;
}

---

The documentation for this class was generated from the following files:

• include/Transmitter.h
• src/Transmitter.cpp