TSDuck Version 3.22-1913 (TSDuck - The MPEG Transport Stream Toolkit)
ts::DuckContext Class Reference

TSDuck execution context containing current preferences. More...

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. More...
 
PDS actualPDS (PDS pds) const
 The actual private data specifier to use. More...
 
void addStandards (Standards mask)
 Add a list of standards which are present in the transport stream or context. More...
 
uint16_t casId (uint16_t cas=CASID_NULL) const
 The actual CAS id to use. More...
 
const CharsetcharsetIn () const
 Get the default input character set for strings from tables and descriptors. More...
 
const CharsetcharsetOut () const
 Get the preferred output character set for strings to insert in tables and descriptors. More...
 
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. More...
 
UString decoded (const uint8_t *data, size_t size) const
 Convert a signalization string into UTF-16 using the default input character set. More...
 
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. More...
 
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. More...
 
UString defaultHFRegion () const
 Get the name of the default region for UVH and VHF band frequency layout. More...
 
void defineArgsForCAS (Args &args)
 Define default CAS command line options in an Args. More...
 
void defineArgsForCharset (Args &args)
 Define character set command line options in an Args. More...
 
void defineArgsForHFBand (Args &args)
 Define HF band command line options in an Args. More...
 
void defineArgsForPDS (Args &args)
 Define Private Data Specifier command line options in an Args. More...
 
void defineArgsForStandards (Args &args)
 Define contextual standards command line options in an Args. More...
 
std::ostream & displayIfASCII (const void *data, size_t size, const UString &prefix=UString(), const UString &suffix=UString())
 A utility method to display data if it can be interpreted as an ASCII string. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void flush ()
 Flush the text output.
 
const HFBandhfBand (const UString &name, bool silent_band=false) const
 Get the description of an HF band for the default region. More...
 
bool loadArgs (Args &args)
 Load the values of all previously defined arguments from command line. More...
 
std::ostream & out () const
 Get the current output stream to issue long text output. More...
 
Reportreport () const
 Get the current report for log and error messages. More...
 
void reset ()
 Reset the TSDuck context to initial configuration.
 
void resetStandards (Standards mask=Standards::NONE)
 Reset the list of standards which are present in the transport stream or context. More...
 
void restoreArgs (const SavedArgs &args)
 Restore all command line options, as loaded by loadArgs() in another DuckContext. More...
 
void saveArgs (SavedArgs &args) const
 Save all command line options, as loaded by loadArgs(). More...
 
void setDefaultCASId (uint16_t cas)
 Set the default CAS id to use. More...
 
void setDefaultCharsetIn (const Charset *charset)
 Set the default input character set for strings. More...
 
void setDefaultCharsetOut (const Charset *charset)
 Set the preferred output character set for strings. More...
 
void setDefaultHFRegion (const UString &region)
 Set the name of the default region for UVH and VHF band frequency layout. More...
 
void setDefaultPDS (PDS pds)
 Set the default private data specifier to use in the absence of explicit private_data_specifier_descriptor. More...
 
bool setOutput (const UString &fileName, bool override=true)
 Redirect the output stream to a file. More...
 
void setOutput (std::ostream *output, bool override=true)
 Redirect the output stream to a stream. More...
 
void setReport (Report *report)
 Set a new report for log and error messages. More...
 
Standards standards () const
 Get the list of standards which are present in the transport stream or context. More...
 
std::string toASCII (const void *data, size_t size) const
 A utility method to interpret data as an ASCII string. More...
 
const HFBanduhfBand () const
 Get the description of the UHF band for the default region. More...
 
const HFBandvhfBand () const
 Get the description of the VHF band for the default region. More...
 

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.

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]reportAddress 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 UString fileName,
bool  override = true 
)

Redirect the output stream to a file.

Parameters
[in]fileNameThe file name to create. If empty, 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.

◆ toASCII()

std::string ts::DuckContext::toASCII ( const void *  data,
size_t  size 
) const

A utility method to interpret data as an ASCII string.

Parameters
[in]dataAddress of data.
[in]sizeSize of data.
Returns
If all bytes in data are ASCII (optionally padded with zeroes), return the equivalent ASCII string. Otherwise, return an empty string.

◆ displayIfASCII()

std::ostream& ts::DuckContext::displayIfASCII ( const void *  data,
size_t  size,
const UString prefix = UString(),
const UString suffix = UString() 
)

A utility method to display data if it can be interpreted as an ASCII string.

Parameters
[in]dataAddress of data.
[in]sizeSize of data.
[in]prefixTo print before the ASCII data.
[in]suffixTo print after the ASCII data.
Returns
A reference to the output stream.

◆ charsetIn()

const Charset* ts::DuckContext::charsetIn ( ) 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).

Returns
The default input character set (never null).

◆ charsetOut()

const Charset* ts::DuckContext::charsetOut ( ) const
inline

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

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 ( uint16_t  cas)

Set the default CAS id to use.

Parameters
[in]casDefault 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]casProposed 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]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.

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

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.

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

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

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