TSDuck execution context containing current preferences. More...

#include <tsDuckContext.h>

Classes
class	SavedArgs
	An opaque class to save all command line options, as loaded by loadArgs(). More...

Public Member Functions
	DuckContext (Report report=nullptr, std::ostream output=nullptr)
	Constructor.

PDS	actualPDS (PDS pds) const
	The actual private data specifier to use.

void	addRegistrationId (uint32_t regid)
	Add a registration id, as found in an MPEG-defined registration descriptor.

void	addStandards (Standards mask)
	Add a list of standards which are present in the transport stream or context.

uint16_t	casId (uint16_t cas=CASID_NULL) const
	The actual CAS id to use.

const Charset *	charsetIn (const Charset *charset=nullptr) const
	Get the default input character set for strings from tables and descriptors.

const Charset *	charsetOut (const Charset *charset=nullptr) const
	Get the preferred output character set for strings to insert in tables and descriptors.

bool	decode (UString &str, const uint8_t *data, size_t size) const
	Convert a signalization string into UTF-16 using the default input character set.

UString	decoded (const uint8_t *data, size_t size) const
	Convert a signalization string into UTF-16 using the default input character set.

UString	decodedWithByteLength (const uint8_t *&data, size_t &size) const
	Convert a signalization string (preceded by its one-byte length) into UTF-16 using the default input character set.

bool	decodeWithByteLength (UString &str, const uint8_t *&data, size_t &size) const
	Convert a signalization string (preceded by its one-byte length) into UTF-16 using the default input character set.

UString	defaultHFRegion () const
	Get the name of the default region for UVH and VHF band frequency layout.

void	defineArgsForCAS (Args &args)
	Define default CAS command line options in an Args.

void	defineArgsForCharset (Args &args)
	Define character set command line options in an Args.

void	defineArgsForHFBand (Args &args)
	Define HF band command line options in an Args.

void	defineArgsForPDS (Args &args)
	Define Private Data Specifier command line options in an Args.

void	defineArgsForStandards (Args &args)
	Define contextual standards command line options in an Args.

void	defineArgsForTimeReference (Args &args)
	Define time reference command line options in an Args.

size_t	encode (uint8_t *&buffer, size_t &size, const UString &str, size_t start=0, size_t count=NPOS) const
	Encode an UTF-16 string into a signalization string using the preferred output character set.

ByteBlock	encoded (const UString &str, size_t start=0, size_t count=NPOS) const
	Encode an UTF-16 string into a signalization string using the preferred output character set.

ByteBlock	encodedWithByteLength (const UString &str, size_t start=0, size_t count=NPOS) const
	Encode an UTF-16 string into a signalization string (preceded by its one-byte length) using the preferred output character set.

size_t	encodeWithByteLength (uint8_t *&buffer, size_t &size, const UString &str, size_t start=0, size_t count=NPOS) const
	Encode an UTF-16 string into a signalization string (preceded by its one-byte length) using the preferred output character set.

void	flush ()
	Flush the text output.

const HFBand *	hfBand (const UString &name, bool silent_band=false) const
	Get the description of an HF band for the default region.

uint32_t	lastRegistrationId () const
	Get the last registration id, as found in MPEG-defined registration descriptors.

bool	loadArgs (Args &args)
	Load the values of all previously defined arguments from command line.

std::ostream &	out () const
	Get the current output stream to issue long text output.

bool	redirectedOutput () const
	Check if output was redirected.

const std::set< uint32_t > &	registrationIds () const
	Get the set of all registration ids, as found in MPEG-defined registration descriptors.

Report &	report () const
	Get the current report for log and error messages.

void	reset ()
	Reset the TSDuck context to initial configuration.

void	resetRegistrationIds ()
	Clear all accumulated registration ids, as found in MPEG-defined registration descriptors.

void	resetStandards (Standards mask=Standards::NONE)
	Reset the list of standards which are present in the transport stream or context.

void	restoreArgs (const SavedArgs &args)
	Restore all command line options, as loaded by loadArgs() in another DuckContext.

void	saveArgs (SavedArgs &args) const
	Save all command line options, as loaded by loadArgs().

void	setDefaultCASId (uint16_t cas)
	Set the default CAS id to use.

void	setDefaultCharsetIn (const Charset *charset)
	Set the default input character set for strings.

void	setDefaultCharsetOut (const Charset *charset)
	Set the preferred output character set for strings.

void	setDefaultHFRegion (const UString &region)
	Set the name of the default region for UVH and VHF band frequency layout.

void	setDefaultPDS (PDS pds)
	Set the default private data specifier to use in the absence of explicit private_data_specifier_descriptor.

bool	setOutput (const fs::path &fileName, bool override=true)
	Redirect the output stream to a file.

void	setOutput (std::ostream *output, bool override=true)
	Redirect the output stream to a stream.

void	setReport (Report *report)
	Set a new report for log and error messages.

bool	setTimeReference (const UString &name)
	Set a non-standard time reference offset using a name.

void	setTimeReferenceOffset (cn::milliseconds offset)
	Set a non-standard time reference offset.

void	setUseLeapSeconds (bool on)
	Set the explicit inclusion of leap seconds where it is needed.

Standards	standards () const
	Get the list of standards which are present in the transport stream or context.

UString	timeReferenceName () const
	Get the non-standard time reference offset as a string.

cn::milliseconds	timeReferenceOffset () const
	Get the non-standard time reference offset.

const HFBand *	uhfBand () const
	Get the description of the UHF band for the default region.

bool	useLeapSeconds () const
	Check the explicit inclusion of leap seconds where it is needed.

const HFBand *	vhfBand () const
	Get the description of the VHF band for the default region.

Detailed Description

TSDuck execution context containing current preferences.

An instance of this class contains specific contextual information for the execution of TSDuck. This context contains either user's preferences and accumulated contextual information.

Context information include:

Report for log and error messages.
Text output stream.
Default character sets (input and output).
Default CAS id.
Default Private Data Specifier (PDS) for DVB private descriptors.
Accumulated standards from the signalization (MPEG, DVB, ATSC, etc.)
Default region for UHF and VHF frequency layout.

Support is included to define and analyze command line options which define values for the environment.

Unlike DuckConfigFile, this class is not a singleton. More than one context is allowed in the same process as long as the various instances of classes which use DuckContext use only one context at a time. For instance, inside a tsp or tsswitch process, each plugin can use its own context, using different preferences.

The class DuckContext is not thread-safe. It shall be used from one single thread or explicit synchronization is required.

Constructor & Destructor Documentation

◆ DuckContext()

ts::DuckContext::DuckContext	(	Report *	report = `nullptr`,
		std::ostream *	output = `nullptr`
	)

Constructor.

Parameters

[in]	report	Address of the report for log and error messages. If null, use the standard error.
[in]	output	The output stream to use, `std::cout` on null pointer.

Member Function Documentation

◆ report()

Report & ts::DuckContext::report ( ) const

inline

Get the current report for log and error messages.

Returns: A reference to the current output report.

◆ setReport()

void ts::DuckContext::setReport ( Report * report )

Set a new report for log and error messages.

Parameters

[in] report Address of the report for log and error messages. If null, use the standard error.

◆ out()

std::ostream & ts::DuckContext::out ( ) const

inline

Get the current output stream to issue long text output.

Returns: A reference to the output stream.

◆ setOutput() [1/2]

bool ts::DuckContext::setOutput	(	const fs::path &	fileName,
		bool	override = `true`
	)

Redirect the output stream to a file.

Parameters

[in]	fileName	The file name to create. If empty or equal to "-", reset to `std::cout`.
[in]	override	It true, the previous file is closed. If false and the output is already redirected outside `std::cout`, do nothing.

Returns: True on success, false on error.

◆ setOutput() [2/2]

void ts::DuckContext::setOutput	(	std::ostream *	output,
		bool	override = `true`
	)

Redirect the output stream to a stream.

Parameters

[in]	output	The output stream to use, `std::cout` on null pointer.
[in]	override	It true, the previous file is closed. If false and the output is already redirected outside `std::cout`, do nothing.

◆ redirectedOutput()

bool ts::DuckContext::redirectedOutput ( ) const

inline

Check if output was redirected.

Returns: True if the current output is neither the initial one nor the standard output.

◆ charsetIn()

const Charset * ts::DuckContext::charsetIn ( const Charset * charset = nullptr ) const

inline

Get the default input character set for strings from tables and descriptors.

The default is the DVB superset of ISO/IEC 6937 as defined in ETSI EN 300 468. Other defaults can be used in non-DVB contexts or when a DVB operator uses an incorrect signalization, assuming another default character set (usually from its own country).

Parameters

[in] charset An optional specific character set to use instead of the default one.

Returns: The default input character set (never null).

◆ charsetOut()

const Charset * ts::DuckContext::charsetOut ( const Charset * charset = nullptr ) const

inline

Get the preferred output character set for strings to insert in tables and descriptors.

Parameters

[in] charset An optional specific character set to use instead of the default one.

Returns: The preferred output character set (never null).

◆ decode()

bool ts::DuckContext::decode	(	UString &	str,
		const uint8_t *	data,
		size_t	size
	)		const

inline

Convert a signalization string into UTF-16 using the default input character set.

Parameters

[out]	str	Returned decoded string.
[in]	data	Address of an encoded string.
[in]	size	Size in bytes of the encoded string.

Returns: True on success, false on error (truncated, unsupported format, etc.)

See also: ETSI EN 300 468, Annex A.

◆ decoded()

UString ts::DuckContext::decoded	(	const uint8_t *	data,
		size_t	size
	)		const

inline

Convert a signalization string into UTF-16 using the default input character set.

Parameters

[in]	data	Address of a string in in binary representation (DVB or similar).
[in]	size	Size in bytes of the string.

Returns: The equivalent UTF-16 string. Stop on untranslatable character, if any.

See also: ETSI EN 300 468, Annex A.

◆ decodeWithByteLength()

bool ts::DuckContext::decodeWithByteLength	(	UString &	str,
		const uint8_t *&	data,
		size_t &	size
	)		const

inline

Convert a signalization string (preceded by its one-byte length) into UTF-16 using the default input character set.

Parameters

[out]	str	Returned decoded string.
[in,out]	data	Address of an encoded string. The address is updated to point after the decoded value.
[in,out]	size	Size of the buffer. Updated to remaining size.

Returns: True on success, false on error (truncated, unsupported format, etc.)

See also: ETSI EN 300 468, Annex A.

◆ decodedWithByteLength()

UString ts::DuckContext::decodedWithByteLength	(	const uint8_t *&	data,
		size_t &	size
	)		const

inline

Convert a signalization string (preceded by its one-byte length) into UTF-16 using the default input character set.

Parameters

[in,out]	data	Address of a buffer containing a string to read. The first byte in the buffer is the length in bytes of the string. Upon return, buffer is updated to point after the end of the string.
[in,out]	size	Size in bytes of the buffer, which may be larger than the DVB string. Upon return, size is updated, decremented by the same amount buffer was incremented.

Returns: The equivalent UTF-16 string. Stop on untranslatable character, if any.

See also: ETSI EN 300 468, Annex A.

◆ encode()

size_t ts::DuckContext::encode	(	uint8_t *&	buffer,
		size_t &	size,
		const UString &	str,
		size_t	start = `0`,
		size_t	count = `NPOS`
	)		const

inline

Encode an UTF-16 string into a signalization string using the preferred output character set.

Stop either when this string is serialized or when the buffer is full, whichever comes first.

Parameters

[in,out]	buffer	Address of the buffer where the signalization string is written. The address is updated to point after the encoded value.
[in,out]	size	Size of the buffer. Updated to remaining size.
[in]	str	The UTF-16 string to encode.
[in]	start	Starting offset to convert in this UTF-16 string.
[in]	count	Maximum number of characters to convert.

Returns: The number of serialized characters (which is usually not the same as the number of written bytes).

◆ encoded()

ByteBlock ts::DuckContext::encoded	(	const UString &	str,
		size_t	start = `0`,
		size_t	count = `NPOS`
	)		const

inline

Encode an UTF-16 string into a signalization string using the preferred output character set.

Parameters

[in]	str	The UTF-16 string to encode.
[in]	start	Starting offset to convert in this UTF-16 string.
[in]	count	Maximum number of characters to convert.

Returns: The DVB string.

◆ encodeWithByteLength()

size_t ts::DuckContext::encodeWithByteLength	(	uint8_t *&	buffer,
		size_t &	size,
		const UString &	str,
		size_t	start = `0`,
		size_t	count = `NPOS`
	)		const

inline

Encode an UTF-16 string into a signalization string (preceded by its one-byte length) using the preferred output character set.

Stop either when this string is serialized or when the buffer is full or when 255 bytes are written, whichever comes first.

Parameters

[in,out]	buffer	Address of the buffer where the DVB string is written. The first byte will receive the size in bytes of the DVB string. The address is updated to point after the encoded value.
[in,out]	size	Size of the buffer. Updated to remaining size.
[in]	str	The UTF-16 string to encode.
[in]	start	Starting offset to convert in this UTF-16 string.
[in]	count	Maximum number of characters to convert.

Returns: The number of serialized characters (which is usually not the same as the number of written bytes).

◆ encodedWithByteLength()

ByteBlock ts::DuckContext::encodedWithByteLength	(	const UString &	str,
		size_t	start = `0`,
		size_t	count = `NPOS`
	)		const

inline

Encode an UTF-16 string into a signalization string (preceded by its one-byte length) using the preferred output character set.

Parameters

[in]	str	The UTF-16 string to encode.
[in]	start	Starting offset to convert in this UTF-16 string.
[in]	count	Maximum number of characters to convert.

Returns: The DVB string with the initial length byte.

◆ setDefaultCharsetIn()

void ts::DuckContext::setDefaultCharsetIn ( const Charset * charset )

Set the default input character set for strings.

The default should be the DVB superset of ISO/IEC 6937 as defined in ETSI EN 300 468. Use another default in the context of an operator using an incorrect signalization, assuming another default character set (usually from its own country).

Parameters

[in] charset The new default input character set or a null pointer to revert to the default.

◆ setDefaultCharsetOut()

void ts::DuckContext::setDefaultCharsetOut ( const Charset * charset )

Set the preferred output character set for strings.

Parameters

[in] charset The new preferred output character set or a null pointer to revert to the default.

◆ setDefaultCASId()

void ts::DuckContext::setDefaultCASId ( uint16_t cas )

Set the default CAS id to use.

Parameters

[in] cas Default CAS id to be used when the CAS is unknown.

◆ casId()

uint16_t ts::DuckContext::casId ( uint16_t cas = CASID_NULL ) const

The actual CAS id to use.

Parameters

[in] cas Proposed CAS id. If equal to CASID_NULL, then another value can be returned.

Returns: The actual CAS id to use.

◆ setDefaultPDS()

void ts::DuckContext::setDefaultPDS ( PDS pds )

Set the default private data specifier to use in the absence of explicit private_data_specifier_descriptor.

Parameters

[in] pds Default PDS. Use zero to revert to no default.

◆ actualPDS()

PDS ts::DuckContext::actualPDS ( PDS pds ) const

The actual private data specifier to use.

Parameters

[in] pds Current PDS, typically from a private_data_specifier_descriptor.

Returns: The actual PDS to use.

◆ addRegistrationId()

void ts::DuckContext::addRegistrationId ( uint32_t regid )

Add a registration id, as found in an MPEG-defined registration descriptor.

Parameters

[in] regid A new registration id.

◆ registrationIds()

const std::set< uint32_t > & ts::DuckContext::registrationIds ( ) const

inline

Get the set of all registration ids, as found in MPEG-defined registration descriptors.

Returns: A constant reference to the set of all registration ids.

◆ lastRegistrationId()

uint32_t ts::DuckContext::lastRegistrationId ( ) const

inline

Get the last registration id, as found in MPEG-defined registration descriptors.

Returns: The last registration id or REGID_NULL if none was found.

◆ standards()

Standards ts::DuckContext::standards ( ) const

inline

Get the list of standards which are present in the transport stream or context.

Returns: A bit mask of standards.

◆ addStandards()

void ts::DuckContext::addStandards ( Standards mask )

Add a list of standards which are present in the transport stream or context.

Parameters

[in] mask A bit mask of standards.

◆ resetStandards()

void ts::DuckContext::resetStandards ( Standards mask = Standards::NONE )

Reset the list of standards which are present in the transport stream or context.

Parameters

[in] mask A bit mask of standards.

◆ setDefaultHFRegion()

void ts::DuckContext::setDefaultHFRegion ( const UString & region )

Set the name of the default region for UVH and VHF band frequency layout.

Parameters

[in] region Name of the region. Use an empty string to revert to the default.

◆ defaultHFRegion()

UString ts::DuckContext::defaultHFRegion ( ) const

Get the name of the default region for UVH and VHF band frequency layout.

Returns: Name of the default region.

◆ hfBand()

const HFBand * ts::DuckContext::hfBand	(	const UString &	name,
		bool	silent_band = `false`
	)		const

Get the description of an HF band for the default region.

Parameters

[in]	name	Name of the HF band to search (e.g. u"UHF", u"VHF", u"BS", u"CS").
[in]	silent_band	If true, do not report error message if the band is not found in the file. Other errors (HF band file not found, region not found) are still reported.

Returns: The description of the band for the default region. Never null.

◆ vhfBand()

const HFBand * ts::DuckContext::vhfBand ( ) const

Get the description of the VHF band for the default region.

Returns: The description of the VHF band for the default region. Never null.

◆ uhfBand()

const HFBand * ts::DuckContext::uhfBand ( ) const

Get the description of the UHF band for the default region.

Returns: The description of the UHF band for the default region. Never null.

◆ setTimeReferenceOffset()

void ts::DuckContext::setTimeReferenceOffset ( cn::milliseconds offset )

inline

Set a non-standard time reference offset.

In DVB SI, reference times are UTC. These SI can be reused in non-standard ways where the stored times use another reference. This is the case with ARIB and ABNT variants of ISDB which reuse TOT, TDT and EIT but with another local time reference.

Parameters

[in] offset Offset from UTC in milli-seconds. Can be positive or negative. The default offset is zero, meaning plain UTC time.

◆ setTimeReference()

bool ts::DuckContext::setTimeReference ( const UString & name )

Set a non-standard time reference offset using a name.

Parameters

[in] name Time reference name. The non-standard time reference offset is computed from this name which can be "JST" or "UTC[[+|-]hh[:mm]]".

Returns: True on success, false if name is invalid.

See also: setTimeReferenceOffset()

◆ timeReferenceOffset()

cn::milliseconds ts::DuckContext::timeReferenceOffset ( ) const

inline

Get the non-standard time reference offset.

Returns: The offset from UTC in milli-seconds. Can be positive or negative.

◆ timeReferenceName()

UString ts::DuckContext::timeReferenceName ( ) const

Get the non-standard time reference offset as a string.

Returns: The offset from UTC as a string.

◆ setUseLeapSeconds()

void ts::DuckContext::setUseLeapSeconds ( bool on )

inline

Set the explicit inclusion of leap seconds where it is needed.

Currently, this applies to SCTE 35 splice_schedule() commands only.

Parameters

[in] on True if leap seconds shall be explicitly included (the default), false to ignore leap seconds.

◆ useLeapSeconds()

bool ts::DuckContext::useLeapSeconds ( ) const

inline

Check the explicit inclusion of leap seconds where it is needed.

Returns: True if leap seconds shall be explicitly included, false to ignore leap seconds.

◆ defineArgsForCharset()

void ts::DuckContext::defineArgsForCharset ( Args & args )

inline

Define character set command line options in an Args.

Defined options: --default-charset, --europe. The context keeps track of defined options so that loadOptions() can parse the appropriate options.

Parameters

[in,out] args Command line arguments to update.

◆ defineArgsForCAS()

void ts::DuckContext::defineArgsForCAS ( Args & args )

inline

Define default CAS command line options in an Args.

Defined options: --default-cas-id and other CAS-specific options. The context keeps track of defined options so that loadOptions() can parse the appropriate options.

Parameters

[in,out] args Command line arguments to update.

◆ defineArgsForPDS()

void ts::DuckContext::defineArgsForPDS ( Args & args )

inline

Define Private Data Specifier command line options in an Args.

Defined options: --default-pds. The context keeps track of defined options so that loadOptions() can parse the appropriate options.

Parameters

[in,out] args Command line arguments to update.

◆ defineArgsForStandards()

void ts::DuckContext::defineArgsForStandards ( Args & args )

inline

Define contextual standards command line options in an Args.

Defined options: --atsc. The context keeps track of defined options so that loadOptions() can parse the appropriate options.

Parameters

[in,out] args Command line arguments to update.

◆ defineArgsForHFBand()

void ts::DuckContext::defineArgsForHFBand ( Args & args )

inline

Define HF band command line options in an Args.

Defined options: --hf-band-region. The context keeps track of defined options so that loadOptions() can parse the appropriate options.

Parameters

[in,out] args Command line arguments to update.

◆ defineArgsForTimeReference()

void ts::DuckContext::defineArgsForTimeReference ( Args & args )

inline

Define time reference command line options in an Args.

Defined options: --time-reference. The context keeps track of defined options so that loadOptions() can parse the appropriate options.

Parameters

[in,out] args Command line arguments to update.

◆ loadArgs()

bool ts::DuckContext::loadArgs ( Args & args )

Load the values of all previously defined arguments from command line.

Args error indicator is set in case of incorrect arguments.

Parameters

[in,out] args Command line arguments.

Returns: True on success, false on error in argument line.

◆ saveArgs()

void ts::DuckContext::saveArgs ( SavedArgs & args ) const

Save all command line options, as loaded by loadArgs().

Parameters

[out] args Saved arguments.

◆ restoreArgs()

void ts::DuckContext::restoreArgs ( const SavedArgs & args )

Restore all command line options, as loaded by loadArgs() in another DuckContext.

Parameters

[in] args Saved arguments to restore.

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

tsDuckContext.h

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DuckContext()

Member Function Documentation

◆ report()

◆ setReport()

◆ out()

◆ setOutput() [1/2]

◆ setOutput() [2/2]

◆ redirectedOutput()

◆ charsetIn()

◆ charsetOut()

◆ decode()

◆ decoded()

◆ decodeWithByteLength()

◆ decodedWithByteLength()

◆ encode()

◆ encoded()

◆ encodeWithByteLength()

◆ encodedWithByteLength()

◆ setDefaultCharsetIn()

◆ setDefaultCharsetOut()

◆ setDefaultCASId()

◆ casId()

◆ setDefaultPDS()

◆ actualPDS()

◆ addRegistrationId()

◆ registrationIds()

◆ lastRegistrationId()

◆ standards()

◆ addStandards()

◆ resetStandards()

◆ setDefaultHFRegion()

◆ defaultHFRegion()

◆ hfBand()

◆ vhfBand()

◆ uhfBand()

◆ setTimeReferenceOffset()

◆ setTimeReference()

◆ timeReferenceOffset()

◆ timeReferenceName()

◆ setUseLeapSeconds()

◆ useLeapSeconds()

◆ defineArgsForCharset()

◆ defineArgsForCAS()

◆ defineArgsForPDS()

◆ defineArgsForStandards()

◆ defineArgsForHFBand()

◆ defineArgsForTimeReference()

◆ loadArgs()

◆ saveArgs()

◆ restoreArgs()