TSDuck Version 3.29-2562 (TSDuck - The MPEG Transport Stream Toolkit)
ts::SectionFile Class Reference

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

Public Types

enum  FileType {
  FileType::UNSPECIFIED,
  FileType::BINARY,
  FileType::XML,
  FileType::JSON
}
 Section file formats. More...
 

Public Member Functions

 SectionFile (DuckContext &duck)
 Constructor. More...
 
void add (const AbstractTablePtr &table)
 Add a typed table in the file. More...
 
void add (const BinaryTablePtr &table)
 Add a binary table in the file. More...
 
void add (const BinaryTablePtrVector &tables)
 Add several binary tables in the file. More...
 
void add (const SectionPtr &section)
 Add a section in the file. More...
 
void add (const SectionPtrVector &sections)
 Add several sections in the file. More...
 
size_t binarySize () const
 Get the size in bytes of all sections. More...
 
void clear ()
 Clear the list of loaded tables and sections.
 
void getOrphanSections (SectionPtrVector &sections) const
 Get a copy of the list of orphan sections. More...
 
void getSections (SectionPtrVector &sections) const
 Get a copy of the list of loaded sections. More...
 
void getTables (BinaryTablePtrVector &tables) const
 Get a copy of the list of loaded tables. More...
 
bool load (const UString &file_name, FileType type=FileType::UNSPECIFIED)
 Load a binary or XML file. More...
 
bool load (std::istream &strm, FileType type=FileType::UNSPECIFIED)
 Load a binary or XML file. More...
 
bool loadBinary (const UString &file_name)
 Load a binary section file. More...
 
bool loadBinary (std::istream &strm)
 Load a binary section file from a stream. More...
 
bool loadBuffer (const ByteBlock &data, size_t start=0, size_t count=NPOS)
 Load a binary section file from a memory buffer. More...
 
bool loadBuffer (const void *data, size_t size)
 Load a binary section file from a memory buffer. More...
 
bool loadJSON (const UString &file_name)
 Load a JSON file. More...
 
bool loadJSON (std::istream &strm)
 Load a JSON file from an open text stream. More...
 
bool loadXML (const UString &file_name)
 Load an XML file. More...
 
bool loadXML (std::istream &strm)
 Load an XML file from an open text stream. More...
 
const SectionPtrVectororphanSections () const
 Fast access to the list of orphan sections, sections which are not part of a table. More...
 
size_t packOrphanSections ()
 Pack all orphan sections. More...
 
bool parseJSON (const UString &json_content)
 Parse a JSON content. More...
 
bool parseXML (const UString &xml_content)
 Parse an XML content. More...
 
void reorganizeEITs (const Time &reftime=Time())
 Reorganize all EIT sections according to ETSI TS 101 211. More...
 
bool saveBinary (const UString &file_name) const
 Save a binary section file. More...
 
bool saveBinary (std::ostream &strm) const
 Save a binary section file. More...
 
size_t saveBuffer (ByteBlock &buffer) const
 Save the section file into a memory buffer. More...
 
size_t saveBuffer (void *buffer, size_t buffer_size) const
 Save the section file into a memory buffer. More...
 
bool saveJSON (const UString &file_name)
 Save a JSON file after automated XML-to-JSON conversion. More...
 
bool saveXML (const UString &file_name) const
 Save an XML file. More...
 
const SectionPtrVectorsections () const
 Fast access to the list of loaded sections. More...
 
size_t sectionsCount () const
 Get the total number of sections in the file. More...
 
void setCRCValidation (CRC32::Validation crc_op)
 Set the CRC32 processing mode when loading binary sections. More...
 
void setTweaks (const xml::Tweaks &tweaks)
 Set new parsing and formatting tweaks for XML files. More...
 
const BinaryTablePtrVectortables () const
 Fast access to the list of loaded tables. More...
 
size_t tablesCount () const
 Get the total number of full tables in the file. More...
 
UString toJSON ()
 Serialize as JSON text. More...
 
UString toXML () const
 Serialize as XML text. More...
 

Static Public Member Functions

static UString BuildFileName (const UString &file_name, FileType type)
 Build a file name, based on a file type. More...
 
static FileType GetFileType (const UString &file_name, FileType type=FileType::UNSPECIFIED)
 Get a file type, based on a file name. More...
 
static bool LoadModel (xml::Document &doc, bool load_extensions=true)
 This static method loads the XML model for tables and descriptors. More...
 

Static Public Attributes

static const UChar *const DEFAULT_BINARY_SECTION_FILE_SUFFIX
 Default file name suffix for binary section files.
 
static const UChar *const DEFAULT_JSON_SECTION_FILE_SUFFIX
 Default file name suffix for JSON section files.
 
static const UChar *const DEFAULT_XML_SECTION_FILE_SUFFIX
 Default file name suffix for XML section files.
 
static const UChar *const XML_TABLES_MODEL
 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

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]duckTSDuck 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_nameFile name.
[in]typeFile 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 UString ts::SectionFile::BuildFileName ( const UString file_name,
FileType  type 
)
static

Build a file name, based on a file type.

Parameters
[in]file_nameFile name.
[in]typeFile 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]tweaksXML tweaks.

◆ setCRCValidation()

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

Set the CRC32 processing mode when loading binary sections.

Parameters
[in]crc_opFor 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_nameXML 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]typeFile 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]strmA standard stream in input mode (binary mode for binary files).
[in]typeFile 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_nameXML 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]strmA 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_contentXML 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_nameJSON 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]strmA 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_contentJSON 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_nameXML 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_nameJSON 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]strmA standard stream in input mode (binary mode).
Returns
True on success, false on error.

◆ loadBinary() [2/2]

bool ts::SectionFile::loadBinary ( const UString file_name)

Load a binary section file.

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

Parameters
[in]file_nameBinary 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]strmA standard stream in output mode (binary mode).
Returns
True on success, false on error.

◆ saveBinary() [2/2]

bool ts::SectionFile::saveBinary ( const UString file_name) const

Save a binary section file.

Parameters
[in]file_nameBinary 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]dataAddress of the memory buffer.
[in]sizeSize 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]dataByte block containing the binary data.
[in]startStarting index inside the byte buffer.
[in]countSize 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]bufferAddress of the memory buffer to write.
[in]buffer_sizeSize 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]bufferA 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]tablesThe list of loaded tables.

◆ getSections()

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

Get a copy of the list of loaded sections.

Parameters
[out]sectionsThe list of loaded sections.

◆ getOrphanSections()

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

Get a copy of the list of orphan sections.

Parameters
[out]sectionsThe 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]tableThe 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]tablesThe 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]tableThe table to add.

◆ add() [4/5]

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

Add a section in the file.

Parameters
[in]sectionThe binary section to add.

◆ add() [5/5]

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

Add several sections in the file.

Parameters
[in]sectionsThe 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())

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]reftimeReference 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.
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]docXML document which receives the model.
[out]load_extensionsIf 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:
tsduck.version
def version()
TSDuck version as a string.
Definition: tsduck.py:199