TSDuck Version 3.15-964 (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 {
  UNSPECIFIED,
  BINARY,
  XML
}
 Section file formats. More...
 

Public Member Functions

 SectionFile ()
 Default constructor.
 
virtual ~SectionFile ()
 Destructor.
 
void add (const BinaryTablePtr &table)
 Add a table in the file. More...
 
void add (const BinaryTablePtrVector &tables)
 Add several tables in the file. More...
 
void add (const AbstractTablePtr &table, const DVBCharset *charset=0)
 Add a table 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...
 
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, Report &report=(*ts::CerrReport::Instance()), FileType type=UNSPECIFIED, CRC32::Validation crc_op=CRC32::IGNORE, const DVBCharset *charset=0)
 Load a binary or XML file. More...
 
bool load (std::istream &strm, Report &report=(*ts::CerrReport::Instance()), FileType type=UNSPECIFIED, CRC32::Validation crc_op=CRC32::IGNORE, const DVBCharset *charset=0)
 Load a binary or XML file. More...
 
bool loadBinary (std::istream &strm, Report &report=(*ts::CerrReport::Instance()), CRC32::Validation crc_op=CRC32::IGNORE)
 Load a binary section file from a stream. More...
 
bool loadBinary (const UString &file_name, Report &report=(*ts::CerrReport::Instance()), CRC32::Validation crc_op=CRC32::IGNORE)
 Load a binary section file. More...
 
bool loadXML (const UString &file_name, Report &report=(*ts::CerrReport::Instance()), const DVBCharset *charset=0)
 Load an XML file. More...
 
bool loadXML (std::istream &strm, Report &report=(*ts::CerrReport::Instance()), const DVBCharset *charset=0)
 Load an XML file. More...
 
const SectionPtrVectororphanSections () const
 Fast access to the list of orphan sections, sections which are not part of a table. More...
 
bool parseXML (const UString &xml_content, Report &report=(*ts::CerrReport::Instance()), const DVBCharset *charset=0)
 Parse an XML content. More...
 
bool saveBinary (std::ostream &strm, Report &report=(*ts::CerrReport::Instance())) const
 Save a binary section file. More...
 
bool saveBinary (const UString &file_name, Report &report=(*ts::CerrReport::Instance())) const
 Save a binary section file. More...
 
bool saveXML (const UString &file_name, Report &report=(*ts::CerrReport::Instance()), const DVBCharset *charset=0) const
 Save an XML file. More...
 
const SectionPtrVectorsections () const
 Fast access to the list of loaded sections. More...
 
const BinaryTablePtrVectortables () const
 Fast access to the list of loaded tables. More...
 
UString toXML (Report &report=(*ts::CerrReport::Instance()), const DVBCharset *charset=0) 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=UNSPECIFIED)
 Get a file type, based on a file name. More...
 

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

Member Function Documentation

◆ GetFileType()

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

Get a file type, based on a file name.

Parameters
[in]file_nameFile name.
[in]typeFile type.
Returns
If type is not UNSPECIFIED, return type. Otherwise, return the file type based on the file name. If the file name has no known extension, return 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 UNSPECIFIED, remove the extension from file_name and add the extension corresponding to type.

◆ load() [1/2]

bool ts::SectionFile::load ( const UString file_name,
Report report = (*ts::CerrReport::Instance()),
FileType  type = UNSPECIFIED,
CRC32::Validation  crc_op = CRC32::IGNORE,
const DVBCharset charset = 0 
)

Load a binary or XML file.

Parameters
[in]file_nameXML file name.
[in,out]reportWhere to report errors.
[in]typeFile type. If UNSPECIFIED, the file type is based on the file name.
[in]crc_opFor binary files, how to process the CRC32 of the input sections.
[in]charsetFor XML files, if not zero, default character set to encode strings.
Returns
True on success, false on error.

◆ load() [2/2]

bool ts::SectionFile::load ( std::istream &  strm,
Report report = (*ts::CerrReport::Instance()),
FileType  type = UNSPECIFIED,
CRC32::Validation  crc_op = CRC32::IGNORE,
const DVBCharset charset = 0 
)

Load a binary or XML file.

Parameters
[in,out]strmA standard stream in input mode (binary mode for binary files).
[in,out]reportWhere to report errors.
[in]typeFile type. If UNSPECIFIED, return an error.
[in]crc_opFor binary files, how to process the CRC32 of the input sections.
[in]charsetFor XML files, if not zero, default character set to encode strings.
Returns
True on success, false on error.

◆ loadXML() [1/2]

bool ts::SectionFile::loadXML ( const UString file_name,
Report report = (*ts::CerrReport::Instance()),
const DVBCharset charset = 0 
)

Load an XML file.

Parameters
[in]file_nameXML file name.
[in,out]reportWhere to report errors.
[in]charsetIf not zero, default character set to encode strings.
Returns
True on success, false on error.

◆ loadXML() [2/2]

bool ts::SectionFile::loadXML ( std::istream &  strm,
Report report = (*ts::CerrReport::Instance()),
const DVBCharset charset = 0 
)

Load an XML file.

Parameters
[in,out]strmA standard text stream in input mode.
[in,out]reportWhere to report errors.
[in]charsetIf not zero, default character set to encode strings.
Returns
True on success, false on error.

◆ parseXML()

bool ts::SectionFile::parseXML ( const UString xml_content,
Report report = (*ts::CerrReport::Instance()),
const DVBCharset charset = 0 
)

Parse an XML content.

Parameters
[in]xml_contentXML file content in UTF-8.
[in,out]reportWhere to report errors.
[in]charsetIf not zero, default character set to encode strings.
Returns
True on success, false on error.

◆ saveXML()

bool ts::SectionFile::saveXML ( const UString file_name,
Report report = (*ts::CerrReport::Instance()),
const DVBCharset charset = 0 
) const

Save an XML file.

Parameters
[in]file_nameXML file name.
[in,out]reportWhere to report errors.
[in]charsetIf not zero, character set to use without explicit table code.
Returns
True on success, false on error.

◆ toXML()

UString ts::SectionFile::toXML ( Report report = (*ts::CerrReport::Instance()),
const DVBCharset charset = 0 
) const

Serialize as XML text.

Parameters
[in,out]reportWhere to report errors.
[in]charsetIf not zero, character set to use without explicit table code.
Returns
Complete XML document text, empty on error.

◆ loadBinary() [1/2]

bool ts::SectionFile::loadBinary ( std::istream &  strm,
Report report = (*ts::CerrReport::Instance()),
CRC32::Validation  crc_op = CRC32::IGNORE 
)

Load a binary section file from a stream.

Parameters
[in,out]strmA standard stream in input mode (binary mode).
[in]crc_opHow to process the CRC32 of the input packet.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ loadBinary() [2/2]

bool ts::SectionFile::loadBinary ( const UString file_name,
Report report = (*ts::CerrReport::Instance()),
CRC32::Validation  crc_op = CRC32::IGNORE 
)

Load a binary section file.

Parameters
[in]file_nameBinary file name.
[in]crc_opHow to process the CRC32 of the input packet.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ saveBinary() [1/2]

bool ts::SectionFile::saveBinary ( std::ostream &  strm,
Report report = (*ts::CerrReport::Instance()) 
) const

Save a binary section file.

Parameters
[in,out]strmA standard stream in output mode (binary mode).
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ saveBinary() [2/2]

bool ts::SectionFile::saveBinary ( const UString file_name,
Report report = (*ts::CerrReport::Instance()) 
) const

Save a binary section file.

Parameters
[in]file_nameBinary file name.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ 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 table in the file.

Parameters
[in]tableThe binary table to add.

◆ add() [2/5]

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

Add several tables in the file.

Parameters
[in]tablesThe binary tables to add.

◆ add() [3/5]

void ts::SectionFile::add ( const AbstractTablePtr table,
const DVBCharset charset = 0 
)

Add a table in the file.

The table is serialized

Parameters
[in]tableThe table to add.
[in]charsetIf not zero, default character set to encode strings.

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

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