Representation of a ".names" file, containing names for identifiers. More...

#include <tsNamesFile.h>

Classes
class	RegisterExtensionFile
	A class to register additional names files to merge with the TSDuck names file. More...

class	Visitor
	A visitor interface class to be implemented by applications needing ranges of values. More...

Public Types
using	NamesFilePtr = std::shared_ptr< NamesFile >
	Shared pointer to a names file.

enum class	Predefined { DTV = 0 , IP = 1 , OUI = 2 , DEKTEC = 3 , HIDES = 4 , COUNT = 5 }
	Identifiers for some predefined TSDuck names files. More...

using	Value = uint64_t
	Largest integer type we manage in the repository of names.

Public Member Functions
	NamesFile (const UString &file_name, bool merge_extensions=false)
	Constructor.

UString	configurationFile () const
	Get the complete path of the configuration file from which the names were loaded.

size_t	errorCount () const
	Get the number of errors in the configuration file.

bool	mergeConfigurationFile (const UString &file_name)
	Load a configuration file and merge its content into this instance.

bool	mergeFile (const UString &file_name)
	Load a names file and merge its content into this instance.

bool	nameExists (const UString &section_name, Value value) const
	Check if a name exists in a specified section.

UString	nameFromSection (const UString &section_name, Value value, NamesFlags flags=NamesFlags::NAME, Value alternate_value=0, size_t bits=0) const
	Get a name from a specified section.

UString	nameFromSectionWithFallback (const UString &section_name, Value value1, Value value2, NamesFlags flags=NamesFlags::NAME, Value alternate_value=0, size_t bits=0) const
	Get a name from a specified section, with alternate fallback value.

void	subscribe (Visitor *visitor, const UString &section_name=UString())
	Subscribe to all new values which will be merged into the file.

void	unsubscribe (Visitor *visitor, const UString &section_name=UString())
	Unsubscribe from all new values which will be merged into the file.

size_t	visitSection (Visitor *visitor, const UString &section_name) const
	Get all values in a section.

size_t	visitSection (Visitor *visitor, const UString &section_name, Value value) const
	Get all extended values of a specified value in a section.

Static Public Member Functions
static void	DeleteInstance (Predefined index)
	Delete a common instance of NamesFile for a predefined configuration file.

static UString	Formatted (Value value, const UString &name, NamesFlags flags, size_t bits, Value alternate_value=0)
	Format a name using flags.

static NamesFilePtr	Instance (const UString &file_name, bool merge_extensions=false)
	Get a common instance of NamesFile for a given configuration file.

static NamesFilePtr	Instance (Predefined index)
	Get a common instance of NamesFile for a predefined configuration file.

static void	UnregisterExtensionFile (const UString &file_name)
	Unregister a previously registered extension.

Detailed Description

Representation of a ".names" file, containing names for identifiers.

In an instance of NamesFile, all names are loaded from one configuration file.

Member Enumeration Documentation

◆ Predefined

enum class ts::NamesFile::Predefined

strong

Identifiers for some predefined TSDuck names files.

Using an idenfier is faster than looking for a file name.

Enumerator
DTV	All Digital TV definitions (MPEG, DVB, ATSC, ISDB).
IP	Internet protocols definitions.
OUI	IEEE Organizationally Unique Identifiers.
DEKTEC	Dektec devices definitions.
HIDES	HiDes modulators definitions.
COUNT	Not a real value, just the number of values.

Constructor & Destructor Documentation

◆ NamesFile()

ts::NamesFile::NamesFile	(	const UString &	file_name,
		bool	merge_extensions = `false`
	)

Constructor.

Using this constructor directly is discouraged. Use Instance() instead.

Parameters

[in]	file_name	Configuration file name. Typically without directory name. Without directory, the file is automatically searched in the TSDuck configuration directory.
[in]	merge_extensions	If true, merge the content of names files from TSDuck extensions.

See also: Instance(const UString&, bool);; Instance(Predefined, bool);

Member Function Documentation

◆ mergeFile()

bool ts::NamesFile::mergeFile ( const UString & file_name )

Load a names file and merge its content into this instance.

Parameters

[in] file_name Configuration file name.

Returns: True on success, false on error.

◆ mergeConfigurationFile()

bool ts::NamesFile::mergeConfigurationFile ( const UString & file_name )

Load a configuration file and merge its content into this instance.

Parameters

[in] file_name Configuration file name. Typically without directory name. Without directory, the file is automatically searched in the TSDuck configuration directory.

Returns: True on success, false on error.

◆ Instance() [1/2]

static NamesFilePtr ts::NamesFile::Instance	(	const UString &	file_name,
		bool	merge_extensions = `false`
	)

inlinestatic

Get a common instance of NamesFile for a given configuration file.

The file is loaded once and the instance is created the first time. When the same file is requested again, the same instance is returned.

Parameters

[in]	file_name	Configuration file name without directory name. The file is searched in the TSDuck configuration directory.
[in]	merge_extensions	If true, merge the content of names files from TSDuck extensions when the file is loaded the first time.

Returns: A pointer to the NamesFile instance for that file. Never return a null pointer. In case of error (non existent file for instance), an empty instance is returned for that file.

◆ Instance() [2/2]

static NamesFilePtr ts::NamesFile::Instance ( Predefined index )

inlinestatic

Get a common instance of NamesFile for a predefined configuration file.

The file is loaded once and the instance is created the first time. When the same file is requested again, the same instance is returned.

Parameters

[in] index Identifier of the predefined file to get.

Returns: A pointer to the NamesFile instance for that file. Never return a null pointer. In case of error (non existent file for instance), an empty instance is returned for that file.

◆ DeleteInstance()

static void ts::NamesFile::DeleteInstance ( Predefined index )

inlinestatic

Delete a common instance of NamesFile for a predefined configuration file.

This should never be necessary unless TSDuck extensions are loaded on the fly. This never happens since extensions are registered in macro TS_REGISTER_NAMES_FILE. This is useful in test programs only.

Parameters

[in] index Identifier of the predefined file to get.

◆ configurationFile()

UString ts::NamesFile::configurationFile ( ) const

inline

Get the complete path of the configuration file from which the names were loaded.

Returns: The complete path of the configuration file. Empty if does not exist.

◆ errorCount()

size_t ts::NamesFile::errorCount ( ) const

Get the number of errors in the configuration file.

Returns: The number of errors in the configuration file.

◆ nameExists()

bool ts::NamesFile::nameExists	(	const UString &	section_name,
		Value	value
	)		const

Check if a name exists in a specified section.

Parameters

[in]	section_name	Name of section to search. Not case-sensitive.
[in]	value	Value to get the name for.

Returns: True if a name exists for value in section_name.

◆ nameFromSection()

UString ts::NamesFile::nameFromSection	(	const UString &	section_name,
		Value	value,
		NamesFlags	flags = `NamesFlags::NAME`,
		Value	alternate_value = `0`,
		size_t	bits = `0`
	)		const

Get a name from a specified section.

Parameters

[in]	section_name	Name of section to search. Not case-sensitive.
[in]	value	Value to get the name for.
[in]	flags	Presentation flags.
[in]	alternate_value	Display this integer value if flags ALTERNATE is set.
[in]	bits	Optional size in bits of the displayed data. Used in replacement of the "Bits=XX" directive in the .names file.

Returns: The corresponding name.

◆ nameFromSectionWithFallback()

UString ts::NamesFile::nameFromSectionWithFallback	(	const UString &	section_name,
		Value	value1,
		Value	value2,
		NamesFlags	flags = `NamesFlags::NAME`,
		Value	alternate_value = `0`,
		size_t	bits = `0`
	)		const

Get a name from a specified section, with alternate fallback value.

Parameters

[in]	section_name	Name of section to search. Not case-sensitive.
[in]	value1	Value to get the name for.
[in]	value2	Alternate value if no name is found for value1.
[in]	flags	Presentation flags.
[in]	alternate_value	Display this integer value if flags ALTERNATE is set.
[in]	bits	Optional size in bits of the displayed data. Used in replacement of the "Bits=XX" directive in the .names file.

Returns: The corresponding name.

◆ visitSection() [1/2]

size_t ts::NamesFile::visitSection	(	Visitor *	visitor,
		const UString &	section_name
	)		const

Get all values in a section.

Parameters

[in,out]	visitor	An instance of a subclass of Visitor which receives all values.
[in]	section_name	Name of section to search. Not case-sensitive.

Returns: The number of visited values.

◆ visitSection() [2/2]

size_t ts::NamesFile::visitSection	(	Visitor *	visitor,
		const UString &	section_name,
		Value	value
	)		const

Get all extended values of a specified value in a section.

All sections shall have a nominal width, "Bits=8" for instance. However, when the section has "Extended=true", "extended" values can be provided. With "Bits=8", the value 0x00AA, 0x01AA, or 0xFFAA, are all extended values for the base 8-bit value 0xAA, as an example.

Parameters

[in,out]	visitor	An instance of a subclass of Visitor which receives all extended values for value.
[in]	section_name	Name of section to search. Not case-sensitive.
[in]	value	The base value to get extended values for.

Returns: The number of visited values.

◆ subscribe()

void ts::NamesFile::subscribe	(	Visitor *	visitor,
		const UString &	section_name = `UString()`
	)

Subscribe to all new values which will be merged into the file.

Parameters

[in,out]	visitor	An instance of a subclass of Visitor which will receive all new values in section_name.
[in]	section_name	Name of section to notify. Not case-sensitive. If empty, visitor will be notified of all values in all sections.

◆ unsubscribe()

void ts::NamesFile::unsubscribe	(	Visitor *	visitor,
		const UString &	section_name = `UString()`
	)

Unsubscribe from all new values which will be merged into the file.

Parameters

[in,out]	visitor	An instance of a subclass of Visitor to unsubscribe. If null, remove all visitors for section_name.
[in]	section_name	Name of section to remove. Not case-sensitive. If empty, visitor will unsubscribed of everything.

◆ Formatted()

static UString ts::NamesFile::Formatted	(	Value	value,
		const UString &	name,
		NamesFlags	flags,
		size_t	bits,
		Value	alternate_value = `0`
	)

static

Format a name using flags.

Parameters

[in]	value	Value for the name.
[in]	name	Name for the value.
[in]	flags	Presentation flags.
[in]	bits	Nominal size in bits of the data.
[in]	alternate_value	Display this integer value if flags ALTERNATE is set.

Returns: The corresponding name.

◆ UnregisterExtensionFile()

static void ts::NamesFile::UnregisterExtensionFile ( const UString & file_name )

static

Unregister a previously registered extension.

Parameters

[in] file_name Name of the names file to unregister,

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

tsNamesFile.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Predefined

Constructor & Destructor Documentation

◆ NamesFile()

Member Function Documentation

◆ mergeFile()

◆ mergeConfigurationFile()

◆ Instance() [1/2]

◆ Instance() [2/2]

◆ DeleteInstance()

◆ configurationFile()

◆ errorCount()

◆ nameExists()

◆ nameFromSection()

◆ nameFromSectionWithFallback()

◆ visitSection() [1/2]

◆ visitSection() [2/2]

◆ subscribe()

◆ unsubscribe()

◆ Formatted()

◆ UnregisterExtensionFile()