TSDuck Version 3.18-1255 (TSDuck - The MPEG Transport Stream Toolkit)
ts::DuckContext Class Reference

TSDuck execution context containing current preferences. 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...
 
CASFamily casFamily (CASFamily cas=CAS_OTHER) const
 The actual CAS family to use. More...
 
UString defaultHFRegion () const
 Get the name of the default region for UVH and VHF band frequency layout. More...
 
void defineOptionsForDVBCharset (Args &args)
 Define DVB character set command line options in an Args. More...
 
void defineOptionsForHFBand (Args &args)
 Define HF band command line options in an Args. More...
 
void defineOptionsForPDS (Args &args)
 Define Private Data Specifier command line options in an Args. More...
 
void defineOptionsForStandards (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...
 
const DVBCharsetdvbCharsetIn () const
 Get the default input DVB character set for DVB strings without table code. More...
 
const DVBCharsetdvbCharsetOut () const
 Get the preferred output DVB character set for DVB strings. More...
 
void flush ()
 Flush the text output.
 
UString fromDVB (const std::string &dvb) const
 Convert a DVB string into UTF-16 using the default input DVB character set. More...
 
UString fromDVB (const uint8_t *dvb, size_t dvbSize) const
 Convert a DVB string into UTF-16 using the default input DVB character set. More...
 
UString fromDVBWithByteLength (const uint8_t *&buffer, size_t &size) const
 Convert a DVB string into UTF-16 (preceded by its one-byte length) using the default input DVB character set. More...
 
bool loadOptions (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 resetStandards (Standards mask=STD_NONE)
 Reset the list of standards which are present in the transport stream or context. More...
 
void setDefaultCASFamily (CASFamily cas)
 Set the default CAS family to use. More...
 
void setDefaultDVBCharsetIn (const DVBCharset *charset)
 Set the default input DVB character set for DVB strings without table code. More...
 
void setDefaultDVBCharsetOut (const DVBCharset *charset)
 Set the preferred output DVB character set for DVB 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...
 
size_t toDVB (const UString &str, uint8_t *&buffer, size_t &size, size_t start=0, size_t count=NPOS) const
 Encode an UTF-16 string into a DVB string using the preferred output DVB character set. More...
 
ByteBlock toDVB (const UString &str, size_t start=0, size_t count=NPOS) const
 Encode an UTF-16 string into a DVB string using the preferred output DVB character set. More...
 
size_t toDVBWithByteLength (const UString &str, uint8_t *&buffer, size_t &size, size_t start=0, size_t count=NPOS) const
 Encode an UTF-16 string into a DVB string (preceded by its one-byte length) using the preferred output DVB character set. More...
 
ByteBlock toDVBWithByteLength (const UString &str, size_t start=0, size_t count=NPOS) const
 Encode an UTF-16 string into a DVB string (preceded by its one-byte length) using the preferred output DVB character set. 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 DVB character sets (input and output).
  • Default CAS family.
  • 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.

◆ dvbCharsetIn()

const DVBCharset* ts::DuckContext::dvbCharsetIn ( ) const
inline

Get the default input DVB character set for DVB strings without table code.

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

Returns
The default input DVB character set or the null pointer if none is defined.

◆ dvbCharsetOut()

const DVBCharset* ts::DuckContext::dvbCharsetOut ( ) const
inline

Get the preferred output DVB character set for DVB strings.

Returns
The preferred output DVB character set or the null pointer if none is defined.

◆ fromDVB() [1/2]

UString ts::DuckContext::fromDVB ( const std::string &  dvb) const
inline

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

Parameters
[in]dvbA string in DVB representation. The first bytes of the string indicate the DVB character set to use.
Returns
The equivalent UTF-16 string. Stop on untranslatable character, if any.
See also
ETSI EN 300 468, Annex A.

◆ fromDVB() [2/2]

UString ts::DuckContext::fromDVB ( const uint8_t *  dvb,
size_t  dvbSize 
) const
inline

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

Parameters
[in]dvbAddress of a string in DVB representation. The first bytes of the string indicate the DVB character set to use.
[in]dvbSizeSize in bytes of the DVB string.
Returns
The equivalent UTF-16 string. Stop on untranslatable character, if any.
See also
ETSI EN 300 468, Annex A.

◆ fromDVBWithByteLength()

UString ts::DuckContext::fromDVBWithByteLength ( const uint8_t *&  buffer,
size_t &  size 
) const
inline

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

Parameters
[in,out]bufferAddress of a buffer containing a DVB 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.

◆ toDVB() [1/2]

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

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

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

Parameters
[in]strThe UTF-16 string to encode.
[in,out]bufferAddress of the buffer where the DVB string is written. The address is updated to point after the encoded value.
[in,out]sizeSize of the buffer. Updated to remaining size.
[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).

◆ toDVB() [2/2]

ByteBlock ts::DuckContext::toDVB ( const UString str,
size_t  start = 0,
size_t  count = NPOS 
) const
inline

Encode an UTF-16 string into a DVB string using the preferred output DVB 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.

◆ toDVBWithByteLength() [1/2]

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

Encode an UTF-16 string into a DVB string (preceded by its one-byte length) using the preferred output DVB 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]strThe UTF-16 string to encode.
[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]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).

◆ toDVBWithByteLength() [2/2]

ByteBlock ts::DuckContext::toDVBWithByteLength ( const UString str,
size_t  start = 0,
size_t  count = NPOS 
) const
inline

Encode an UTF-16 string into a DVB string (preceded by its one-byte length) using the preferred output DVB 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.

◆ setDefaultDVBCharsetIn()

void ts::DuckContext::setDefaultDVBCharsetIn ( const DVBCharset charset)

Set the default input DVB character set for DVB strings without table code.

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 DVB character set or a null pointer to revert to the default.

◆ setDefaultDVBCharsetOut()

void ts::DuckContext::setDefaultDVBCharsetOut ( const DVBCharset charset)

Set the preferred output DVB character set for DVB strings.

Parameters
[in]charsetThe new preferred output DVB character set or a null pointer to revert to the default.

◆ setDefaultCASFamily()

void ts::DuckContext::setDefaultCASFamily ( CASFamily  cas)

Set the default CAS family to use.

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

◆ casFamily()

CASFamily ts::DuckContext::casFamily ( CASFamily  cas = CAS_OTHER) const

The actual CAS family to use.

Parameters
[in]casProposed CAS family. If equal to CAS_OTHER, then another value can be returned.
Returns
The actual CAS family 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 = STD_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.

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

◆ defineOptionsForDVBCharset()

void ts::DuckContext::defineOptionsForDVBCharset ( Args args)
inline

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

◆ defineOptionsForPDS()

void ts::DuckContext::defineOptionsForPDS ( 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.

◆ defineOptionsForStandards()

void ts::DuckContext::defineOptionsForStandards ( 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.

◆ defineOptionsForHFBand()

void ts::DuckContext::defineOptionsForHFBand ( 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.

◆ loadOptions()

bool ts::DuckContext::loadOptions ( 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.

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