LibFlute::FileDeliveryTable Class Reference

A class for parsing and creating FLUTE FDTs (File Delivery Tables). More...

#include <FileDeliveryTable.h>

Classes
struct	FileEntry
	An entry for a file in the FDT. More...

Public Types
enum	FdtNamespace { FDT_NS_NONE = 0 , FDT_NS_RFC3926 , FDT_NS_DRAFT_2005 , FDT_NS_3GPP_CONSOLIDATED_V2 }
	FDT namespace enumeration. More...

Public Member Functions
	FileDeliveryTable (uint32_t instance_id, FecOti fec_oti, FdtNamespace fdt_namespace=FDT_NS_NONE)
	Create an empty FDT. More...
	FileDeliveryTable (uint32_t instance_id, char *buffer, size_t len)
	Parse an XML string and create a FDT class from it. More...
virtual	~FileDeliveryTable ()
	Default destructor. More...
uint32_t	instance_id ()
	Get the FDT instance ID. More...
void	set_expires (uint64_t exp)
	Set the expiry value. More...
void	add (const FileEntry &entry)
	Add a file entry. More...
void	remove (uint32_t toi)
	Remove a file entry. More...
std::string	to_string () const
	Serialize the FDT to an XML string. More...
const std::vector< FileEntry > &	file_entries () const
	Get all current file entries. More...
void	sent ()
	Mark instance sent. More...

Detailed Description

A class for parsing and creating FLUTE FDTs (File Delivery Tables).

Definition at line 29 of file FileDeliveryTable.h.

Member Enumeration Documentation

FdtNamespace

enum LibFlute::FileDeliveryTable::FdtNamespace

FDT namespace enumeration.

Enumerator
FDT_NS_NONE
FDT_NS_RFC3926
FDT_NS_DRAFT_2005
FDT_NS_3GPP_CONSOLIDATED_V2

Definition at line 34 of file FileDeliveryTable.h.

                        {
          FDT_NS_NONE = 0,
          FDT_NS_RFC3926,
          FDT_NS_DRAFT_2005,
//          FDT_NS_RFC6726, // FLUTE v2 - will need other things implementing to use this correctly
          FDT_NS_3GPP_CONSOLIDATED_V2
      };

Constructor & Destructor Documentation

FileDeliveryTable() [1/2]

LibFlute::FileDeliveryTable::FileDeliveryTable	(	uint32_t	instance_id,
		FecOti	fec_oti,
		FdtNamespace	fdt_namespace = FDT_NS_NONE
	)

Create an empty FDT.

Parameters

instance_id	FDT instance ID to set
fec_oti	Global FEC OTI parameters
fdt_namespace	The XML namespace to use for FDT

Definition at line 135 of file FileDeliveryTable.cpp.

  : _instance_id( instance_id )
  , _instance_id_sent( instance_id - 1 )
  , _global_fec_oti( fec_oti )
  , _fdt_namespace( fdt_namespace )
{
}

FileDeliveryTable() [2/2]

LibFlute::FileDeliveryTable::FileDeliveryTable	(	uint32_t	instance_id,
		char *	buffer,
		size_t	len
	)

Parse an XML string and create a FDT class from it.

Parameters

instance_id	FDT instance ID (from ALC headers)
buffer	String containing the FDT XML
len	Length of the buffer

Definition at line 143 of file FileDeliveryTable.cpp.

  : _instance_id( instance_id )
  , _instance_id_sent( instance_id - 1 )
  , _global_fec_oti()
{
  static const std::string mbms2007_ns("urn:3GPP:metadata:2007:MBMS:FLUTE:FDT"); // 3GPP TS 26.346 Clause 7.2.10.2
  static const std::string mbms2012_ns("urn:3GPP:metadata:2012:MBMS:FLUTE:FDT"); // 3GPP TS 26.346 Clause 7.2.10.2
  tinyxml2::XMLDocument doc(true, tinyxml2::COLLAPSE_WHITESPACE);
  doc.Parse(buffer, len);
  auto fdt_instance = doc.RootElement();
  // A malformed / truncated FDT buffer leaves no root element; every access
  // below (elementNamespace, Name(), ...) would then dereference null and crash
  // the receiver. Throw instead so Receiver::handle_receive_from's
  // catch(std::exception&) drops the bad FDT and keeps the client alive.
  if (doc.Error() || fdt_instance == nullptr) {
    spdlog::warn("FDT parse failed ({}) at line {}, len={}",
                 doc.ErrorName() ? doc.ErrorName() : "?", doc.ErrorLineNum(), len);
    throw std::runtime_error(std::string("FDT XML parse failed: ") +
                             (doc.ErrorName() ? doc.ErrorName() : "no root element"));
  }
  XMLNamespaces root_ns(fdt_instance);
  auto fdt_ns = root_ns.elementNamespace(fdt_instance);
  if (!root_ns.matches(fdt_instance->Name(), "FDT-Instance", fdt_ns)) {
    throw std::runtime_error("Root element is not FDT-Instance");
  }
 
  if (fdt_ns == "") {
    _fdt_namespace = FDT_NS_NONE;
  } else if (fdt_ns == "http://www.example.com/flute") { // RFC 3926 Section 3.4.2
    _fdt_namespace = FDT_NS_RFC3926;
  } else if (fdt_ns == "urn:IETF:metadata:2005:FLUTE:FDT") { // 3GPP TS 26.346 Clause 7.2.10.1
    _fdt_namespace = FDT_NS_DRAFT_2005;
//  } else if (fdt_ns == "urn:ietf:params:xml:ns:fdt") { // RFC 6726 - FLUTEv2 - needs more work
//    _fdt_namespace = FDT_NS_RFC6726;
  } else if (fdt_ns == "urn:3GPP:metadata:2022:FLUTE:FDT") { // 3GPP TS 26.346 Clause L.6.1
    _fdt_namespace = FDT_NS_3GPP_CONSOLIDATED_V2;
  } else {
    throw std::runtime_error("FDT namespace not recognised");
  }
 
  _expires = std::stoull(root_ns.findAttribute(fdt_instance, "Expires", fdt_ns)->Value());
 
  spdlog::debug("Received new FDT with instance ID {}: {}", instance_id, buffer);
 
  auto val = root_ns.findAttribute(fdt_instance, "FEC-OTI-FEC-Encoding-ID", fdt_ns);
  if (val != nullptr) {
    _global_fec_oti.encoding_id = static_cast<FecScheme>(strtoul(val->Value(), nullptr, 0));
  }
 
  val = root_ns.findAttribute(fdt_instance, "FEC-OTI-FEC-Instance-ID", fdt_ns);
  if (val != nullptr) {
    _global_fec_oti.instance_id = strtoul(val->Value(), nullptr, 0);
  }
 
  val = root_ns.findAttribute(fdt_instance, "FEC-OTI-Maximum-Source-Block-Length", fdt_ns);
  if (val != nullptr) {
    _global_fec_oti.max_source_block_length = strtoul(val->Value(), nullptr, 0);
  }
 
  val = root_ns.findAttribute(fdt_instance, "FEC-OTI-Encoding-Symbol-Length", fdt_ns);
  if (val != nullptr) {
    _global_fec_oti.encoding_symbol_length = strtoul(val->Value(), nullptr, 0);
  }
 
  val = root_ns.findAttribute(fdt_instance, "FEC-OTI-Max-Number-of-Encoding-Symbols", fdt_ns);
  if (val != nullptr) {
    _global_fec_oti.max_number_of_encoding_symbols = strtoul(val->Value(), nullptr, 0);
  }
 
  for (auto file = root_ns.findChildElement(fdt_instance, "File", fdt_ns);
      file != nullptr; file = root_ns.findSiblingElement(file, "File", fdt_ns)) {
 
    XMLNamespaces file_ns(file, root_ns);
 
    // File required attributes
    auto toi_str = file_ns.findAttribute(file, "TOI", fdt_ns);
    if (toi_str == nullptr) {
      throw std::runtime_error("Missing TOI attribute on File element");
    }
    uint32_t toi = strtoull(toi_str->Value(), nullptr, 0);
 
    auto content_location = file_ns.findAttribute(file, "Content-Location", fdt_ns);
    if (content_location == nullptr) {
      throw std::runtime_error("Missing Content-Location attribute on File element");
    }
 
    // File optional attributes
    uint32_t content_length = 0;
    val = file_ns.findAttribute(file, "Content-Length", fdt_ns);
    if (val != nullptr) {
      content_length = strtoull(val->Value(), nullptr, 0);
    }
 
    uint32_t transfer_length = 0;
    val = file_ns.findAttribute(file, "Transfer-Length", fdt_ns);
    if (val != nullptr) {
      transfer_length = strtoull(val->Value(), nullptr, 0);
    } else {
      transfer_length = content_length;
    }
 
    auto content_md5 = std::string();
    val = file_ns.findAttribute(file, "Content-MD5", fdt_ns);
    if (val != nullptr) {
      content_md5 = val->Value();
    }
 
    auto content_encoding = std::string();
    val = file_ns.findAttribute(file, "Content-Encoding", fdt_ns);
    if (val != nullptr) {
      content_encoding = val->Value();
    }
 
    auto content_type = std::string();
    val = file_ns.findAttribute(file, "Content-Type", fdt_ns);
    if (val != nullptr) {
      content_type = val->Value();
    }
 
    auto encoding_id = _global_fec_oti.encoding_id;
    val = file_ns.findAttribute(file, "FEC-OTI-FEC-Encoding-ID", fdt_ns);
    if (val != nullptr) {
      encoding_id = static_cast<FecScheme>(strtoul(val->Value(), nullptr, 0));
    }
 
    auto fec_instance_id = _global_fec_oti.instance_id;
    val = file_ns.findAttribute(file, "FEC-OTI-FEC-Instance-ID", fdt_ns);
    if (val != nullptr) {
      fec_instance_id = strtoul(val->Value(), nullptr, 0);
    }
 
    auto max_source_block_length = _global_fec_oti.max_source_block_length;
    val = file_ns.findAttribute(file, "FEC-OTI-Maximum-Source-Block-Length", fdt_ns);
    if (val != nullptr) {
      max_source_block_length = strtoul(val->Value(), nullptr, 0);
    }
 
    auto encoding_symbol_length = _global_fec_oti.encoding_symbol_length;
    val = file_ns.findAttribute(file, "FEC-OTI-Encoding-Symbol-Length", fdt_ns);
    if (val != nullptr) {
      encoding_symbol_length = strtoul(val->Value(), nullptr, 0);
    }
 
    auto max_number_of_encoding_symbols = _global_fec_oti.max_number_of_encoding_symbols;
    val = file_ns.findAttribute(file, "FEC-OTI-Max-Number-of-Encoding-Symbols", fdt_ns);
    if (val != nullptr) {
      max_number_of_encoding_symbols = strtoul(val->Value(), nullptr, 0);
    }
 
    auto mbms2012_file_etag = "";
    val = file_ns.findAttribute(file, "File-ETag", mbms2012_ns);
    if (val != nullptr) {
      mbms2012_file_etag = val->Value();
    }
 
    // File optional elements
 
    bool no_cache = false;
    //bool max_stale = false;
    std::optional<uint64_t> cache_expires = std::nullopt;
    auto cc = file_ns.findChildElement(file, "Cache-Control", mbms2007_ns);
    if (cc) {
      XMLNamespaces cc_ns(cc, file_ns);
 
      // mbms2007:Cache-Control optional elements
 
      auto no_cache_elem = cc_ns.findChildElement(cc, "no-cache", mbms2007_ns);
      if (no_cache_elem) {
        no_cache = true;
      }
 
      //auto max_stale_elem = cc_ns.findChildElement(cc, "max-stale", mbms2007_ns);
      //if (max_stale_elem) {
      //  max_stale = true;
      //}
 
      auto expires_elem = cc_ns.findChildElement(cc, "Expires", mbms2007_ns);
      if (expires_elem) {
        cache_expires = strtoul(expires_elem->GetText(), nullptr, 0);
      }
    }
 
    FecOti fec_oti{
      .encoding_id = (FecScheme)encoding_id,
      .instance_id = fec_instance_id,
      .transfer_length = transfer_length,
      .encoding_symbol_length = encoding_symbol_length,
      .max_source_block_length = max_source_block_length,
      .max_number_of_encoding_symbols = max_number_of_encoding_symbols
    };
 
    FileEntry fe{
      toi,
      std::string(content_location->Value()),
      content_length,
      content_md5,
      content_type,
      (cache_expires)?(cache_expires.value()):0,
      fec_oti,
      {
        no_cache,
        cache_expires
      },
      content_encoding,
      mbms2012_file_etag
    };
    _file_entries.push_back(fe);
  }
}

~FileDeliveryTable()

virtual LibFlute::FileDeliveryTable::~FileDeliveryTable ( )

inlinevirtual

Default destructor.

Definition at line 63 of file FileDeliveryTable.h.

{};

Member Function Documentation

add()

auto LibFlute::FileDeliveryTable::add

(

const FileEntry &

entry

)

Add a file entry.

Definition at line 353 of file FileDeliveryTable.cpp.

{
  if (_instance_id == _instance_id_sent) _instance_id++;
  _file_entries.push_back(fe);
}

file_entries()

const std::vector<FileEntry>& LibFlute::FileDeliveryTable::file_entries ( ) const

inline

Get all current file entries.

Definition at line 115 of file FileDeliveryTable.h.

                                                       {
        return _file_entries;
      };

instance_id()

uint32_t LibFlute::FileDeliveryTable::instance_id ( )

inline

Get the FDT instance ID.

Definition at line 68 of file FileDeliveryTable.h.

{ return _instance_id; };

remove()

auto LibFlute::FileDeliveryTable::remove

(

uint32_t

toi

)

Remove a file entry.

Definition at line 359 of file FileDeliveryTable.cpp.

{
  for (auto it = _file_entries.cbegin(); it != _file_entries.cend();) {
    if (it->toi == toi) {
      it = _file_entries.erase(it);
    } else {
      ++it;
    }
  }
  if (_instance_id == _instance_id_sent) _instance_id++;
}

sent()

void LibFlute::FileDeliveryTable::sent ( )

inline

Mark instance sent.

Definition at line 122 of file FileDeliveryTable.h.

{ _instance_id_sent = _instance_id; };

set_expires()

void LibFlute::FileDeliveryTable::set_expires ( uint64_t  exp )

inline

Set the expiry value.

Definition at line 95 of file FileDeliveryTable.h.

{ _expires = exp; };

to_string()

auto LibFlute::FileDeliveryTable::to_string

(

)

const

Serialize the FDT to an XML string.

Definition at line 371 of file FileDeliveryTable.cpp.

                                                             {
  tinyxml2::XMLDocument doc;
  doc.InsertFirstChild( doc.NewDeclaration() );
  auto root = doc.NewElement("FDT-Instance");
  switch (_fdt_namespace) {
    case FDT_NS_RFC3926:
      // RFC 3926 Section 3.4.2
      root->SetAttribute("xmlns", "http://www.example.com/flute");
      break;
    case FDT_NS_DRAFT_2005:
      // 3GPP TS 26.346 Clause 7.2.10.1
      root->SetAttribute("xmlns", "urn:IETF:metadata:2005:FLUTE:FDT");
      break;
//    case FDT_NS_RFC6726:  // FLUTE v2 - Will need other things implementing to use this
//      // RFC 6726
//      root->SetAttribute("xmlns", "urn:ietf:params:xml:ns:fdt");
//      break;
    case FDT_NS_3GPP_CONSOLIDATED_V2:
      // 3GPP TS 26.346 Clause L.6.1
      root->SetAttribute("xmlns", "urn:3GPP:metadata:2022:FLUTE:FDT");
      break;
    default:
      break;
  }
  root->SetAttribute("Expires", std::to_string(_expires).c_str());
  root->SetAttribute("FEC-OTI-FEC-Encoding-ID", (unsigned)_global_fec_oti.encoding_id);
  if (_global_fec_oti.instance_id) root->SetAttribute("FEC-OTI-FEC-Instance-ID", (unsigned)_global_fec_oti.instance_id);
  root->SetAttribute("FEC-OTI-Maximum-Source-Block-Length", (unsigned)_global_fec_oti.max_source_block_length);
  root->SetAttribute("FEC-OTI-Encoding-Symbol-Length", (unsigned)_global_fec_oti.encoding_symbol_length);
  root->SetAttribute("xmlns:mbms2007", "urn:3GPP:metadata:2007:MBMS:FLUTE:FDT"); // 3GPP TS 26.346 Clause 7.2.10.2
  root->SetAttribute("xmlns:mbms2012", "urn:3GPP:metadata:2012:MBMS:FLUTE:FDT"); // 3GPP TS 26.346 Clause 7.2.10.2
  doc.InsertEndChild(root);
 
  for (const auto& file : _file_entries) {
    auto f = doc.NewElement("File");
    f->SetAttribute("TOI", file.toi);
    f->SetAttribute("Content-Location", file.content_location.c_str());
    f->SetAttribute("Content-Length", file.content_length);
    if (file.fec_oti.transfer_length) f->SetAttribute("Transfer-Length", file.fec_oti.transfer_length);
    if (!file.content_md5.empty()) f->SetAttribute("Content-MD5", file.content_md5.c_str());
    if (!file.content_encoding.empty()) f->SetAttribute("Content-Encoding", file.content_encoding.c_str());
    if (!file.content_type.empty()) f->SetAttribute("Content-Type", file.content_type.c_str());
    if (file.fec_oti.encoding_id != _global_fec_oti.encoding_id)
      f->SetAttribute("FEC-OTI-FEC-Encoding-ID", (unsigned)file.fec_oti.encoding_id);
    if (file.fec_oti.instance_id != 0 && file.fec_oti.instance_id != _global_fec_oti.instance_id)
      f->SetAttribute("FEC-OTI-FEC-Instance-ID", (unsigned)file.fec_oti.instance_id);
    if (file.fec_oti.max_source_block_length != 0 &&
        file.fec_oti.max_source_block_length != _global_fec_oti.max_source_block_length)
      f->SetAttribute("FEC-OTI-Maximum-Source-Block-Length", (unsigned)file.fec_oti.max_source_block_length);
    if (file.fec_oti.encoding_symbol_length != 0 &&
        file.fec_oti.encoding_symbol_length != _global_fec_oti.encoding_symbol_length)
      f->SetAttribute("FEC-OTI-Encoding-Symbol-Length", (unsigned)file.fec_oti.encoding_symbol_length);
    if (!file.etag.empty()) f->SetAttribute("mbms2012:File-ETag", file.etag.c_str());
    if (file.cache_control.no_cache || file.cache_control.cache_expires) {
      auto cc = doc.NewElement("mbms2007:Cache-Control");
      if (file.cache_control.no_cache) {
        auto noc = doc.NewElement("mbms2007:no-cache");
        noc->SetText("true");
        cc->InsertEndChild(noc);
      } else {
        auto exp = doc.NewElement("mbms2007:Expires");
        exp->SetText(std::to_string(file.expires).c_str());
        cc->InsertEndChild(exp);
      }
      f->InsertEndChild(cc);
    }
    root->InsertEndChild(f);
  }
 
 
  tinyxml2::XMLPrinter printer;
  doc.Print(&printer);
  return std::string(printer.CStr());
}

---

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

• include/FileDeliveryTable.h
• src/FileDeliveryTable.cpp