A binary or XML file containing PSI/SI sections and tables. More...

#include <tsSectionFile.h>

Public Types
enum class	FileType { UNSPECIFIED , BINARY , XML , JSON }
	Section file formats. More...

Public Member Functions
	SectionFile (DuckContext &duck)
	Constructor.

void	add (const AbstractTablePtr &table)
	Add a typed table in the file.

void	add (const BinaryTablePtr &table)
	Add a binary table in the file.

void	add (const BinaryTablePtrVector &tables)
	Add several binary tables in the file.

void	add (const SectionPtr &section)
	Add a section in the file.

void	add (const SectionPtrVector &sections)
	Add several sections in the file.

size_t	binarySize () const
	Get the size in bytes of all sections.

void	clear ()
	Clear the list of loaded tables and sections.

void	getOrphanSections (SectionPtrVector &sections) const
	Get a copy of the list of orphan sections.

void	getSections (SectionPtrVector &sections) const
	Get a copy of the list of loaded sections.

void	getTables (BinaryTablePtrVector &tables) const
	Get a copy of the list of loaded tables.

bool	load (const UString &file_name, FileType type=FileType::UNSPECIFIED)
	Load a binary or XML file.

bool	load (std::istream &strm, FileType type=FileType::UNSPECIFIED)
	Load a binary or XML file.

bool	loadBinary (const fs::path &file_name)
	Load a binary section file.

bool	loadBinary (std::istream &strm)
	Load a binary section file from a stream.

bool	loadBuffer (const ByteBlock &data, size_t start=0, size_t count=NPOS)
	Load a binary section file from a memory buffer.

bool	loadBuffer (const void *data, size_t size)
	Load a binary section file from a memory buffer.

bool	loadJSON (const UString &file_name)
	Load a JSON file.

bool	loadJSON (std::istream &strm)
	Load a JSON file from an open text stream.

bool	loadXML (const UString &file_name)
	Load an XML file.

bool	loadXML (std::istream &strm)
	Load an XML file from an open text stream.

const SectionPtrVector &	orphanSections () const
	Fast access to the list of orphan sections, sections which are not part of a table.

size_t	packOrphanSections ()
	Pack all orphan sections.

bool	parseJSON (const UString &json_content)
	Parse a JSON content.

bool	parseXML (const UString &xml_content)
	Parse an XML content.

void	reorganizeEITs (const Time &reftime=Time(), EITOptions options=EITOptions::GEN_ALL)
	Reorganize all EIT sections according to ETSI TS 101 211.

bool	saveBinary (const fs::path &file_name) const
	Save a binary section file.

bool	saveBinary (std::ostream &strm) const
	Save a binary section file.

size_t	saveBuffer (ByteBlock &buffer) const
	Save the section file into a memory buffer.

size_t	saveBuffer (void *buffer, size_t buffer_size) const
	Save the section file into a memory buffer.

bool	saveJSON (const UString &file_name)
	Save a JSON file after automated XML-to-JSON conversion.

bool	saveXML (const UString &file_name) const
	Save an XML file.

const SectionPtrVector &	sections () const
	Fast access to the list of loaded sections.

size_t	sectionsCount () const
	Get the total number of sections in the file.

void	setCRCValidation (CRC32::Validation crc_op)
	Set the CRC32 processing mode when loading binary sections.

void	setTweaks (const xml::Tweaks &tweaks)
	Set new parsing and formatting tweaks for XML files.

const BinaryTablePtrVector &	tables () const
	Fast access to the list of loaded tables.

size_t	tablesCount () const
	Get the total number of full tables in the file.

UString	toJSON ()
	Serialize as JSON text.

UString	toXML () const
	Serialize as XML text.

Static Public Member Functions
static fs::path	BuildFileName (const fs::path &file_name, FileType type)
	Build a file name, based on a file type.

static FileType	GetFileType (const UString &file_name, FileType type=FileType::UNSPECIFIED)
	Get a file type, based on a file name.

static bool	LoadModel (xml::Document &doc, bool load_extensions=true)
	This static method loads the XML model for tables and descriptors.

Static Public Attributes
static constexpr const UChar *const	DEFAULT_BINARY_SECTION_FILE_SUFFIX = u".bin"
	Default file name suffix for binary section files.

static constexpr const UChar *const	DEFAULT_JSON_SECTION_FILE_SUFFIX = u".json"
	Default file name suffix for JSON section files.

static constexpr const UChar *const	DEFAULT_XML_SECTION_FILE_SUFFIX = u".xml"
	Default file name suffix for XML section files.

static constexpr const UChar *const	XML_TABLES_MODEL = u"tsduck.tables.model.xml"
	File name of the XML model file for tables.

Detailed Description

A binary or XML file containing PSI/SI sections and tables.

A section file contains one or more sections. Short sections are also tables. Long sections need to be grouped to form a table. When a section file contains only complete valid tables, we also call it a table file.

When a section file is loaded, the application can indifferently access:

All sections in the file.
All complete tables in the file.
Sections which do not belong to a table (orphan sections).

There are currently two storage formats for section files: binary and XML. By default, file names ending in .bin are considered as binary files while names ending in .xml are considered as XML files. To manipulate other file formats, the application must specify the file type.

Binary section file format

A binary section file is simply the concatenation of complete sections, header and payload, without any encapsulation. Sections must be read from the beginning of the file. The length field in the section header shall be used to locate the next section, immediately after the current section.

Short sections are read and recognized as complete tables on their own. To get a valid table with long sections, all sections forming this table must be stored contiguously in the order of their section number.

XML section file format

The format of XML section files is documented in the TSDuck user's guide. An informal template is given in file tsduck.tables.model.xml. This file is used to validate the content of XML section files.

Sample XML section file:

<?xml version="1.0" encoding="UTF-8"?>
<tsduck>
  <PAT version="8" current="true" transport_stream_id="0x0012" network_PID="0x0010">
    <service service_id="0x0001" program_map_PID="0x1234"/>
    <service service_id="0x0002" program_map_PID="0x0678"/>
  </PAT>
</tsduck>

Each XML node describes a complete table. As a consequence, an XML section file contains complete tables only. There is no orphan section.

Member Enumeration Documentation

◆ FileType

enum class ts::SectionFile::FileType

strong

Section file formats.

Enumerator
UNSPECIFIED	Unspecified, depends on file name extension.
BINARY	Binary section file.
XML	XML section file.
JSON	JSON (translated XML) section file.

Constructor & Destructor Documentation

◆ SectionFile()

ts::SectionFile::SectionFile ( DuckContext & duck )

Constructor.

Parameters

[in,out] duck TSDuck execution context. The reference is kept inside the demux.

Member Function Documentation

◆ binarySize()

size_t ts::SectionFile::binarySize ( ) const

Get the size in bytes of all sections.

This would be the size of the corresponding binary file.

Returns: The size in bytes of all sections.

◆ sectionsCount()

size_t ts::SectionFile::sectionsCount ( ) const

inline

Get the total number of sections in the file.

Returns: The total number of sections in the file.

◆ tablesCount()

size_t ts::SectionFile::tablesCount ( ) const

inline

Get the total number of full tables in the file.

Orphan sections are not included.

Returns: The total number of full tables in the file.

◆ GetFileType()

static FileType ts::SectionFile::GetFileType	(	const UString &	file_name,
		FileType	type = `FileType::UNSPECIFIED`
	)

static

Get a file type, based on a file name.

Parameters

[in]	file_name	File name or inline XML or inline JSON.
[in]	type	File type.

Returns: If type is not FileType::UNSPECIFIED, return type. Otherwise, return the file type based on the file name. If the file name has no known extension, return FileType::UNSPECIFIED.

◆ BuildFileName()

static fs::path ts::SectionFile::BuildFileName	(	const fs::path &	file_name,
		FileType	type
	)

static

Build a file name, based on a file type.

Parameters

[in]	file_name	File name.
[in]	type	File type.

Returns: If type is not FileType::UNSPECIFIED, remove the extension from file_name and add the extension corresponding to type.

◆ setTweaks()

void ts::SectionFile::setTweaks ( const xml::Tweaks & tweaks )

inline

Set new parsing and formatting tweaks for XML files.

Parameters

[in] tweaks XML tweaks.

◆ setCRCValidation()

void ts::SectionFile::setCRCValidation ( CRC32::Validation crc_op )

inline

Set the CRC32 processing mode when loading binary sections.

Parameters

[in] crc_op For binary files, how to process the CRC32 of the input sections.

◆ load() [1/2]

bool ts::SectionFile::load	(	const UString &	file_name,
		FileType	type = `FileType::UNSPECIFIED`
	)

Load a binary or XML file.

The loaded sections are added to the content of this object.

Parameters

[in]	file_name	XML file name. If the file name starts with "<?xml", this is considered as "inline XML content". If the file name is empty or "-", the standard input is used.
[in]	type	File type. If UNSPECIFIED, the file type is based on the file name.

Returns: True on success, false on error.

◆ load() [2/2]

bool ts::SectionFile::load	(	std::istream &	strm,
		FileType	type = `FileType::UNSPECIFIED`
	)

Load a binary or XML file.

The loaded sections are added to the content of this object.

Parameters

[in,out]	strm	A standard stream in input mode (binary mode for binary files).
[in]	type	File type. If UNSPECIFIED, return an error.

Returns: True on success, false on error.

◆ loadXML() [1/2]

bool ts::SectionFile::loadXML ( const UString & file_name )

Load an XML file.

The loaded tables are added to the content of this object.

Parameters

[in] file_name XML file name. If the file name starts with "<?xml", this is considered as "inline XML content". If the file name is empty or "-", the standard input is used.

Returns: True on success, false on error.

◆ loadXML() [2/2]

bool ts::SectionFile::loadXML ( std::istream & strm )

Load an XML file from an open text stream.

The loaded sections are added to the content of this object.

Parameters

[in,out] strm A standard text stream in input mode.

Returns: True on success, false on error.

◆ parseXML()

bool ts::SectionFile::parseXML ( const UString & xml_content )

Parse an XML content.

The parsed tables are added to the content of this object.

Parameters

[in] xml_content XML file content in UTF-8.

Returns: True on success, false on error.

◆ loadJSON() [1/2]

bool ts::SectionFile::loadJSON ( const UString & file_name )

Load a JSON file.

The JSON must have the format of a previous automated XML-to-JSON conversion. The loaded tables are added to the content of this object.

Parameters

[in] file_name JSON file name. If the file name starts with "{" or "[", this is considered as "inline JSON content". If the file name is empty or "-", the standard input is used.

Returns: True on success, false on error.

◆ loadJSON() [2/2]

bool ts::SectionFile::loadJSON ( std::istream & strm )

Load a JSON file from an open text stream.

The JSON must have the format of a previous automated XML-to-JSON conversion. The loaded sections are added to the content of this object.

Parameters

[in,out] strm A standard text stream in input mode.

Returns: True on success, false on error.

◆ parseJSON()

bool ts::SectionFile::parseJSON ( const UString & json_content )

Parse a JSON content.

The JSON must have the format of a previous automated XML-to-JSON conversion. The parsed tables are added to the content of this object.

Parameters

[in] json_content JSON file content in UTF-8.

Returns: True on success, false on error.

◆ saveXML()

bool ts::SectionFile::saveXML ( const UString & file_name ) const

Save an XML file.

Parameters

[in] file_name XML file name. If the file name is empty or "-", the standard output is used.

Returns: True on success, false on error.

◆ saveJSON()

bool ts::SectionFile::saveJSON ( const UString & file_name )

Save a JSON file after automated XML-to-JSON conversion.

Parameters

[in] file_name JSON file name. If the file name is empty or "-", the standard output is used.

Returns: True on success, false on error.

◆ toXML()

UString ts::SectionFile::toXML ( ) const

Serialize as XML text.

Returns: Complete XML document text, empty on error.

◆ toJSON()

UString ts::SectionFile::toJSON ( )

Serialize as JSON text.

Returns: Complete JSON document text, empty on error.

◆ loadBinary() [1/2]

bool ts::SectionFile::loadBinary ( std::istream & strm )

inline

Load a binary section file from a stream.

The loaded sections are added to the content of this object.

Parameters

[in,out] strm A standard stream in input mode (binary mode).

Returns: True on success, false on error.

◆ loadBinary() [2/2]

bool ts::SectionFile::loadBinary ( const fs::path & file_name )

Load a binary section file.

The loaded sections are added to the content of this object.

Parameters

[in] file_name Binary file name. If the file name is empty or "-", the standard input is used.

Returns: True on success, false on error.

◆ saveBinary() [1/2]

bool ts::SectionFile::saveBinary ( std::ostream & strm ) const

inline

Save a binary section file.

Parameters

[in,out] strm A standard stream in output mode (binary mode).

Returns: True on success, false on error.

◆ saveBinary() [2/2]

bool ts::SectionFile::saveBinary ( const fs::path & file_name ) const

Save a binary section file.

Parameters

[in] file_name Binary file name. If the file name is empty or "-", the standard output is used.

Returns: True on success, false on error.

◆ loadBuffer() [1/2]

bool ts::SectionFile::loadBuffer	(	const void *	data,
		size_t	size
	)

Load a binary section file from a memory buffer.

The loaded sections are added to the content of this object.

Parameters

[in]	data	Address of the memory buffer.
[in]	size	Size in bytes of the memory buffer.

Returns: True on success, false if some sections were incorrect or truncated.

◆ loadBuffer() [2/2]

bool ts::SectionFile::loadBuffer	(	const ByteBlock &	data,
		size_t	start = `0`,
		size_t	count = `NPOS`
	)

Load a binary section file from a memory buffer.

The loaded sections are added to the content of this object.

Parameters

[in]	data	Byte block containing the binary data.
[in]	start	Starting index inside the byte buffer.
[in]	count	Size in bytes to read after start. If set to NPOS, use the rest of the buffer.

Returns: True on success, false if some sections were incorrect or truncated.

◆ saveBuffer() [1/2]

size_t ts::SectionFile::saveBuffer	(	void *	buffer,
		size_t	buffer_size
	)		const

Save the section file into a memory buffer.

Parameters

[out]	buffer	Address of the memory buffer to write.
[in]	buffer_size	Size in bytes of the memory buffer.

Returns: The written size in bytes. If the buffer is too short, no section is truncated. The returned size includes complete sections only. Use binarySize() to get the required total size.

◆ saveBuffer() [2/2]

size_t ts::SectionFile::saveBuffer ( ByteBlock & buffer ) const

Save the section file into a memory buffer.

Parameters

[in,out] buffer A byte block into which the sections are written. The sections are appended to the existing content of buffer.

Returns: The number of bytes which were appended to the buffer.

◆ tables()

const BinaryTablePtrVector & ts::SectionFile::tables ( ) const

inline

Fast access to the list of loaded tables.

Returns: A constant reference to the internal list of loaded tables.

◆ sections()

const SectionPtrVector & ts::SectionFile::sections ( ) const

inline

Fast access to the list of loaded sections.

Returns: A constant reference to the internal list of loaded sections.

◆ orphanSections()

const SectionPtrVector & ts::SectionFile::orphanSections ( ) const

inline

Fast access to the list of orphan sections, sections which are not part of a table.

Returns: A constant reference to the internal list of orphan sections.

◆ getTables()

void ts::SectionFile::getTables ( BinaryTablePtrVector & tables ) const

inline

Get a copy of the list of loaded tables.

Parameters

[out] tables The list of loaded tables.

◆ getSections()

void ts::SectionFile::getSections ( SectionPtrVector & sections ) const

inline

Get a copy of the list of loaded sections.

Parameters

[out] sections The list of loaded sections.

◆ getOrphanSections()

void ts::SectionFile::getOrphanSections ( SectionPtrVector & sections ) const

inline

Get a copy of the list of orphan sections.

Parameters

[out] sections The list of orphan sections.

◆ add() [1/5]

void ts::SectionFile::add ( const BinaryTablePtr & table )

Add a binary table in the file.

If the table is not complete (there are missing sections), the sections which are present are individually added.

Parameters

[in] table The binary table to add.

◆ add() [2/5]

void ts::SectionFile::add ( const BinaryTablePtrVector & tables )

Add several binary tables in the file.

If a table is not complete (there are missing sections), the sections which are present are individually added.

Parameters

[in] tables The binary tables to add.

◆ add() [3/5]

void ts::SectionFile::add ( const AbstractTablePtr & table )

Add a typed table in the file.

The table is serialized first. Then its sections are added in the file.

Parameters

[in] table The table to add.

◆ add() [4/5]

void ts::SectionFile::add ( const SectionPtr & section )

Add a section in the file.

Parameters

[in] section The binary section to add.

◆ add() [5/5]

void ts::SectionFile::add ( const SectionPtrVector & sections )

Add several sections in the file.

Parameters

[in] sections The binary sections to add.

◆ packOrphanSections()

size_t ts::SectionFile::packOrphanSections ( )

Pack all orphan sections.

Consecutive sections from the same tables are packed: the sections are renumbered starting at zero. The result is a complete but potentially invalid section.

Returns: The number of tables which were created.

◆ reorganizeEITs()

void ts::SectionFile::reorganizeEITs	(	const Time &	reftime = `Time()`,
		EITOptions	options = `EITOptions::GEN_ALL`
	)

Reorganize all EIT sections according to ETSI TS 101 211.

Only one EITp/f subtable is kept per service. It is split in two sections if two events (present and following) are specified. All EIT schedule are kept. But they are completely reorganized. All events are extracted and spread over new EIT sections according to ETSI TS 101 211 rules.

Parameters

[in]	reftime	Reference time for EIT schedule. Only the date part is used. This is the "last midnight" according to which EIT segments are assigned. By default, the oldest event start time is used.
[in]	options	Generation options for EIT (p/f and/or schedule, actual and/or other).

See also: ts::EIT::ReorganizeSections(); ETSI TS 101 211, section 4.1.4

◆ LoadModel()

static bool ts::SectionFile::LoadModel	(	xml::Document &	doc,
		bool	load_extensions = `true`
	)

static

This static method loads the XML model for tables and descriptors.

It loads the main model and merges all extensions.

Parameters

[out]	doc	XML document which receives the model.
[out]	load_extensions	If true (the default), load model additions from all declared TSDuck extensions.

Returns: True on success, false on error.

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

tsSectionFile.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Binary section file format

XML section file format

Member Enumeration Documentation

◆ FileType

Constructor & Destructor Documentation

◆ SectionFile()

Member Function Documentation

◆ binarySize()

◆ sectionsCount()

◆ tablesCount()

◆ GetFileType()

◆ BuildFileName()

◆ setTweaks()

◆ setCRCValidation()

◆ load() [1/2]

◆ load() [2/2]

◆ loadXML() [1/2]

◆ loadXML() [2/2]

◆ parseXML()

◆ loadJSON() [1/2]

◆ loadJSON() [2/2]

◆ parseJSON()

◆ saveXML()

◆ saveJSON()

◆ toXML()

◆ toJSON()

◆ loadBinary() [1/2]

◆ loadBinary() [2/2]

◆ saveBinary() [1/2]

◆ saveBinary() [2/2]

◆ loadBuffer() [1/2]

◆ loadBuffer() [2/2]

◆ saveBuffer() [1/2]

◆ saveBuffer() [2/2]

◆ tables()

◆ sections()

◆ orphanSections()

◆ getTables()

◆ getSections()

◆ getOrphanSections()

◆ add() [1/5]

◆ add() [2/5]

◆ add() [3/5]

◆ add() [4/5]

◆ add() [5/5]

◆ packOrphanSections()

◆ reorganizeEITs()

◆ LoadModel()