TSDuck v3.46-4964
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::DuckContext Class Reference

#include <tsDuckContext.h>

Inheritance diagram for ts::DuckContext:
Collaboration diagram for ts::DuckContext:

Classes

class  SavedArgs

Public Member Functions

 DuckContext (Report *report=nullptr, std::ostream *output=nullptr)
virtual ~DuckContext () override
PDS actualPDS (PDS pds) const
void addDefaultREGID (REGID regid)
void addStandards (Standards mask)
CASID casId (CASID cas=CASID_NULL) const
const Charset * charsetIn (const Charset *charset=nullptr) const
const Charset * charsetOut (const Charset *charset=nullptr) const
bool decode (UString &str, const uint8_t *data, size_t size) const
UString decoded (const uint8_t *data, size_t size) const
UString decodedWithByteLength (const uint8_t *&data, size_t &size) const
bool decodeWithByteLength (UString &str, const uint8_t *&data, size_t &size) const
UString defaultHFRegion () const
void defineArgsForCAS (Args &args)
void defineArgsForCharset (Args &args)
void defineArgsForFixingPDS (Args &args)
void defineArgsForHFBand (Args &args)
void defineArgsForPDS (Args &args)
void defineArgsForStandards (Args &args)
void defineArgsForTimeReference (Args &args)
size_t encode (uint8_t *&buffer, size_t &size, const UString &str, size_t start=0, size_t count=NPOS) const
ByteBlock encoded (const UString &str, size_t start=0, size_t count=NPOS) const
ByteBlock encodedWithByteLength (const UString &str, size_t start=0, size_t count=NPOS) const
size_t encodeWithByteLength (uint8_t *&buffer, size_t &size, const UString &str, size_t start=0, size_t count=NPOS) const
bool fixPDS () const
void flush ()
const HFBand * hfBand (const UString &name, bool silent_band=false) const
bool loadArgs (Args &args)
bool muteReport (bool mute)
std::ostream & out () const
bool redirectedOutput () const
virtual Report & report () const override
void reset ()
void resetDefaultREGIDs ()
void resetStandards (Standards mask=Standards::NONE)
void restoreArgs (const SavedArgs &args)
void saveArgs (SavedArgs &args) const
void setDefaultCASId (CASID cas)
void setDefaultCharsetIn (const Charset *charset)
void setDefaultCharsetOut (const Charset *charset)
void setDefaultHFRegion (const UString &region)
void setDefaultPDS (PDS pds)
void setFixPDS (bool fix)
bool setOutput (const fs::path &fileName, bool override=true)
void setOutput (std::ostream *output, bool override=true)
Report * setReport (Report *report)
ReporterBase * setReport (ReporterBase *delegate)
bool setTimeReference (const UString &name)
void setTimeReferenceOffset (cn::milliseconds offset)
void setUseLeapSeconds (bool on)
Standards standards () const
UString timeReferenceName () const
cn::milliseconds timeReferenceOffset () const
const HFBand * uhfBand () const
void updateREGIDs (REGIDVector &regids) const
bool useLeapSeconds () const
const HFBand * vhfBand () const

Static Public Member Functions

static int SilentLevel (bool silent, int default_severity=Severity::Error)

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]reportAddress of the report for log and error messages. If null, use the standard error.
[in]outputThe output stream to use, std::cout on null pointer.

◆ ~DuckContext()

virtual ts::DuckContext::~DuckContext ( )
overridevirtual

Destructor.

Member Function Documentation

◆ reset()

void ts::DuckContext::reset ( )

Reset the TSDuck context to initial configuration.

◆ 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]fileNameThe file name to create. If empty or equal to "-", reset to std::cout.
[in]overrideIt 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]outputThe output stream to use, std::cout on null pointer.
[in]overrideIt 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.

◆ flush()

void ts::DuckContext::flush ( )

Flush the text 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]charsetAn 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]charsetAn 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]strReturned decoded string.
[in]dataAddress of an encoded string.
[in]sizeSize 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]dataAddress of a string in in binary representation (DVB or similar).
[in]sizeSize 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]strReturned decoded string.
[in,out]dataAddress of an encoded string. The address is updated to point after the decoded value.
[in,out]sizeSize 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]dataAddress 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]sizeSize 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]bufferAddress of the buffer where the signalization string is written. The address is updated to point after the encoded value.
[in,out]sizeSize of the buffer. Updated to remaining size.
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum 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]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum 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]bufferAddress 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]sizeSize of the buffer. Updated to remaining size.
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum 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]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum 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]charsetThe 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]charsetThe new preferred output character set or a null pointer to revert to the default.

◆ setDefaultCASId()

void ts::DuckContext::setDefaultCASId ( CASID cas)
inline

Set the default CAS id to use.

Parameters
[in]casDefault CAS id to be used when the CAS is unknown.

◆ casId()

CASID ts::DuckContext::casId ( CASID cas = CASID_NULL) const
inline

The actual CAS id to use.

Parameters
[in]casProposed CAS id. If equal to CASID_NULL, then another value can be returned.
Returns
The actual CAS id to use.

◆ setFixPDS()

void ts::DuckContext::setFixPDS ( bool fix)
inline

Set the fixing mode of missing PDS and REGID.

Parameters
[in]fixIf true, when serializing XML private MPEG and DVB descriptors in tables, the required REGID or PDS is automatically added if missing.

◆ fixPDS()

bool ts::DuckContext::fixPDS ( ) const
inline

Check if missing registration descriptors and private data specified descriptors are automatically added when serializing XML tables.

Returns
True if missing registration descriptors and private data specified descriptors are automatically added.

◆ setDefaultPDS()

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

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

Parameters
[in]pdsDefault 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]pdsCurrent PDS, typically from a private_data_specifier_descriptor.
Returns
The actual PDS to use.

◆ resetDefaultREGIDs()

void ts::DuckContext::resetDefaultREGIDs ( )
inline

Reset the list of default registration ids. All registration ids, including those coming from --default-registration options, are deleted.

◆ addDefaultREGID()

void ts::DuckContext::addDefaultREGID ( REGID regid)
inline

Add a new id at the end of the list of default registration ids.

Parameters
[in]regidA registration id to add.

◆ updateREGIDs()

void ts::DuckContext::updateREGIDs ( REGIDVector & regids) const
inline

Update a list of registration ids (typically from a descriptor list) with the default registration ids. The default registration ids mostly come from --default-registration options. They are inserted at the beginning of regids.

Parameters
[in,out]regidsThe list of registration ids to update.

◆ 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]maskA 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]maskA bit mask of standards.

◆ setDefaultHFRegion()

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

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

Parameters
[in]regionName 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]nameName of the HF band to search (e.g. u"UHF", u"VHF", u"BS", u"CS").
[in]silent_bandIf 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]offsetOffset 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]nameTime 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]onTrue 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]argsCommand 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]argsCommand line arguments to update.

◆ defineArgsForPDS()

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

Define Private Data Specifier and Registration Id command line options in an Args. Defined options: --default-pds and --default-registration. The context keeps track of defined options so that loadOptions() can parse the appropriate options.

Parameters
[in,out]argsCommand line arguments to update.

◆ defineArgsForFixingPDS()

void ts::DuckContext::defineArgsForFixingPDS ( Args & args)
inline

Define command line options in an Args to automatically fix missing Private Data Specifier and Registration Id. Defined options: --fix-missing-pds. The context keeps track of defined options so that loadOptions() can parse the appropriate options.

Parameters
[in,out]argsCommand 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]argsCommand 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]argsCommand 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]argsCommand 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]argsCommand 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]argsSaved arguments.

◆ restoreArgs()

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

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

Parameters
[in]argsSaved arguments to restore.

◆ report()

virtual Report & ts::ReporterBase::report ( ) const
overridevirtualinherited

Access the Report which is associated with this object. Can be called from another thread only if the Report object is thread-safe.

Returns
A reference to the associated report.

Implements ts::ReporterInterface.

◆ setReport() [1/2]

Report * ts::ReporterBase::setReport ( Report * report)
inherited

Associate this object with another Report to log errors.

Parameters
[in]reportWhere to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.
Returns
The address of the previous Report object or a null pointer if there was none.

◆ setReport() [2/2]

ReporterBase * ts::ReporterBase::setReport ( ReporterBase * delegate)
inherited

Associate this object with another ReporterBase to log errors.

Parameters
[in]delegateUse the report of another ReporterBase. If delegate is null, the previous explicit Report is used..
Returns
The address of the previous ReporterBase object or a null pointer if there was none.

◆ muteReport()

bool ts::ReporterBase::muteReport ( bool mute)
inherited

Temporarily mute the associated report.

Parameters
[in]muteIt true, report() will return a null report (log messages are discarded), until muteReport() is invoked again with mute set to false.
Returns
Previous state of the mute field.

◆ SilentLevel()

int ts::ReporterBase::SilentLevel ( bool silent,
int default_severity = Severity::Error )
inlinestaticinherited

Compute a log severity level from a "silent" parameter. Some subclass methods have a "silent" parameter to avoid reporting errors which may be insignificant, typically when closing a device after an error, in which case the close operation may produce other errors if the previous error left the device in an inconsistent state. While those errors should not be displayed as errors, we still display them at debug level.

Parameters
[in]silentIf true, do not report errors, report debug messages instead.
[in]default_severityDefault severity, in non-silent mode (error by default).
Returns
Error when silent is false, Debug otherwise.

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