TSDuck Version 3.15-964 (TSDuck - The MPEG Transport Stream Toolkit)
ts::ProcessorPlugin Class Referenceabstract

Packet processing tsp plugin interface. More...

Inheritance diagram for ts::ProcessorPlugin:
Collaboration diagram for ts::ProcessorPlugin:

Public Types

enum  ArgType {
  NONE,
  STRING,
  INTEGER,
  UNSIGNED,
  POSITIVE,
  UINT8,
  UINT16,
  UINT32,
  PIDVAL,
  INT8,
  INT16,
  INT32,
  TRISTATE
}
 Type of an argument or parameter. More...
 
enum  Flags {
  NO_ERROR_DISPLAY = 0x0001,
  NO_EXIT_ON_ERROR = 0x0002,
  NO_EXIT_ON_HELP = 0x0004,
  NO_EXIT_ON_VERSION = 0x0008,
  GATHER_PARAMETERS = 0x0010,
  HELP_ON_THIS = 0x0020,
  NO_DEBUG = 0x0040,
  NO_HELP = 0x0080,
  NO_VERBOSE = 0x0100,
  NO_VERSION = 0x0200
}
 Args object flags, used in an or'ed mask. More...
 
enum  HelpFormat {
  HELP_NAME,
  HELP_DESCRIPTION,
  HELP_USAGE,
  HELP_SYNTAX,
  HELP_FULL
}
 Types of help formatting, for getHelpText() and predefined option --help. More...
 
enum  Status {
  TSP_OK = 0,
  TSP_END = 1,
  TSP_DROP = 2,
  TSP_NULL = 3
}
 Status of a packet processing. More...
 

Public Member Functions

 ProcessorPlugin (TSP *tsp_, const UString &description=UString(), const UString &syntax=UString())
 Constructor. More...
 
virtual ~ProcessorPlugin ()
 Virtual destructor.
 
virtual bool analyze (int argc, char *argv[], bool processRedirections=true)
 Load command arguments and analyze them. More...
 
virtual bool analyze (const UString &app_name, const UStringVector &arguments, bool processRedirections=true)
 Load command arguments and analyze them. More...
 
UString appName () const
 Get the application name from the last command line analysis. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT bitMaskValue (const UChar *name=0, const INT &def_value=static_cast< INT >(0)) const
 Get an OR'ed of all values of an integer option in the last analyzed command line. More...
 
ArgscopyOptions (const Args &other, const bool replace=false)
 Copy all option definitions from another Args object into this one. More...
 
size_t count (const UChar *name=0) const
 Check the number of occurences of an option in the last analyzed command line. More...
 
bool debug () const
 Check if debugging is active. More...
 
void debug (const UString &msg)
 Report a debug message. More...
 
void debug (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a debug message with a printf-like interface. More...
 
void debug (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a debug message with a printf-like interface. More...
 
template<typename ENUM >
ENUM enumValue (const UChar *name=0, ENUM def_value=static_cast< ENUM >(0), size_t index=0) const
 Get the value of an enum option in the last analyzed command line. More...
 
void error (const UString &msg)
 Report an error message. More...
 
void error (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report an error message with a printf-like interface. More...
 
void error (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report an error message with a printf-like interface. More...
 
void exitOnError (bool force=false)
 Exit application when errors were reported in the last analyzed command line. More...
 
void fatal (const UString &msg)
 Report a fatal error message. More...
 
void fatal (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a fatal error message with a printf-like interface. More...
 
void fatal (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a fatal error message with a printf-like interface. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getBitMaskValue (INT &value, const UChar *name=0, const INT &def_value=static_cast< INT >(0)) const
 Get an OR'ed of all values of an integer option in the last analyzed command line. More...
 
virtual BitRate getBitrate ()
 Get the plugin bitrate. More...
 
const UStringgetDescription () const
 Get the description of the command. More...
 
template<typename ENUM >
void getEnumValue (ENUM &value, const UChar *name=0, ENUM def_value=static_cast< ENUM >(0), size_t index=0) const
 Get the value of an enum option in the last analyzed command line. More...
 
int getFlags () const
 Get the option flags of the command. More...
 
UString getHelpText (HelpFormat format, size_t line_width=79) const
 Get a formatted help text. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getIntValue (INT &value, const UChar *name=0, const INT &def_value=static_cast< INT >(0), size_t index=0) const
 Get the value of an integer option in the last analyzed command line. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getIntValues (std::vector< INT > &values, const UChar *name=0) const
 Get all occurences of an integer option in a vector of integers. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getIntValues (std::set< INT > &values, const UChar *name=0) const
 Get all occurences of an integer option in a set of integers. More...
 
virtual bool getOptions ()
 The main application invokes getOptions() only once, at application startup. More...
 
void getPIDSet (PIDSet &values, const UChar *name=0, bool def_value=false) const
 Get all occurences of an option and interpret them as PID values. More...
 
const UStringgetShell () const
 Get the "shell" string. More...
 
const UStringgetSyntax () const
 Get the syntax of the command. More...
 
void getTristateValue (Tristate &value, const UChar *name=0, size_t index=0) const
 Get the value of tristate option in the last analyzed command line. More...
 
void getValue (UString &value, const UChar *name=0, const UChar *def_value=u"", size_t index=0) const
 Get the value of an option in the last analyzed command line. More...
 
void getValues (UStringVector &values, const UChar *name=0) const
 Get all occurences of an option in a container of strings. More...
 
Argshelp (const UChar *name, const UString &syntax, const UString &text)
 Add the help text of an exiting option. More...
 
Argshelp (const UChar *name, const UString &text)
 Add the help text of an exiting option. More...
 
void info (const UString &msg)
 Report an informational message. More...
 
void info (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report an informational message with a printf-like interface. More...
 
void info (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report an informational message with a printf-like interface. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT intValue (const UChar *name=0, const INT &def_value=static_cast< INT >(0), size_t index=0) const
 Get the value of an integer option in the last analyzed command line. More...
 
void invalidate ()
 Force en error state in this object, as if an error was reported.
 
virtual bool isRealTime ()
 Tell if the plugin is a real time one. More...
 
virtual void log (int severity, const UString &msg)
 Report a message with an explicit severity. More...
 
virtual void log (int severity, const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a message with an explicit severity and a printf-like interface. More...
 
virtual void log (int severity, const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a message with an explicit severity and a printf-like interface. More...
 
int maxSeverity () const
 Get maximum severity level. More...
 
Argsoption (const UChar *name=0, UChar short_name=0, ArgType type=NONE, size_t min_occur=0, size_t max_occur=0, int64_t min_value=0, int64_t max_value=0, bool optional=false)
 Add the definition of an option. More...
 
Argsoption (const UChar *name, UChar short_name, const Enumeration &enumeration, size_t min_occur=0, size_t max_occur=0, bool optional=false)
 Add the definition of an option, the value being from an enumeration type. More...
 
UString optionNames (const UChar *name, const UString &separator=u", ") const
 When an option has an Enumeration type, get a list of all valid names. More...
 
bool present (const UChar *name=0) const
 Check if an option is present in the last analyzed command line. More...
 
bool processArgsRedirection (UStringVector &args)
 Process argument redirection using '@' on a vector of strings. More...
 
virtual Status processPacket (TSPacket &pkt, bool &flush, bool &bitrate_changed)=0
 Packet processing interface. More...
 
virtual void raiseMaxSeverity (int level) override
 Raise maximum severity level. More...
 
void redirectReport (Report *report)
 Redirect report logging. More...
 
virtual void setDescription (const UString &description)
 Set the description of the command. More...
 
virtual void setFlags (int flags)
 Set the option flags of the command. More...
 
virtual void setIntro (const UString &intro)
 Set the introduction or preamble text for help description. More...
 
virtual void setMaxSeverity (int level)
 Set maximum severity level. More...
 
void setShell (const UString &shell)
 Set the "shell" string. More...
 
virtual void setSyntax (const UString &syntax)
 Set the syntax of the command. More...
 
void severe (const UString &msg)
 Report a severe error message. More...
 
void severe (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a severe error message with a printf-like interface. More...
 
void severe (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a severe error message with a printf-like interface. More...
 
virtual size_t stackUsage () const
 Define the maximum stack usage for the thread executing the plugin. More...
 
virtual bool start ()
 The main application invokes start() to start the plugin. More...
 
virtual bool stop ()
 The main application invokes stop() to terminate the plugin. More...
 
Tristate tristateValue (const UChar *name=0, size_t index=0) const
 Get the value of tristate option in the last analyzed command line. More...
 
virtual PluginType type () const override
 Get the plugin type. More...
 
bool valid () const
 Check if options were correct during the last command line analysis. More...
 
UString value (const UChar *name=0, const UChar *def_value=u"", size_t index=0) const
 Get the value of an option in the last analyzed command line. More...
 
bool verbose () const
 Check if verbose reporting is active. More...
 
void verbose (const UString &msg)
 Report a verbose message. More...
 
void verbose (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a verbose message with a printf-like interface. More...
 
void verbose (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a verbose message with a printf-like interface. More...
 
void warning (const UString &msg)
 Report a warning message. More...
 
void warning (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a warning message with a printf-like interface. More...
 
void warning (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a warning message with a printf-like interface. More...
 

Static Public Attributes

static const size_t DEFAULT_STACK_USAGE = 128 * 1024
 Default stack usage in bytes for the thread executing a plugin.
 
static const Enumeration HelpFormatEnum
 Enumeration description of HelpFormat. More...
 
static const size_t UNLIMITED_COUNT
 Unlimited number of occurences. More...
 
static const int64_t UNLIMITED_VALUE
 Unlimited value. More...
 

Protected Member Functions

virtual void writeLog (int severity, const UString &message) override
 Actual message reporting method. More...
 

Protected Attributes

volatile int _max_severity
 Debug level is accessible to subclasses.
 
TSPtsp
 The TSP callback structure can be directly accessed by subclasses.
 

Detailed Description

Packet processing tsp plugin interface.

All shared libraries providing packet processing capability shall return an object implementing this abstract interface.

Member Enumeration Documentation

◆ Status

Status of a packet processing.

Returned by processPacket() after processing one packet.

Enumerator
TSP_OK 

OK, pass packet to next processor or output.

TSP_END 

End of processing, tell everybody to terminate.

TSP_DROP 

Drop this packet.

TSP_NULL 

Replace this packet with a null packet.

◆ Flags

enum ts::Args::Flags
inherited

Args object flags, used in an or'ed mask.

Enumerator
NO_ERROR_DISPLAY 

Don't display errors.

NO_EXIT_ON_ERROR 

Don't terminate application on error.

NO_EXIT_ON_HELP 

Don't terminate application on --help.

NO_EXIT_ON_VERSION 

Don't terminate application on --version.

GATHER_PARAMETERS 

Specifies that all options must be placed before the parameters.

Once the first parameter is found, all subsequent elements on the command line are considered as parameters, even if they start with '-' or '--'.

HELP_ON_THIS 

Display help using info() on this object, not standard error.

NO_DEBUG 

No predefined option "--debug".

NO_HELP 

No predefined option "--help".

NO_VERBOSE 

No predefined option "--verbose".

NO_VERSION 

No predefined option "--version".

◆ ArgType

enum ts::Args::ArgType
inherited

Type of an argument or parameter.

Enumerator
NONE 

Option without argument.

STRING 

Uninterpreted string argument.

INTEGER 

Integer argument, must set min & max values.

UNSIGNED 

Integer 0..unlimited.

POSITIVE 

Integer 1..unlimited.

UINT8 

Integer 0..0xFF.

UINT16 

Integer 0..0xFFFF.

UINT32 

Integer 0..0xFFFFFFFF.

PIDVAL 

Integer 0..0x1FFF (an MPEG PID value).

INT8 

Integer -128..127.

INT16 

Integer -32,768..32,767.

INT32 

Integer -2,147,483,648..2,147,483,647.

TRISTATE 

Tristate value, ts::MAYBE if absent.

◆ HelpFormat

enum ts::Args::HelpFormat
inherited

Types of help formatting, for getHelpText() and predefined option --help.

Enumerator
HELP_NAME 

Application name only.

HELP_DESCRIPTION 

One-line description.

HELP_USAGE 

Formatted command line syntax.

HELP_SYNTAX 

One-line command line syntax.

HELP_FULL 

Full help text.

Constructor & Destructor Documentation

◆ ProcessorPlugin()

ts::ProcessorPlugin::ProcessorPlugin ( TSP tsp_,
const UString description = UString(),
const UString syntax = UString() 
)

Constructor.

Parameters
[in]tsp_Associated callback to tsp executable.
[in]descriptionA short one-line description, eg. "Wonderful File Copier".
[in]syntaxA short one-line syntax summary, eg. "[options] filename ...".

Member Function Documentation

◆ processPacket()

virtual Status ts::ProcessorPlugin::processPacket ( TSPacket pkt,
bool &  flush,
bool &  bitrate_changed 
)
pure virtual

Packet processing interface.

The main application invokes processPacket() to let the shared library process one TS packet.

Dropping packets affect the output bitrate if the output device is a real-time one. With such devices, it is better to replace the undesired packet with a null packet.

Dropping a packet or changing its PID (including replacing a packet with a null one) affects the continuity counters of the other packets of the original PID.

Parameters
[in,out]pktThe TS packet to process.
[in,out]flushInitially set to false. If the method sets flush to true, the packet and all previously processed and buffered packets should be passed to the next processor as soon as possible.
[in,out]bitrate_changedInitially set to false. If the method sets bitrate_changed to true, tsp should call the getBitrate() callback as soon as possible.
Returns
The processing status.

Implemented in ts::AbstractDescrambler, and ts::AbstractTablePlugin.

◆ type()

virtual PluginType ts::ProcessorPlugin::type ( ) const
inlineoverridevirtual

Get the plugin type.

Returns
The plugin type.

Implements ts::Plugin.

◆ stackUsage()

virtual size_t ts::Plugin::stackUsage ( ) const
inlinevirtualinherited

Define the maximum stack usage for the thread executing the plugin.

If the method is not implemented by a subclass, the default value is DEFAULT_STACK_USAGE (128 kB).

Returns
The maximum stack usage in bytes for the thread executing the plugin.

Reimplemented in ts::DektecInputPlugin.

◆ getOptions()

virtual bool ts::Plugin::getOptions ( )
inlinevirtualinherited

The main application invokes getOptions() only once, at application startup.

Optionally implemented by subclasses to analyze the command line options. A plugin may ignore getOptions() and analyzes the command line options as part of the start() method. However, if a plugin is started later, command line errors may be reported too late.

Returns
True on success, false on error (ie. not started).

Reimplemented in ts::DektecInputPlugin.

◆ start()

virtual bool ts::Plugin::start ( )
inlinevirtualinherited

The main application invokes start() to start the plugin.

Optionally implemented by subclasses.

Returns
True on success, false on error (ie. not started).

Reimplemented in ts::PushInputPlugin, ts::AbstractDescrambler, ts::DektecInputPlugin, ts::DektecOutputPlugin, and ts::AbstractTablePlugin.

◆ stop()

virtual bool ts::Plugin::stop ( )
inlinevirtualinherited

The main application invokes stop() to terminate the plugin.

Optionally implemented by subclasses.

Returns
True on success, false on error (ie. not started).

Reimplemented in ts::PushInputPlugin, ts::AbstractDescrambler, ts::DektecInputPlugin, and ts::DektecOutputPlugin.

◆ getBitrate()

virtual BitRate ts::Plugin::getBitrate ( )
inlinevirtualinherited

Get the plugin bitrate.

The main application may invoke getBitrate() at any time. The semantics depends on the capability.

  • Input plugin: Returns the current input bitrate of the device. Useful for real-time devices only.
  • Output plugin: Returns the current output bitrate which is used by the device.
  • Packet processing plugin: Return the current bitrate at the output of the packet processor. This can be used by packet processors which influence the bitrate by removing packets or introducing delays.

Optionally implemented by subclasses. By default, return that the plugin is not aware of the bitrate.

Returns
Plugin bitrate in bits/second. Shall return 0 on error or unknown bitrate.

Reimplemented in ts::DektecInputPlugin, ts::AbstractDescrambler, and ts::DektecOutputPlugin.

◆ isRealTime()

virtual bool ts::Plugin::isRealTime ( )
inlinevirtualinherited

Tell if the plugin is a real time one.

Some plugin behave more accurately when the responsiveness of the environment is more accurate. Typically, input and output on tuners, modulators or ASI devices are real-time plugins. On the opposite, working on offline disk files is not.

This method shall be implemented by real-time plugins and shall return true. The default implementation returns false.

A plugin should be defined as real-time by design, not based on the interpretation of command-line parameters. Typically, the method isRealTime() is invoked before starting the plugin and consequently before the plugin has the opportunity to analyze its command-line parameters.

Returns
True if the plugin usually requires real-time responsiveness.

Reimplemented in ts::DektecInputPlugin, and ts::DektecOutputPlugin.

◆ writeLog()

virtual void ts::Plugin::writeLog ( int  severity,
const UString msg 
)
overrideprotectedvirtualinherited

Actual message reporting method.

Must be implemented in actual classes. The method is called only when a message passed the severity filter. It is not necessary to recheck severity inside the method.

Parameters
[in]severityMessage severity.
[in]msgMessage text.

Reimplemented from ts::Args.

◆ option() [1/2]

Args& ts::Args::option ( const UChar name = 0,
UChar  short_name = 0,
ArgType  type = NONE,
size_t  min_occur = 0,
size_t  max_occur = 0,
int64_t  min_value = 0,
int64_t  max_value = 0,
bool  optional = false 
)
inherited

Add the definition of an option.

This method is typically invoked in the constructor of a subclass.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]short_nameOptional one letter short name.
[in]typeOption or parameter value type.
[in]min_occurMinimum number of occurences of this option on the command line.
[in]max_occurMaximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]min_valueMinimum value, ignored if type is not INTEGER.
[in]max_valueMaximum value, ignored if type is not INTEGER.
[in]optionalWhen true, the option's value is optional.
Returns
A reference to this instance.

◆ option() [2/2]

Args& ts::Args::option ( const UChar name,
UChar  short_name,
const Enumeration enumeration,
size_t  min_occur = 0,
size_t  max_occur = 0,
bool  optional = false 
)
inherited

Add the definition of an option, the value being from an enumeration type.

This method is typically invoked in the constructor of a subclass.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]short_nameOptional one letter short name.
[in]enumerationList of enumeration values. The command line parameter value can be a string describing an enumeration value or directly an integer value. In the application, the option's value is always the integer value of the enumeration value.
[in]min_occurMinimum number of occurences of this option on the command line.
[in]max_occurMaximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]optionalWhen true, the option's value is optional.
Returns
A reference to this instance.

◆ help() [1/2]

Args& ts::Args::help ( const UChar name,
const UString syntax,
const UString text 
)
inherited

Add the help text of an exiting option.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]syntaxString to display for the option value instead of the default "value". For instance: "address:port" "'string'".
[in]textHelp text. Unformatted, line breaks will be added automatically.
Returns
A reference to this instance.

◆ help() [2/2]

Args& ts::Args::help ( const UChar name,
const UString text 
)
inherited

Add the help text of an exiting option.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]textHelp text. Unformatted, line breaks will be added automatically.
Returns
A reference to this instance.

◆ optionNames()

UString ts::Args::optionNames ( const UChar name,
const UString separator = u", " 
) const
inherited

When an option has an Enumeration type, get a list of all valid names.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]separatorThe separator to be used between values, a comma by default.
Returns
A comma-separated list of all possible names.
See also
Enumeration::nameList()

◆ copyOptions()

Args& ts::Args::copyOptions ( const Args other,
const bool  replace = false 
)
inherited

Copy all option definitions from another Args object into this one.

This method is typically invoked in the constructor of a subclass to import all option definitions of another instance.

Parameters
[in]otherAnother instance from which to get the options.
[in]replaceIf true, override duplicated options which were already declared in this object. If false (the default), duplicated options are ignored.
Returns
A reference to this object.

◆ setDescription()

virtual void ts::Args::setDescription ( const UString description)
inlinevirtualinherited

Set the description of the command.

Parameters
[in]descriptionA short one-line description, e.g. "Wonderful File Copier".

◆ setSyntax()

virtual void ts::Args::setSyntax ( const UString syntax)
inlinevirtualinherited

Set the syntax of the command.

Parameters
[in]syntaxA short one-line syntax summary, e.g. "[options] filename ...".

◆ setIntro()

virtual void ts::Args::setIntro ( const UString intro)
inlinevirtualinherited

Set the introduction or preamble text for help description.

Parameters
[in]introIntroduction text.

◆ setFlags()

virtual void ts::Args::setFlags ( int  flags)
inlinevirtualinherited

Set the option flags of the command.

Parameters
[in]flagsDefine various options, a combination of or'ed values from Flags.

◆ getDescription()

const UString& ts::Args::getDescription ( ) const
inlineinherited

Get the description of the command.

Returns
A short one-line description of the command.

◆ getSyntax()

const UString& ts::Args::getSyntax ( ) const
inlineinherited

Get the syntax of the command.

Returns
A short one-line syntax summary of the command.

◆ getFlags()

int ts::Args::getFlags ( ) const
inlineinherited

Get the option flags of the command.

Returns
A combination of or'ed values from Flags.

◆ getHelpText()

UString ts::Args::getHelpText ( HelpFormat  format,
size_t  line_width = 79 
) const
inherited

Get a formatted help text.

Parameters
[in]formatRequested format of the help text.
[in]line_widthMaximum width of text lines.
Returns
The formatted help text.

◆ setShell()

void ts::Args::setShell ( const UString shell)
inlineinherited

Set the "shell" string.

The shell string is an optional prefix for the syntax line as displayed by the --help predefined option. The shell name is displayed before the application name.

Parameters
[in]shellShell name string.

◆ getShell()

const UString& ts::Args::getShell ( ) const
inlineinherited

Get the "shell" string.

Returns
The shell name string.
See also
setShell()

◆ analyze() [1/2]

virtual bool ts::Args::analyze ( int  argc,
char *  argv[],
bool  processRedirections = true 
)
virtualinherited

Load command arguments and analyze them.

Normally, in case of error or if --help or --version is specified, the application is automatically terminated. If some flags prevent the termination of the application, return true if the command is correct, false if the command is incorrect or --help or --version is specified.

Parameters
[in]argcNumber of arguments from command line.
[in]argvArguments from command line. The application name is in argv[0]. The subsequent elements contain the arguments.
[in]processRedirectionsIf true (the default), process command line arguments redirection. All lines with the form '@filename' are replaced by the content of filename.
Returns
By default, always return true or the application is automatically terminated in case of error. If some flags prevent the termination of the application, return true if the command is correct, false if the command is incorrect or --help or --version is specified.

Reimplemented in ts::ArgsWithPlugins.

◆ analyze() [2/2]

virtual bool ts::Args::analyze ( const UString app_name,
const UStringVector arguments,
bool  processRedirections = true 
)
virtualinherited

Load command arguments and analyze them.

Normally, in case of error or if --help or --version is specified, the application is automatically terminated. If some flags prevent the termination of the application, return true if the command is correct, false if the command is incorrect or --help or --version is specified.

Parameters
[in]app_nameApplication name.
[in]argumentsArguments from command line.
[in]processRedirectionsIf true (the default), process command line arguments redirection. All lines with the form '@filename' are replaced by the content of filename.
Returns
By default, always return true or the application is automatically terminated in case of error. If some flags prevent the termination of the application, return true if the command is correct, false if the command is incorrect or --help or --version is specified.

Reimplemented in ts::ArgsWithPlugins.

◆ valid()

bool ts::Args::valid ( ) const
inlineinherited

Check if options were correct during the last command line analysis.

Returns
True if the last analyze() completed successfully.

◆ appName()

UString ts::Args::appName ( ) const
inlineinherited

Get the application name from the last command line analysis.

Returns
The application name from the last command line analysis.

◆ present()

bool ts::Args::present ( const UChar name = 0) const
inherited

Check if an option is present in the last analyzed command line.

Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
Returns
True if the corresponding option or parameter is present on the command line, false otherwise.

◆ count()

size_t ts::Args::count ( const UChar name = 0) const
inherited

Check the number of occurences of an option in the last analyzed command line.

Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
Returns
The number of occurences of the corresponding option or parameter in the command line.

◆ getValue()

void ts::Args::getValue ( UString value,
const UChar name = 0,
const UChar def_value = u"",
size_t  index = 0 
) const
inherited

Get the value of an option in the last analyzed command line.

Parameters
[out]valueA string receiving the value of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
[in]def_valueThe string to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.

◆ value()

UString ts::Args::value ( const UChar name = 0,
const UChar def_value = u"",
size_t  index = 0 
) const
inherited

Get the value of an option in the last analyzed command line.

Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
[in]def_valueThe string to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.
Returns
The value of the option or parameter.

◆ getValues()

void ts::Args::getValues ( UStringVector values,
const UChar name = 0 
) const
inherited

Get all occurences of an option in a container of strings.

Parameters
[out]valuesA container of strings receiving all values of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.

◆ getPIDSet()

void ts::Args::getPIDSet ( PIDSet values,
const UChar name = 0,
bool  def_value = false 
) const
inherited

Get all occurences of an option and interpret them as PID values.

Parameters
[out]valuesA set of PID's receiving all values of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
[in]def_valueThe boolean to set in all PID values if the option or parameter is not present in the command line.

◆ getIntValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Args::getIntValue ( INT value,
const UChar name = 0,
const INT def_value = static_cast< INT >(0),
size_t  index = 0 
) const
inherited

Get the value of an integer option in the last analyzed command line.

If the option has been declared with an integer type in the syntax of the command, the validity of the supplied option value has been checked by the analyze() method. If analyze() did not fail, the option value is guaranteed to be in the declared range.

Template Parameters
INTAn integer type for the result.
Parameters
[out]valueA variable receiving the integer value of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.

◆ intValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT ts::Args::intValue ( const UChar name = 0,
const INT def_value = static_cast< INT >(0),
size_t  index = 0 
) const
inherited

Get the value of an integer option in the last analyzed command line.

Template Parameters
INTAn integer type for the result.
Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.
Returns
The integer value of the option or parameter.

◆ getIntValues() [1/2]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Args::getIntValues ( std::vector< INT > &  values,
const UChar name = 0 
) const
inherited

Get all occurences of an integer option in a vector of integers.

Parameters
[out]valuesA container of integers receiving all values of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.

◆ getIntValues() [2/2]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Args::getIntValues ( std::set< INT > &  values,
const UChar name = 0 
) const
inherited

Get all occurences of an integer option in a set of integers.

Parameters
[out]valuesA container of integers receiving all values of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.

◆ bitMaskValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT ts::Args::bitMaskValue ( const UChar name = 0,
const INT def_value = static_cast< INT >(0) 
) const
inherited

Get an OR'ed of all values of an integer option in the last analyzed command line.

This method is typically useful when the values of an option are taken from an Enumeration and each value is a bit mask. When specifying several values, the result of this method is a mask of all specified options.

Template Parameters
INTAn integer type for the result.
Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return in value if the option or parameter is not present in the command line.
Returns
The OR'ed values of the integer option.

◆ getBitMaskValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Args::getBitMaskValue ( INT value,
const UChar name = 0,
const INT def_value = static_cast< INT >(0) 
) const
inherited

Get an OR'ed of all values of an integer option in the last analyzed command line.

This method is typically useful when the values of an option are taken from an Enumeration and each value is a bit mask. When specifying several values, the result of this method is a mask of all specified options.

Template Parameters
INTAn integer type for the result.
Parameters
[out]valueA variable receiving the OR'ed values of the integer option.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return in value if the option or parameter is not present in the command line.

◆ getEnumValue()

template<typename ENUM >
void ts::Args::getEnumValue ( ENUM &  value,
const UChar name = 0,
ENUM  def_value = static_cast< ENUM >(0),
size_t  index = 0 
) const
inherited

Get the value of an enum option in the last analyzed command line.

Typically used when the option was declared using an Enumeration object.

Template Parameters
ENUMAn enumeration type for the result.
Parameters
[out]valueA variable receiving the enum value of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.

◆ enumValue()

template<typename ENUM >
ENUM ts::Args::enumValue ( const UChar name = 0,
ENUM  def_value = static_cast< ENUM >(0),
size_t  index = 0 
) const
inherited

Get the value of an enum option in the last analyzed command line.

Typically used when the option was declared using an Enumeration object.

Template Parameters
ENUMAn enumeration type for the result.
Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.
Returns
The enum value of the option or parameter.

◆ getTristateValue()

void ts::Args::getTristateValue ( Tristate value,
const UChar name = 0,
size_t  index = 0 
) const
inherited

Get the value of tristate option in the last analyzed command line.

Parameters
[out]valueA variable receiving the tristate value of the option or parameter. The returned value is always one of the three valid Tristate values. When the option or parameter is not present in the command line or with fewer occurences than index, the returned value is MAYBE. For options with optional values, if the the option is present without value, the returned value is TRUE.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]indexThe occurence of the option to return. Zero designates the first occurence.

◆ tristateValue()

Tristate ts::Args::tristateValue ( const UChar name = 0,
size_t  index = 0 
) const
inherited

Get the value of tristate option in the last analyzed command line.

Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]indexThe occurence of the option to return. Zero designates the first occurence.
Returns
The tristate value of the option or parameter. The returned value is always one of the three valid Tristate values. When the option or parameter is not present in the command line or with fewer occurences than index, the returned value is MAYBE. For options with optional values, if the the option is present without value, the returned value is TRUE.

◆ exitOnError()

void ts::Args::exitOnError ( bool  force = false)
inherited

Exit application when errors were reported in the last analyzed command line.

Parameters
[in]forceIf true, ignore flag NO_EXIT_ON_ERROR and force application termination on error.

◆ redirectReport()

void ts::Args::redirectReport ( Report report)
inherited

Redirect report logging.

Parameters
[in]reportWhere to report errors. The redirection is cancelled if zero.

◆ raiseMaxSeverity()

virtual void ts::Args::raiseMaxSeverity ( int  level)
overridevirtualinherited

Raise maximum severity level.

Parameters
[in]levelSet report at least to that level.

Reimplemented from ts::Report.

◆ processArgsRedirection()

bool ts::Args::processArgsRedirection ( UStringVector args)
inherited

Process argument redirection using '@' on a vector of strings.

Parameters
[in,out]argsA vector of strings. All lines of the form '@filename' are replaced by the content of the given file. A double '@@' at the beginning of a line is replaced by a single '@' without reading a file.
Returns
True on success, false on error (non existent file for instance). Errors are reported though this object.

◆ setMaxSeverity()

virtual void ts::Report::setMaxSeverity ( int  level)
virtualinherited

Set maximum severity level.

Messages with higher severities are not reported.

Parameters
[in]levelSet report to that level.

◆ maxSeverity()

int ts::Report::maxSeverity ( ) const
inlineinherited

Get maximum severity level.

Returns
Current maximum debug level.

◆ debug() [1/4]

bool ts::Report::debug ( ) const
inlineinherited

Check if debugging is active.

Returns
True if current reporting level is Debug or higher.

◆ debug() [2/4]

void ts::Report::debug ( const UString msg)
inlineinherited

Report a debug message.

Parameters
[in]msgMessage text.

◆ debug() [3/4]

void ts::Report::debug ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a debug message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ debug() [4/4]

void ts::Report::debug ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a debug message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ verbose() [1/4]

bool ts::Report::verbose ( ) const
inlineinherited

Check if verbose reporting is active.

Returns
True if current reporting level is Verbose or higher.

◆ verbose() [2/4]

void ts::Report::verbose ( const UString msg)
inlineinherited

Report a verbose message.

Parameters
[in]msgMessage text.

◆ verbose() [3/4]

void ts::Report::verbose ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a verbose message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ verbose() [4/4]

void ts::Report::verbose ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a verbose message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ log() [1/3]

virtual void ts::Report::log ( int  severity,
const UString msg 
)
virtualinherited

Report a message with an explicit severity.

This method is the central reporting point. If filters the severity and drops the message if severity is higher than maxSeverity().

Subclasses should override writeLog() to implement a specific reporting device. It is not necessary to override log() unless the subclass needs to implement a different severity filtering policy.

Parameters
[in]severityMessage severity.
[in]msgMessage text.

◆ log() [2/3]

virtual void ts::Report::log ( int  severity,
const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
virtualinherited

Report a message with an explicit severity and a printf-like interface.

Parameters
[in]severityMessage severity.
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ log() [3/3]

virtual void ts::Report::log ( int  severity,
const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
virtualinherited

Report a message with an explicit severity and a printf-like interface.

Parameters
[in]severityMessage severity.
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ fatal() [1/3]

void ts::Report::fatal ( const UString msg)
inlineinherited

Report a fatal error message.

Parameters
[in]msgMessage text.

◆ fatal() [2/3]

void ts::Report::fatal ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a fatal error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ fatal() [3/3]

void ts::Report::fatal ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a fatal error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ severe() [1/3]

void ts::Report::severe ( const UString msg)
inlineinherited

Report a severe error message.

Parameters
[in]msgMessage text.

◆ severe() [2/3]

void ts::Report::severe ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a severe error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ severe() [3/3]

void ts::Report::severe ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a severe error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ error() [1/3]

void ts::Report::error ( const UString msg)
inlineinherited

Report an error message.

Parameters
[in]msgMessage text.

◆ error() [2/3]

void ts::Report::error ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report an error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ error() [3/3]

void ts::Report::error ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report an error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ warning() [1/3]

void ts::Report::warning ( const UString msg)
inlineinherited

Report a warning message.

Parameters
[in]msgMessage text.

◆ warning() [2/3]

void ts::Report::warning ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a warning message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ warning() [3/3]

void ts::Report::warning ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a warning message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ info() [1/3]

void ts::Report::info ( const UString msg)
inlineinherited

Report an informational message.

Parameters
[in]msgMessage text.

◆ info() [2/3]

void ts::Report::info ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report an informational message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ info() [3/3]

void ts::Report::info ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report an informational message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

Member Data Documentation

◆ UNLIMITED_COUNT

const size_t ts::Args::UNLIMITED_COUNT
staticinherited

Unlimited number of occurences.

To be used as value for parameter max_occur to indicate that there is no limit to the number of occurences of an option.

Warning: use only for max_occur (size_t ). Do not use for max_value (int64_t ) since size_t is uint64_t on 64-bit platforms.

◆ UNLIMITED_VALUE

const int64_t ts::Args::UNLIMITED_VALUE
staticinherited

Unlimited value.

To be used as value for parameter @ max_value to indicate that there is no limit to the parameter integer value.

◆ HelpFormatEnum

const Enumeration ts::Args::HelpFormatEnum
staticinherited

Enumeration description of HelpFormat.

Typically used to implement the --help command line option.


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