ts::PushInputPlugin Class Reference

Abstract superclass for input tsp plugins working in push mode. More...

#include <tsPushInputPlugin.h>

Inheritance diagram for ts::PushInputPlugin:

Collaboration diagram for ts::PushInputPlugin:

Public Types
enum	ArgType {   NONE ,   STRING ,   FILENAME ,   DIRECTORY ,   HEXADATA ,   INTEGER ,   UNSIGNED ,   POSITIVE ,   UINT8 ,   UINT16 ,   UINT32 ,   UINT63 ,   PIDVAL ,   INT8 ,   INT16 ,   INT32 ,   INT64 ,   ANUMBER ,   CHRONO ,   TRISTATE ,   IPADDR ,   IPSOCKADDR ,   IPSOCKADDR_OA ,   IPSOCKADDR_OP ,   IPSOCKADDR_OAP }
	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 ,   NO_CONFIG_FILE = 0x0400 }
	Args object flags, used in an or'ed mask. More...
enum	HelpFormat {   HELP_NAME ,   HELP_DESCRIPTION ,   HELP_USAGE ,   HELP_SYNTAX ,   HELP_FULL ,   HELP_OPTIONS }
	Types of help formatting, for getHelpText() and predefined option --help. More...

Public Member Functions
virtual	~PushInputPlugin () override
	Destructor.
virtual bool	analyze (const UString &app_name, const UStringVector &arguments, bool processRedirections=true)
	Load command arguments and analyze them.
virtual bool	analyze (const UString &command, bool processRedirections=true)
	Load command arguments and analyze them.
virtual bool	analyze (int argc, char *argv[], bool processRedirections=true)
	Load command arguments and analyze them.
UString	appName () const
	Get the application name from the last command line analysis.
template<typename INT > requires std::integral<INT>
INT	bitMaskValue (const UChar *name=nullptr, 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.
UString	commandLine () const
	Get the full command line from the last command line analysis.
Args &	copyOptions (const Args &other, const bool replace=false)
	Copy all option definitions from another Args object into this one.
size_t	count (const UChar *name=nullptr) const
	Check the number of occurences of an option in the last analyzed command line.
bool	debug () const
	Check if debugging is active.
template<class... Args>
void	debug (const UChar *fmt, Args &&... args)
	Report a debug message with a printf-like interface.
void	debug (const UChar *msg)
	Report a debug message.
template<class... Args>
void	debug (const UString &fmt, Args &&... args)
	Report a debug message with a printf-like interface.
void	debug (const UString &msg)
	Report a debug message.
Report *	delegateReport (Report *report)
	Delegate message logging to another report object.
template<class... Args>
void	error (const UChar *fmt, Args &&... args)
	Report an error message with a printf-like interface.
void	error (const UChar *msg)
	Report an error message.
template<class... Args>
void	error (const UString &fmt, Args &&... args)
	Report an error message with a printf-like interface.
void	error (const UString &msg)
	Report an error message.
void	exitOnError (bool force=false)
	Exit application when errors were reported in the last analyzed command line.
template<class... Args>
void	fatal (const UChar *fmt, Args &&... args)
	Report a fatal error message with a printf-like interface.
void	fatal (const UChar *msg)
	Report a fatal error message.
template<class... Args>
void	fatal (const UString &fmt, Args &&... args)
	Report a fatal error message with a printf-like interface.
void	fatal (const UString &msg)
	Report a fatal error message.
template<typename INT > requires std::integral<INT>
void	getBitMaskValue (INT &value, const UChar *name=nullptr, 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.
virtual BitRate	getBitrate ()
	Get the plugin bitrate.
virtual BitRateConfidence	getBitrateConfidence ()
	Get the plugin bitrate confidence.
template<class Rep , class Period >
void	getChronoValue (cn::duration< Rep, Period > &value, const UChar *name=nullptr, size_t index=0) const
	Get the value of an std::chrono::duration option in the last analyzed command line.
template<class Rep1 , class Period1 , class Rep2 , class Period2 >
void	getChronoValue (cn::duration< Rep1, Period1 > &value, const UChar *name=nullptr, const cn::duration< Rep2, Period2 > &def_value=cn::duration< Rep1, Period1 >::zero(), size_t index=0) const
	Get the value of an std::chrono::duration option in the last analyzed command line.
void	getCommandArgs (UStringVector &args) const
	Get the command line parameters from the last command line analysis.
const UString &	getDescription () const
	Get the description of the command.
int	getFlags () const
	Get the option flags of the command.
virtual UString	getHelpText (HelpFormat format, size_t line_width=DEFAULT_LINE_WIDTH) const
	Get a formatted help text.
void	getHexaValue (ByteBlock &value, const UChar *name=nullptr, const ByteBlock &def_value=ByteBlock(), size_t index=0) const
	Get the value of an hexadecimal option in the last analyzed command line.
template<typename INT , typename INT2 = INT> requires ts::int_enum<INT> && ts::int_enum<INT2>
void	getIntValue (INT &value, const UChar *name=nullptr, const INT2 def_value=static_cast< INT2 >(0), size_t index=0) const
	Get the value of an integer option in the last analyzed command line.
template<std::size_t N>
void	getIntValues (CompactBitSet< N > &values, const UChar *name=nullptr, bool defValue=false) const
	Get all occurences of an option as a compact bitset of values.
template<std::size_t N>
void	getIntValues (std::bitset< N > &values, const UChar *name=nullptr, bool defValue=false) const
	Get all occurences of an option as a bitset of values.
template<typename INT > requires ts::int_enum<INT>
void	getIntValues (std::set< INT > &values, const UChar *name=nullptr) const
	Get all occurences of an integer option in a set of integers.
template<typename INT > requires ts::int_enum<INT>
void	getIntValues (std::vector< INT > &values, const UChar *name=nullptr) const
	Get all occurences of an integer option in a vector of integers.
void	getIPValue (IPAddress &value, const UChar *name=nullptr, const IPAddress &def_value=IPAddress(), size_t index=0) const
	Get the value of an option as an IP address in the last analyzed command line.
template<typename INT > requires ts::int_enum<INT>
void	getOptionalIntValue (std::optional< INT > &value, const UChar *name=nullptr, bool clear_if_absent=false) const
	Get the value of an integer option in the last analyzed command line, only if present.
void	getOptionalValue (std::optional< UString > &value, const UChar *name=nullptr, bool clear_if_absent=false) const
	Get the value of an option in the last analyzed command line, only if present.
virtual bool	getOptions ()
	The main application invokes getOptions() only once, at application startup.
void	getPathValue (fs::path &value, const UChar *name=nullptr, const fs::path &def_value=fs::path(), size_t index=0) const
	Get the value of a filesystem path option in the last analyzed command line.
template<class CONTAINER > requires std::derived_from<typename CONTAINER::value_type, fs::path>
void	getPathValues (CONTAINER &values, const UChar *name=nullptr) const
	Get all occurences of a filesystem path option in a container of path.
const UString &	getShell () const
	Get the "shell" string.
void	getSocketValue (IPSocketAddress &value, const UChar *name=nullptr, const IPSocketAddress &def_value=IPSocketAddress(), size_t index=0) const
	Get the value of an option as an IP socket address in the last analyzed command line.
const UString &	getSyntax () const
	Get the syntax of the command.
void	getTristateValue (Tristate &value, const UChar *name=nullptr, size_t index=0) const
	Get the value of tristate option in the last analyzed command line.
template<class NUMTYPE , typename INT1 > requires std::derived_from<NUMTYPE, AbstractNumber> && std::integral<INT1>
void	getValue (NUMTYPE &value, const UChar *name, INT1 def_value, size_t index=0) const
	Get the value of an AbstractNumber option in the last analyzed command line.
template<class NUMTYPE > requires std::derived_from<NUMTYPE, ts::AbstractNumber>
void	getValue (NUMTYPE &value, const UChar *name=nullptr, const NUMTYPE &def_value=NUMTYPE(0), size_t index=0) const
	Get the value of an AbstractNumber option in the last analyzed command line.
void	getValue (UString &value, const UChar *name=nullptr, const UChar *def_value=u"", size_t index=0) const
	Get the value of an option in the last analyzed command line.
template<class CONTAINER > requires std::derived_from<typename CONTAINER::value_type, ts::UString>
void	getValues (CONTAINER &values, const UChar *name=nullptr) const
	Get all occurences of an option in a container of strings.
bool	gotErrors () const
	Check if errors (or worse) were reported through this object.
virtual bool	handlePacketTimeout ()
	Invoked when no packet could be retrieved within the specified timeout.
Args &	help (const UChar *name, const UString &syntax, const UString &text)
	Add the help text of an existing option.
Args &	help (const UChar *name, const UString &text)
	Add the help text of an existing option.
ByteBlock	hexaValue (const UChar *name=nullptr, const ByteBlock &def_value=ByteBlock(), size_t index=0) const
	Get the value of an hexadecimal option in the last analyzed command line.
template<class... Args>
void	info (const UChar *fmt, Args &&... args)
	Report an informational message with a printf-like interface.
void	info (const UChar *msg)
	Report an informational message.
template<class... Args>
void	info (const UString &fmt, Args &&... args)
	Report an informational message with a printf-like interface.
void	info (const UString &msg)
	Report an informational message.
template<typename INT > requires ts::int_enum<INT>
INT	intValue (const UChar *name=nullptr, 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.
void	invalidate ()
	Force en error state in this object, as if an error was reported.
IPAddress	ipValue (const UChar *name=nullptr, const IPAddress &def_value=IPAddress(), size_t index=0) const
	Get the value of an option as an IP address in the last analyzed command line.
virtual bool	isRealTime ()
	Tell if the plugin is a real time one.
template<class... Args>
void	log (int severity, const UChar *fmt, Args &&... args)
	Report a message with an explicit severity and a printf-like interface.
template<class... Args>
void	log (int severity, const UString &fmt, Args &&... args)
	Report a message with an explicit severity and a printf-like interface.
void	log (int severity, const UString &msg)
	Report a message with an explicit severity.
int	maxSeverity () const
	Get maximum severity level.
template<class NUMTYPE > requires std::derived_from<NUMTYPE, ts::AbstractNumber>
NUMTYPE	numValue (const UChar *name=nullptr, const NUMTYPE &def_value=NUMTYPE(0), size_t index=0) const
	Get the value of an AbstractNumber option in the last analyzed command line.
Args &	option (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.
template<class NUMTYPE , typename INT1 = int64_t, typename INT2 = int64_t> requires std::derived_from<NUMTYPE, AbstractNumber> && std::integral<INT1> && std::integral<INT2>
Args &	option (const UChar *name, UChar short_name=0, size_t min_occur=0, size_t max_occur=0, INT1 min_value=std::numeric_limits< INT2 >::min(), INT2 max_value=std::numeric_limits< INT1 >::max(), bool optional=false)
	Add the definition of an option, the value being an instance of AbstractNumber.
template<class DURATION > requires std::integral<typename DURATION::rep>
Args &	option (const UChar *name, UChar short_name=0, size_t min_occur=0, size_t max_occur=0, int64_t min_value=0, int64_t max_value=std::numeric_limits< int64_t >::max(), bool optional=false)
	Add the definition of an option, the value being an instance of std::chrono::duration.
Args &	option (const UChar *name=nullptr, 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, size_t decimals=0)
	Add the definition of an option.
UString	optionNames (const UChar *name, const UString &separator=u", ") const
	When an option has an Enumeration type, get a list of all valid names.
bool	present (const UChar *name=nullptr) const
	Check if an option is present in the last analyzed command line.
bool	processArgsRedirection (UStringVector &args)
	Process argument redirection using '@' on a vector of strings.
void	raiseMaxSeverity (int level)
	Raise maximum severity level.
UString	reportPrefix () const
	Get the current prefix to display.
void	resetContext (const DuckContext::SavedArgs &state)
	Reset the internal TSDuck execution context of this plugin.
void	resetErrors ()
	Reset the error indicator.
void	setAppName (const UString &name)
	Set the initial application name (will be overwritten at next command analysis).
virtual void	setDescription (const UString &description)
	Set the description of the command.
virtual void	setFlags (int flags)
	Set the option flags of the command.
virtual void	setIntro (const UString &intro)
	Set the introduction or preamble text for help description.
void	setMaxSeverity (int level)
	Set maximum severity level.
virtual bool	setReceiveTimeout (cn::milliseconds timeout)
	Set a receive timeout for all input operations.
void	setReportPrefix (const UString &prefix)
	Set the prefix to display before each message.
void	setShell (const UString &shell)
	Set the "shell" string.
virtual void	setSyntax (const UString &syntax)
	Set the syntax of the command.
virtual void	setTail (const UString &tail)
	Set the conclusion or tailing text for help description.
template<class... Args>
void	severe (const UChar *fmt, Args &&... args)
	Report a severe error message with a printf-like interface.
void	severe (const UChar *msg)
	Report a severe error message.
template<class... Args>
void	severe (const UString &fmt, Args &&... args)
	Report a severe error message with a printf-like interface.
void	severe (const UString &msg)
	Report a severe error message.
IPSocketAddress	socketValue (const UChar *name=nullptr, const IPSocketAddress &def_value=IPSocketAddress(), size_t index=0) const
	Get the value of an option as an IP socket address in the last analyzed command line.
virtual size_t	stackUsage () const
	Define the maximum stack usage for the thread executing the plugin.
Tristate	tristateValue (const UChar *name=nullptr, size_t index=0) const
	Get the value of tristate option in the last analyzed command line.
virtual PluginType	type () const override
	Get the plugin type.
bool	valid () const
	Check if options were correct during the last command line analysis.
UString	value (const UChar *name=nullptr, const UChar *def_value=u"", size_t index=0) const
	Get the value of an option in the last analyzed command line.
bool	verbose () const
	Check if verbose reporting is active.
template<class... Args>
void	verbose (const UChar *fmt, Args &&... args)
	Report a verbose message with a printf-like interface.
void	verbose (const UChar *msg)
	Report a verbose message.
template<class... Args>
void	verbose (const UString &fmt, Args &&... args)
	Report a verbose message with a printf-like interface.
void	verbose (const UString &msg)
	Report a verbose message.
template<class... Args>
void	warning (const UChar *fmt, Args &&... args)
	Report a warning message with a printf-like interface.
void	warning (const UChar *msg)
	Report a warning error message.
template<class... Args>
void	warning (const UString &fmt, Args &&... args)
	Report a warning message with a printf-like interface.
void	warning (const UString &msg)
	Report a warning error message.

Static Public Member Functions
static UString	GetAppName (int argc, char *argv[])
	Get the application name from a standard argc/argv pair.

Static Public Attributes
static constexpr size_t	DEFAULT_LINE_WIDTH = 79
	Default line width for help texts.
static constexpr 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.
static constexpr size_t	UNLIMITED_COUNT = std::numeric_limits<size_t>::max()
	Unlimited number of occurences.
static const int64_t	UNLIMITED_VALUE = std::numeric_limits<int64_t>::max()
	Unlimited value.

Protected Member Functions
	PushInputPlugin (TSP *tsp_, const UString &description=UString(), const UString &syntax=UString())
	Constructor.
virtual bool	abortInput () override
	Abort the input operation currently in progress.
bool	isInterrupted () const
	Invoked by subclass, typically in processInput(), to check if the plugin was interrupted on purpose.
virtual void	processInput ()=0
	Packet reception interface.
virtual bool	pushPackets (const TSPacket *buffer, const TSPacketMetadata *mdata, size_t count)
	Push packet to the tsp chain.
void	setQueueSize (size_t count)
	Tune the TS packet buffer between the "push" subclass and the "pull" superclass.
virtual bool	start () override
	Plugin start method.
virtual bool	stop () override
	Plugin stop method.
virtual void	writeLog (int severity, const UString &message) override
	Actual message reporting method.

Protected Attributes
DuckContext	duck
	The TSDuck context with various MPEG/DVB features.
TSP *const	tsp
	The TSP callback structure can be directly accessed by subclasses.

Detailed Description

Abstract superclass for input tsp plugins working in push mode.

An input plugin works in "pull" mode by default. When tsp needs mode input packets, it calls the receive() method of the plugin to "pull" packets.

Some input devices, however, naturally work in "push" mode. Some code loops and pushes new packets somewhere when some are available. When this looping or dispatching code is a third-party one, it is impossible to modify it and make is work in pull mode.

This class is a bridge between push mode and pull mode. Input plugins which prefer to work in push mode should inherit from this class.

Note: This class was originally developed to support HTTP-based input plugins. Because the "curl_easy" interface was used on Unix, these plugins had to work in push mode. Now, we use these plugins use the "curl_multi" interface and the PushInputPlugin is no longer used in TSDuck. It remains here jsut in case some future input plugin has to work in push mode.

Member Enumeration Documentation

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".
NO_CONFIG_FILE	No default option from the configuration file.

ArgType

enum ts::Args::ArgType

inherited

Type of an argument or parameter.

Enumerator
NONE	Option without argument.
STRING	Uninterpreted string argument.
FILENAME	String argument which will be interpreted as a file name.
DIRECTORY	String argument which will be interpreted as a directory name.
HEXADATA	String argument which will be interpreted as a suite of hexadecimal digits.
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.
UINT63	63-bit unsigned (cannot represent 2^63 and higher).
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.
INT64	64-bit signed.
ANUMBER	A subclass of AbstractNumber.
CHRONO	Any instantiation of std::chrono::duration.
TRISTATE	Tristate value, ts::Maybe if absent.
IPADDR	IP address or host name translating to an address.
IPSOCKADDR	IP socket address (or host name) and port, both are mandatory.
IPSOCKADDR_OA	IP socket address (or host name) and port, address is optional.
IPSOCKADDR_OP	IP socket address (or host name) and port, port is optional.
IPSOCKADDR_OAP	IP socket address (or host name) and port, address and port are optional.

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.
HELP_OPTIONS	Options names, one by line.

Constructor & Destructor Documentation

PushInputPlugin()

ts::PushInputPlugin::PushInputPlugin ( TSP *  tsp_, const UString &  description = UString(), const UString &  syntax = UString()  )

protected

Constructor.

Parameters

[in]	tsp_	Associated callback to tsp executable.
[in]	description	A short one-line description, eg. "Wonderful File Copier".
[in]	syntax	A short one-line syntax summary, eg. "[options] filename ...".

Member Function Documentation

processInput()

virtual void ts::PushInputPlugin::processInput ( )

protectedpure virtual

Packet reception interface.

The concrete class shall implement this method to process input. This method is called only once and should loop until end of input. When packets are available, processInput() shall invoke pushPackets().

This method shall return immediately in any of the following cases:

• End of input.
• pushPackets() returns false, meaning that termination is requested.
• tsp->aborting() return true, meaning that the program was interrupted.
• Unrecoverable input error.

start()

virtual bool ts::PushInputPlugin::start ( )

overrideprotectedvirtual

Plugin start method.

If a subclass overrides start(), it should invoke the superclass at the beginning of its start() method.

Returns

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

Reimplemented from ts::Plugin.

stop()

virtual bool ts::PushInputPlugin::stop ( )

overrideprotectedvirtual

Plugin stop method.

If a subclass overrides stop(), it should invoke the superclass at the end of its stop() method.

Returns

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

Reimplemented from ts::Plugin.

setQueueSize()

void ts::PushInputPlugin::setQueueSize ( size_t  count )

protected

Tune the TS packet buffer between the "push" subclass and the "pull" superclass.

This method must be called from the start() method in the superclass.

Parameters

[in]

count

Size of the intermediate buffer in packets.

pushPackets()

virtual bool ts::PushInputPlugin::pushPackets ( const TSPacket *  buffer, const TSPacketMetadata *  mdata, size_t  count  )

protectedvirtual

Push packet to the tsp chain.

This method must be called from the processInput() method in the superclass.

Parameters

[in]	buffer	Address of the buffer containing incoming packets.
[in]	mdata	Address of the buffer containing incoming packets metadata.
[in]	count	Size of buffer in number of packets.

Returns

True on success, false on error or requested termination.

abortInput()

virtual bool ts::PushInputPlugin::abortInput ( )

overrideprotectedvirtual

Abort the input operation currently in progress.

This method is typically invoked from another thread when the input plugin is waiting for input. When this method is invoked, the plugin shall abort the current input and place the input plugin in some "error" or "end of input" state. The only acceptable operation after an abortInput() is a stop().

Returns

True when the operation was properly handled. False in case of fatal error or if not supported by the plugin.

Reimplemented from ts::InputPlugin.

isInterrupted()

bool ts::PushInputPlugin::isInterrupted ( ) const

inlineprotected

Invoked by subclass, typically in processInput(), to check if the plugin was interrupted on purpose.

Returns

True if the plugin was interrupted on purpose.

setReceiveTimeout()

virtual bool ts::InputPlugin::setReceiveTimeout ( cn::milliseconds  timeout )

virtualinherited

Set a receive timeout for all input operations.

This method is typically invoked from tsp before starting the plugin.

Parameters

[in]

timeout

Receive timeout in milliseconds. No timeout if zero or negative.

Returns

True when the timeout is accepted, false if not supported by the plugin.

Reimplemented in ts::DektecInputPlugin, ts::AbstractHTTPInputPlugin, ts::IPInputPlugin, ts::NullInputPlugin, and ts::RISTInputPlugin.

type()

virtual PluginType ts::InputPlugin::type ( ) const

overridevirtualinherited

Get the plugin type.

Returns

The plugin type.

Implements ts::Plugin.

stackUsage()

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

virtualinherited

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

virtualinherited

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, ts::AbstractDatagramInputPlugin, ts::AbstractDescrambler, ts::AbstractDuplicateRemapPlugin, ts::AbstractHTTPInputPlugin, ts::AbstractTablePlugin, ts::DebugPlugin, ts::FileInputPlugin, ts::FileOutputPlugin, ts::FilePacketPlugin, ts::ForkInputPlugin, ts::ForkOutputPlugin, ts::ForkPacketPlugin, ts::hls::InputPlugin, ts::hls::OutputPlugin, ts::HTTPInputPlugin, ts::HTTPOutputPlugin, ts::IPInputPlugin, ts::IPOutputPlugin, ts::IPPacketPlugin, ts::MemoryInputPlugin, ts::MemoryOutputPlugin, ts::NullInputPlugin, ts::PSIPlugin, ts::RISTInputPlugin, ts::RISTOutputPlugin, ts::SkipPlugin, ts::SRTInputPlugin, ts::SRTOutputPlugin, and ts::TablesPlugin.

getBitrate()

virtual BitRate ts::Plugin::getBitrate ( )

virtualinherited

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::DektecOutputPlugin, ts::AbstractDatagramInputPlugin, and ts::VatekOutputPlugin.

getBitrateConfidence()

virtual BitRateConfidence ts::Plugin::getBitrateConfidence ( )

virtualinherited

Get the plugin bitrate confidence.

When a subclass overrides getBitrate(), it should also override getBitrateConfidence().

Returns

The level of confidence of the bitrate value as returned by the previous call to getBitrate(). If the previous returned bitrate was zero, this confidence level shall be ignored.

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

isRealTime()

virtual bool ts::Plugin::isRealTime ( )

virtualinherited

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, ts::DektecOutputPlugin, ts::AbstractDatagramInputPlugin, ts::hls::InputPlugin, ts::hls::OutputPlugin, ts::IPOutputPlugin, ts::IPPacketPlugin, ts::RISTInputPlugin, ts::RISTOutputPlugin, ts::SRTOutputPlugin, and ts::VatekOutputPlugin.

handlePacketTimeout()

virtual bool ts::Plugin::handlePacketTimeout ( )

virtualinherited

Invoked when no packet could be retrieved within the specified timeout.

For input plugins, this method is called when no space in input buffer can be found within the specified timeout.

Returns

True if the application should continue to wait, false to abort. The default implementation aborts (but the default timeout is infinite).

resetContext()

void ts::Plugin::resetContext ( const DuckContext::SavedArgs &  state )

inherited

Reset the internal TSDuck execution context of this plugin.

This can be done to set default option values before getOptions() and start(). This can also be done between stop() and start() to enforce a clean restart.

Parameters

[in]

state

Initial state to set or restore.

option() [1/4]

Args & ts::Args::option ( const UChar *  name = nullptr, 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, size_t  decimals = 0  )

inlineinherited

Add the definition of an option.

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

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	short_name	Optional one letter short name.
[in]	type	Option or parameter value type.
[in]	min_occur	Minimum number of occurences of this option on the command line, ignored if type is NONE.
[in]	max_occur	Maximum number of occurences, ignored if type is NONE, 0 means default (1 for an option, unlimited for a parameters).
[in]	min_value	Minimum value for integer, minimum size for string and hexa data.
[in]	max_value	Maximum value for integer, maximum size for string and hexa data.
[in]	optional	When true, the option's value is optional.
[in]	decimals	Reference number of decimal digits. When decimals is greater than zero, the result is automatically adjusted by the corresponding power of ten. For instance, when decimals is 3, u"12" returns 12000, u"12.34" returns 12340 and "12.345678" returns 12345. All extra decimals are accepted but ignored.

Returns

A reference to this instance.

option() [2/4]

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  )

inlineinherited

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]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	short_name	Optional one letter short name.
[in]	enumeration	List 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_occur	Minimum number of occurences of this option on the command line.
[in]	max_occur	Maximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]	optional	When true, the option's value is optional.

Returns

A reference to this instance.

option() [3/4]

template<class NUMTYPE , typename INT1 = int64_t, typename INT2 = int64_t>
requires std::derived_from<NUMTYPE, AbstractNumber> && std::integral<INT1> && std::integral<INT2>

Args & ts::Args::option ( const UChar *  name, UChar  short_name = 0, size_t  min_occur = 0, size_t  max_occur = 0, INT1  min_value = std::numeric_limits<INT2>::min(), INT2  max_value = std::numeric_limits<INT1>::max(), bool  optional = false  )

inlineinherited

Add the definition of an option, the value being an instance of AbstractNumber.

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

Template Parameters

NUMTYPE

A subclass of AbstractNumber.

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	short_name	Optional one letter short name.
[in]	min_occur	Minimum number of occurences of this option on the command line.
[in]	max_occur	Maximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]	min_value	Minimum value. Use an integer value, not a NUMTYPE value.
[in]	max_value	Maximum value. Use an integer value, not a NUMTYPE value
[in]	optional	When true, the option's value is optional.

Returns

A reference to this instance.

option() [4/4]

template<class DURATION >
requires std::integral<typename DURATION::rep>

Args & ts::Args::option ( const UChar *  name, UChar  short_name = 0, size_t  min_occur = 0, size_t  max_occur = 0, int64_t  min_value = 0, int64_t  max_value = std::numeric_limits<int64_t>::max(), bool  optional = false  )

inlineinherited

Add the definition of an option, the value being an instance of std::chrono::duration.

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

Template Parameters

DURATION

An instance of std::chrono::duration.

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	short_name	Optional one letter short name.
[in]	min_occur	Minimum number of occurences of this option on the command line.
[in]	max_occur	Maximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]	min_value	Minimum value. Use an integer value, not a DURATION value.
[in]	max_value	Maximum value. Use an integer value, not a DURATION value.
[in]	optional	When 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 existing option.

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	syntax	String to display for the option value instead of the default "value". For instance: "address:port" "'string'".
[in]	text	Help 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  )

inlineinherited

Add the help text of an existing option.

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	text	Help 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]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	separator	The 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]	other	Another instance from which to get the options.
[in]	replace	If 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 )

virtualinherited

Set the description of the command.

Parameters

[in]

description

A short one-line description, e.g. "Wonderful File Copier".

setSyntax()

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

virtualinherited

Set the syntax of the command.

Parameters

[in]

syntax

A short one-line syntax summary, e.g. "[options] filename ...".

Reimplemented in ts::ArgsWithPlugins.

setIntro()

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

virtualinherited

Set the introduction or preamble text for help description.

Parameters

[in]

intro

Introduction text.

setTail()

virtual void ts::Args::setTail ( const UString &  tail )

virtualinherited

Set the conclusion or tailing text for help description.

Parameters

[in]

tail

Tailing text.

setFlags()

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

virtualinherited

Set the option flags of the command.

Parameters

[in]

flags

Define 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()

virtual UString ts::Args::getHelpText ( HelpFormat  format, size_t  line_width = DEFAULT_LINE_WIDTH  ) const

virtualinherited

Get a formatted help text.

Parameters

[in]	format	Requested format of the help text.
[in]	line_width	Maximum width of text lines.

Returns

The formatted help text.

Reimplemented in ts::ArgsWithPlugins.

setAppName()

void ts::Args::setAppName ( const UString &  name )

inlineinherited

Set the initial application name (will be overwritten at next command analysis).

Parameters

[in]

name

Application name string.

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]

shell

Shell name string.

getShell()

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

inlineinherited

Get the "shell" string.

Returns

The shell name string.

See also

setShell()

analyze() [1/3]

virtual bool ts::Args::analyze ( const UString &  command, 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]	command	Full command line, with application name and parameters. Parameters are separated with spaces. Special characters and spaces must be escaped or quoted in the parameters.
[in]	processRedirections	If 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/3]

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]	argc	Number of arguments from command line.
[in]	argv	Arguments from command line. The application name is in argv[0]. The subsequent elements contain the arguments.
[in]	processRedirections	If 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() [3/3]

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_name	Application name.
[in]	arguments	Arguments from command line.
[in]	processRedirections	If 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.

GetAppName()

static UString ts::Args::GetAppName ( int  argc, char *  argv[]  )

staticinherited

Get the application name from a standard argc/argv pair.

Parameters

[in]	argc	Number of arguments from command line.
[in]	argv	Arguments from command line.

Returns

The corresponding application name.

getCommandArgs()

void ts::Args::getCommandArgs ( UStringVector &  args ) const

inlineinherited

Get the command line parameters from the last command line analysis.

Parameters

[out]

args

The command parameters from the last command line analysis.

commandLine()

UString ts::Args::commandLine ( ) const

inherited

Get the full command line from the last command line analysis.

Returns

The full command line from the last command line analysis. It contains the application name and arguments. Special characters are escaped or quoted.

present()

bool ts::Args::present ( const UChar *  name = nullptr ) const

inherited

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

Parameters

[in]

name

The 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 = nullptr ) const

inherited

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

Parameters

[in]

name

The 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() [1/3]

void ts::Args::getValue ( UString &  value, const UChar *  name = nullptr, 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]	value	A string receiving the value of the option or parameter.
[in]	name	The 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_value	The string to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

getValue() [2/3]

template<class NUMTYPE >
requires std::derived_from<NUMTYPE, ts::AbstractNumber>

void ts::Args::getValue ( NUMTYPE &  value, const UChar *  name = nullptr, const NUMTYPE &  def_value = NUMTYPE(0), size_t  index = 0  ) const

inherited

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

If the option has been declared with an AbstractNumber 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

NUMTYPE

A subclass of AbstractNumber.

Parameters

[out]	value	A variable receiving the value of the option or parameter.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

getValue() [3/3]

template<class NUMTYPE , typename INT1 >
requires std::derived_from<NUMTYPE, AbstractNumber> && std::integral<INT1>

void ts::Args::getValue ( NUMTYPE &  value, const UChar *  name, INT1  def_value, size_t  index = 0  ) const

inlineinherited

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

If the option has been declared with an AbstractNumber 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

NUMTYPE

A subclass of AbstractNumber.

Parameters

[out]	value	A variable receiving the value of the option or parameter.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

value()

UString ts::Args::value ( const UChar *  name = nullptr, 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]	name	The 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_value	The string to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The value of the option or parameter.

getOptionalValue()

void ts::Args::getOptionalValue ( std::optional< UString > &  value, const UChar *  name = nullptr, bool  clear_if_absent = false  ) const

inherited

Get the value of an option in the last analyzed command line, only if present.

Parameters

[in,out]	value	A std::optional string receiving the value of the option or parameter.
[in]	name	The 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]	clear_if_absent	When the option is not present, the std::optional object is cleared (set to uninitialized) when clear_if_absent it true. Otherwise, it is left unmodified.

getValues()

template<class CONTAINER >
requires std::derived_from<typename CONTAINER::value_type, ts::UString>

void ts::Args::getValues ( CONTAINER &  values, const UChar *  name = nullptr  ) const

inherited

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

Template Parameters

CONTAINER

A container type of UString such as list, vector, etc.

Parameters

[out]	values	A container of strings receiving all values of the option or parameter.
[in]	name	The 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.

getPathValue()

void ts::Args::getPathValue ( fs::path &  value, const UChar *  name = nullptr, const fs::path &  def_value = fs::path(), size_t  index = 0  ) const

inherited

Get the value of a filesystem path option in the last analyzed command line.

Parameters

[out]	value	A path receiving the value of the option or parameter.
[in]	name	The 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_value	The path to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

getPathValues()

template<class CONTAINER >
requires std::derived_from<typename CONTAINER::value_type, fs::path>

void ts::Args::getPathValues ( CONTAINER &  values, const UChar *  name = nullptr  ) const

inherited

Get all occurences of a filesystem path option in a container of path.

Template Parameters

CONTAINER

A container type of fs::path such as list, vector, etc.

Parameters

[out]	values	A container of fs::path receiving all values of the option or parameter.
[in]	name	The 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.

getIntValue()

template<typename INT , typename INT2 >
requires ts::int_enum<INT> && ts::int_enum<INT2>

void ts::Args::getIntValue ( INT &  value, const UChar *  name = nullptr, const INT2  def_value = static_cast<INT2>(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

INT	An integer or enumeration type for the result.

Parameters

[out]	value	A variable receiving the integer value of the option or parameter.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

intValue()

template<typename INT >
requires ts::int_enum<INT>

INT ts::Args::intValue ( const UChar *  name = nullptr, 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

INT	An integer or enumeration type for the result.

Parameters

[in]	name	The 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_value	The value to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The integer value of the option or parameter.

getOptionalIntValue()

template<typename INT >
requires ts::int_enum<INT>

void ts::Args::getOptionalIntValue ( std::optional< INT > &  value, const UChar *  name = nullptr, bool  clear_if_absent = false  ) const

inherited

Get the value of an integer option in the last analyzed command line, only if present.

Template Parameters

INT	An integer or enumeration type for the result.

Parameters

[in,out]	value	A std::optional integer receiving the value of the option or parameter.
[in]	name	The 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]	clear_if_absent	When the option is not present, the std::optional object is cleared (set to uninitialized) when clear_if_absent it true. Otherwise, it is left unmodified.

getIntValues() [1/4]

template<typename INT >
requires ts::int_enum<INT>

void ts::Args::getIntValues ( std::vector< INT > &  values, const UChar *  name = nullptr  ) const

inherited

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

Template Parameters

INT	An integer or enumeration type for the result.

Parameters

[out]	values	A container of integers receiving all values of the option or parameter.
[in]	name	The 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/4]

template<typename INT >
requires ts::int_enum<INT>

void ts::Args::getIntValues ( std::set< INT > &  values, const UChar *  name = nullptr  ) const

inherited

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

Template Parameters

INT	An integer or enumeration type for the result.

Parameters

[out]	values	A container of integers receiving all values of the option or parameter.
[in]	name	The 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() [3/4]

template<std::size_t N>

void ts::Args::getIntValues ( std::bitset< N > &  values, const UChar *  name = nullptr, bool  defValue = false  ) const

inherited

Get all occurences of an option as a bitset of values.

Parameters

[out]	values	A bitset receiving all values of the option or parameter. For each value of the option, the corresponding bit is set. Values which are out of range are ignored.
[in]	name	The 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]	defValue	The boolean to set in all values if the option or parameter is not present in the command line.

getIntValues() [4/4]

template<std::size_t N>

void ts::Args::getIntValues ( CompactBitSet< N > &  values, const UChar *  name = nullptr, bool  defValue = false  ) const

inherited

Get all occurences of an option as a compact bitset of values.

Parameters

[out]	values	A compact bitset receiving all values of the option or parameter. For each value of the option, the corresponding bit is set. Values which are out of range are ignored.
[in]	name	The 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]	defValue	The boolean to set in all values if the option or parameter is not present in the command line.

bitMaskValue()

template<typename INT >
requires std::integral<INT>

INT ts::Args::bitMaskValue ( const UChar *  name = nullptr, 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

INT	An integer type for the result.

Parameters

[in]	name	The 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_value	The 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 >
requires std::integral<INT>

void ts::Args::getBitMaskValue ( INT &  value, const UChar *  name = nullptr, 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

INT	An integer type for the result.

Parameters

[out]	value	A variable receiving the OR'ed values of the integer option.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line.

getChronoValue() [1/2]

template<class Rep1 , class Period1 , class Rep2 , class Period2 >

void ts::Args::getChronoValue ( cn::duration< Rep1, Period1 > &  value, const UChar *  name = nullptr, const cn::duration< Rep2, Period2 > &  def_value = cn::duration<Rep1, Period1>::zero(), size_t  index = 0  ) const

inherited

Get the value of an std::chrono::duration option in the last analyzed command line.

If the option has been declared with a std::chrono::duration 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.

Parameters

[out]	value	A variable receiving the duration value of the option or parameter.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence. Add the definition of an option, the value being an instance of std::chrono::duration.

getChronoValue() [2/2]

template<class Rep , class Period >

void ts::Args::getChronoValue ( cn::duration< Rep, Period > &  value, const UChar *  name = nullptr, size_t  index = 0  ) const

inlineinherited

Get the value of an std::chrono::duration option in the last analyzed command line.

If the option has been declared with a std::chrono::duration 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.

Parameters

[out]	value	A variable receiving the duration value of the option or parameter.
[in]	name	The 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]	index	The occurence of the option to return. Zero designates the first occurence. Add the definition of an option, the value being an instance of std::chrono::duration.

getTristateValue()

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

inherited

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

Parameters

[out]	value	A 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]	name	The 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]	index	The occurence of the option to return. Zero designates the first occurence.

tristateValue()

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

inherited

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

Parameters

[in]	name	The 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]	index	The 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.

getHexaValue()

void ts::Args::getHexaValue ( ByteBlock &  value, const UChar *  name = nullptr, const ByteBlock &  def_value = ByteBlock(), size_t  index = 0  ) const

inherited

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

Parameters

[out]	value	A variable receiving the decoded binary value of the option or parameter.
[in]	name	The 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_value	The data to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

hexaValue()

ByteBlock ts::Args::hexaValue ( const UChar *  name = nullptr, const ByteBlock &  def_value = ByteBlock(), size_t  index = 0  ) const

inherited

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

Parameters

[in]	name	The 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_value	The data to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The decoded binary value of the option or parameter.

getIPValue()

void ts::Args::getIPValue ( IPAddress &  value, const UChar *  name = nullptr, const IPAddress &  def_value = IPAddress(), size_t  index = 0  ) const

inherited

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

Parameters

[out]	value	A variable receiving the resolved IP address value of the option or parameter.
[in]	name	The 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_value	The IP address to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

ipValue()

IPAddress ts::Args::ipValue ( const UChar *  name = nullptr, const IPAddress &  def_value = IPAddress(), size_t  index = 0  ) const

inherited

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

Parameters

[in]	name	The 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_value	The IP address to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The resolved IP address value of the option or parameter.

getSocketValue()

void ts::Args::getSocketValue ( IPSocketAddress &  value, const UChar *  name = nullptr, const IPSocketAddress &  def_value = IPSocketAddress(), size_t  index = 0  ) const

inherited

Get the value of an option as an IP socket address in the last analyzed command line.

Parameters

[out]	value	A variable receiving the resolved IP socket address value of the option or parameter.
[in]	name	The 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_value	The IP address socket to return if the option or parameter is not present in the command line or with fewer occurences than index. If the parameter is present but either address or port is missing, the missing part is copied from def_value.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

socketValue()

IPSocketAddress ts::Args::socketValue ( const UChar *  name = nullptr, const IPSocketAddress &  def_value = IPSocketAddress(), size_t  index = 0  ) const

inherited

Get the value of an option as an IP socket address in the last analyzed command line.

Parameters

[in]	name	The 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_value	The IP socket address to return if the option or parameter If the parameter is present but either address or port is missing, the missing part is copied from def_value. is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The resolved IP socket address value of the option or parameter.

numValue()

template<class NUMTYPE >
requires std::derived_from<NUMTYPE, ts::AbstractNumber>

NUMTYPE ts::Args::numValue ( const UChar *  name = nullptr, const NUMTYPE &  def_value = NUMTYPE(0), size_t  index = 0  ) const

inherited

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

If the option has been declared with an AbstractNumber 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

NUMTYPE

A subclass of AbstractNumber.

Parameters

[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The value of the option or parameter.

exitOnError()

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

inherited

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

Parameters

[in]

force

If true, ignore flag NO_EXIT_ON_ERROR and force application termination on error.

processArgsRedirection()

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

inherited

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

Parameters

[in,out]

args

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

writeLog()

virtual void ts::Args::writeLog ( int  severity, const UString &  msg  )

overrideprotectedvirtualinherited

Actual message reporting method.

The method is called only when a message passed the severity filter. It is not necessary to recheck the maximum severity inside the method. By default, does nothing.

Parameters

[in]	severity	Message severity.
[in]	msg	Message text.

Reimplemented from ts::Report.

setMaxSeverity()

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

inherited

Set maximum severity level.

Messages with higher severities are not reported.

Parameters

[in]

level

Set report to that level.

raiseMaxSeverity()

void ts::Report::raiseMaxSeverity ( int  level )

inherited

Raise maximum severity level.

The severity can only be increased (more verbose, more debug), never decreased.

Parameters

[in]

level

Set report at least to that level.

maxSeverity()

int ts::Report::maxSeverity ( ) const

inlineinherited

Get maximum severity level.

Returns

Current maximum debug level.

gotErrors()

bool ts::Report::gotErrors ( ) const

inlineinherited

Check if errors (or worse) were reported through this object.

Errors which were reported through delegated reports are ignored.

Returns

True if errors (or worse) were reported through this object.

resetErrors()

void ts::Report::resetErrors ( )

inlineinherited

Reset the error indicator.

See also

gotErrors()

setReportPrefix()

void ts::Report::setReportPrefix ( const UString &  prefix )

inlineinherited

Set the prefix to display before each message.

Parameters

[in]

prefix

The prefix to prepend to all messages.

reportPrefix()

UString ts::Report::reportPrefix ( ) const

inlineinherited

Get the current prefix to display.

Returns

The current prefix to display.

delegateReport()

Report * ts::Report::delegateReport ( Report *  report )

inherited

Delegate message logging to another report object.

Parameters

[in]

report

New report object to which messages are delegated. Use nullptr to remove the delegation and return to normal logging.

Returns

Previous delegate report, return a null pointer if there was no previous delegate.

debug() [1/5]

bool ts::Report::debug ( ) const

inlineinherited

Check if debugging is active.

Returns

True if current reporting level is Debug or higher.

debug() [2/5]

void ts::Report::debug ( const UChar *  msg )

inlineinherited

Report a debug message.

Parameters

[in]

msg

Message line.

debug() [3/5]

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

inlineinherited

Report a debug message.

Parameters

[in]

msg

Message line.

debug() [4/5]

template<class... Args>

void ts::Report::debug ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report a debug message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

debug() [5/5]

template<class... Args>

void ts::Report::debug ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report a debug message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

verbose() [1/5]

bool ts::Report::verbose ( ) const

inlineinherited

Check if verbose reporting is active.

Returns

True if current reporting level is Verbose or higher.

verbose() [2/5]

void ts::Report::verbose ( const UChar *  msg )

inlineinherited

Report a verbose message.

Parameters

[in]

msg

Message line.

verbose() [3/5]

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

inlineinherited

Report a verbose message.

Parameters

[in]

msg

Message line.

verbose() [4/5]

template<class... Args>

void ts::Report::verbose ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report a verbose message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

verbose() [5/5]

template<class... Args>

void ts::Report::verbose ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report a verbose message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

log() [1/3]

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

inherited

Report a message with an explicit severity.

Parameters

[in]	severity	Message severity.
[in]	msg	Message line.

log() [2/3]

template<class... Args>

void ts::Report::log ( int  severity, const UChar *  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	severity	Message severity.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

log() [3/3]

template<class... Args>

void ts::Report::log ( int  severity, const UString &  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	severity	Message severity.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

fatal() [1/4]

void ts::Report::fatal ( const UChar *  msg )

inlineinherited

Report a fatal error message.

Parameters

[in]

msg

Message line.

fatal() [2/4]

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

inlineinherited

Report a fatal error message.

Parameters

[in]

msg

Message line.

fatal() [3/4]

template<class... Args>

void ts::Report::fatal ( const UChar *  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

fatal() [4/4]

template<class... Args>

void ts::Report::fatal ( const UString &  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

severe() [1/4]

void ts::Report::severe ( const UChar *  msg )

inlineinherited

Report a severe error message.

Parameters

[in]

msg

Message line.

severe() [2/4]

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

inlineinherited

Report a severe error message.

Parameters

[in]

msg

Message line.

severe() [3/4]

template<class... Args>

void ts::Report::severe ( const UChar *  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

severe() [4/4]

template<class... Args>

void ts::Report::severe ( const UString &  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

error() [1/4]

void ts::Report::error ( const UChar *  msg )

inlineinherited

Report an error message.

Parameters

[in]

msg

Message line.

error() [2/4]

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

inlineinherited

Report an error message.

Parameters

[in]

msg

Message line.

error() [3/4]

template<class... Args>

void ts::Report::error ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report an error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

error() [4/4]

template<class... Args>

void ts::Report::error ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report an error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

warning() [1/4]

void ts::Report::warning ( const UChar *  msg )

inlineinherited

Report a warning error message.

Parameters

[in]

msg

Message line.

warning() [2/4]

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

inlineinherited

Report a warning error message.

Parameters

[in]

msg

Message line.

warning() [3/4]

template<class... Args>

void ts::Report::warning ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report a warning message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

warning() [4/4]

template<class... Args>

void ts::Report::warning ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report a warning message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

info() [1/4]

void ts::Report::info ( const UChar *  msg )

inlineinherited

Report an informational message.

Parameters

[in]

msg

Message line.

info() [2/4]

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

inlineinherited

Report an informational message.

Parameters

[in]

msg

Message line.

info() [3/4]

template<class... Args>

void ts::Report::info ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report an informational message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

info() [4/4]

template<class... Args>

void ts::Report::info ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report an informational message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

Member Data Documentation

UNLIMITED_COUNT

constexpr size_t ts::Args::UNLIMITED_COUNT = std::numeric_limits<size_t>::max()

staticconstexprinherited

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 = std::numeric_limits<int64_t>::max()

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:

• tsPushInputPlugin.h