TSDuck Version 3.32-2769 (TSDuck - The MPEG Transport Stream Toolkit)
ts::TunerBase Class Reference

Base class for Digital TV tuners. More...

Inheritance diagram for ts::TunerBase:
Collaboration diagram for ts::TunerBase:

Public Member Functions

 TunerBase (DuckContext &duck)
 Constructor. More...
 
virtual ~TunerBase ()
 Virtual destructor.
 
virtual void abort (bool silent=false)
 Abort any pending or blocked reception. More...
 
virtual bool close (bool silent=false)
 Close the tuner. More...
 
virtual const DeliverySystemSetdeliverySystems () const
 Set of delivery systems which are supported by the tuner. More...
 
virtual UString deviceInfo () const
 Device-specific information. More...
 
virtual UString deviceName () const
 Get the device name of the tuner. More...
 
virtual UString devicePath () const
 System-specific device path (for information only). More...
 
virtual std::ostream & displayStatus (std::ostream &strm, const UString &margin=UString(), bool extended=false)
 Display the characteristics and status of the tuner. More...
 
virtual bool getCurrentTuning (ModulationArgs &params, bool reset_unknown)
 Get the current tuning parameters. More...
 
virtual bool getSignalState (SignalState &state)
 Check if a signal is present and get the signal state. More...
 
virtual bool infoOnly () const
 Get the open mode. More...
 
virtual bool isOpen () const
 Check if the tuner is open. More...
 
virtual bool open (const UString &device_name, bool info_only)
 Open the tuner. More...
 
virtual size_t receive (TSPacket *buffer, size_t max_packets, const AbortInterface *abort=nullptr)
 Receive packets. More...
 
virtual MilliSecond receiveTimeout () const
 Get the timeout for receive operation. More...
 
Reportreport () const
 Get a reference to the error report. More...
 
virtual void setDemuxBufferSize (size_t s)
 Set the demux buffer size in bytes (Linux-specific). More...
 
virtual void setReceiverFilterName (const UString &name)
 Specify a receiver filter name (Windows-specific). More...
 
virtual bool setReceiveTimeout (MilliSecond t)
 Set the timeout for receive operations. More...
 
virtual void setSignalPoll (MilliSecond t)
 Set the poll interval for signal timeout (Linux-specific). More...
 
virtual void setSignalTimeout (MilliSecond t)
 Set the timeout before getting a signal on start. More...
 
virtual void setSignalTimeoutSilent (bool silent)
 Set if an error should be reported on timeout before getting a signal on start. More...
 
virtual void setSinkQueueSize (size_t s)
 Set the max number of queued media samples (Windows-specific). More...
 
virtual bool start ()
 Start receiving packets. More...
 
virtual bool stop (bool silent=false)
 Stop receiving packets. More...
 
virtual bool tune (ModulationArgs &params)
 Tune to the specified parameters. More...
 

Static Public Member Functions

static bool GetAllTuners (DuckContext &duck, TunerPtrVector &tuners)
 Get the list of all existing physical tuners. More...
 

Static Public Attributes

static constexpr size_t DEFAULT_DEMUX_BUFFER_SIZE = 1024 * 1024
 Default demux buffer size in bytes (Linux-specific).
 
static constexpr MilliSecond DEFAULT_SIGNAL_POLL = 100
 Default poll interval for signal timeout (Linux-specific).
 
static constexpr MilliSecond DEFAULT_SIGNAL_TIMEOUT = 5000
 Default timeout before getting a signal on start.
 
static constexpr size_t DEFAULT_SINK_QUEUE_SIZE = 1000
 Default max number of queued media samples (Windows-specific). More...
 

Protected Member Functions

bool checkTuneParameters (ModulationArgs &params) const
 Check the consistency of tune() parameters. More...
 
bool unimplemented () const
 Helper for unimplemented methods. More...
 

Protected Attributes

DuckContext_duck
 TSDuck execution context for subclasses.
 

Detailed Description

Base class for Digital TV tuners.

The TunerBase class defines all virtual methods to access a tuner. All services in the base class are "unimplemented" and return an error. Actual services should be implemented by subclasses.

The main subclasses are TunerDevice which implements a physical tuner, TunerEmulator which implements a file-based fake tuner and Tuner which encapsulates both capabilities.

A note on history: In older versions of TSDuck, a tuner had a single "type" (DVT-T, DVB-S, etc.). There was also a specific subclass of tuner parameters for each type of tuner. With the advent of multi-standard tuners (DVB-T and DVB-C for instance), this was no longer appropriate. Now, each tuner device has a set of supported delivery systems. There is one single class containing all tuning parameters for all delivery systems. The selected delivery system is one of these parameter. To tune a device, we now provide an instance of the ModulationArgs class. If the tuner supports the target delivery system, it picks the appropriate parameters for the selected delivery system.

Constructor & Destructor Documentation

◆ TunerBase()

ts::TunerBase::TunerBase ( DuckContext duck)

Constructor.

Parameters
[in,out]duckTSDuck execution context.

Member Function Documentation

◆ GetAllTuners()

static bool ts::TunerBase::GetAllTuners ( DuckContext duck,
TunerPtrVector tuners 
)
static

Get the list of all existing physical tuners.

Parameters
[in,out]duckTSDuck execution context.
[out]tunersReturned list of physical tuners on the system.
Returns
True on success, false on error.

◆ open()

virtual bool ts::TunerBase::open ( const UString device_name,
bool  info_only 
)
virtual

Open the tuner.

Parameters
[in]device_nameTuner device name. If name is empty, use "first" or "default" tuner.
[in]info_onlyIf true, we will only fetch the properties of the tuner, we won't use it to receive streams. Thus, it is possible to open tuners which are already used to actually receive a stream.
Returns
True on success, false on error.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ close()

virtual bool ts::TunerBase::close ( bool  silent = false)
virtual

Close the tuner.

Parameters
[in]silentWhen true, do not report close errors.
Returns
True on success, false on error.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ isOpen()

virtual bool ts::TunerBase::isOpen ( ) const
virtual

Check if the tuner is open.

Returns
True if the tuner is open.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ infoOnly()

virtual bool ts::TunerBase::infoOnly ( ) const
virtual

Get the open mode.

Returns
True if the tuner is open to fetch information only. In that case, the tuner cannot receive streams.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ deliverySystems()

virtual const DeliverySystemSet& ts::TunerBase::deliverySystems ( ) const
virtual

Set of delivery systems which are supported by the tuner.

Returns
A constant reference to the set of delivery systems which are supported by the tuner.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ deviceName()

virtual UString ts::TunerBase::deviceName ( ) const
virtual

Get the device name of the tuner.

Returns
The device name of the tuner.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ deviceInfo()

virtual UString ts::TunerBase::deviceInfo ( ) const
virtual

Device-specific information.

Returns
A string with device-specific information. Can be empty.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ devicePath()

virtual UString ts::TunerBase::devicePath ( ) const
virtual

System-specific device path (for information only).

Returns
A string with system-specific device path. Can be empty.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ getSignalState()

virtual bool ts::TunerBase::getSignalState ( SignalState state)
virtual

Check if a signal is present and get the signal state.

Parameters
[out]stateReturned state of the tuner. Some fields may be unset if unavailable with that tuner.
Returns
True in case of success (even if no signal was detected), false on error.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ tune()

virtual bool ts::TunerBase::tune ( ModulationArgs params)
virtual

Tune to the specified parameters.

Parameters
[in,out]paramsTuning parameters. Updated with missing default values.
Returns
True on success, false on error.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ start()

virtual bool ts::TunerBase::start ( )
virtual

Start receiving packets.

Returns
True on success, false on error.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ stop()

virtual bool ts::TunerBase::stop ( bool  silent = false)
virtual

Stop receiving packets.

Parameters
[in]silentWhen true, do not report close errors.
Returns
True on success, false on error.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ abort()

virtual void ts::TunerBase::abort ( bool  silent = false)
virtual

Abort any pending or blocked reception.

This unblocks a blocked reader but leaves the tuner in an undefined state. The only safe option after this is a close().

Parameters
[in]silentWhen true, do not report close errors.

Reimplemented in ts::TunerDevice, ts::TunerDevice, and ts::Tuner.

◆ receive()

virtual size_t ts::TunerBase::receive ( TSPacket buffer,
size_t  max_packets,
const AbortInterface abort = nullptr 
)
virtual

Receive packets.

Parameters
[out]bufferAddress of TS packet receive buffer. Read only complete 188-byte TS packets.
[in]max_packetsMaximum number of packets to read in buffer.
[in]abortIf non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
Returns
The number of actually received packets (in the range 1 to max_packets). Returning zero means error or end of input.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ getCurrentTuning()

virtual bool ts::TunerBase::getCurrentTuning ( ModulationArgs params,
bool  reset_unknown 
)
virtual

Get the current tuning parameters.

Parameters
[in,out]paramsReturned tuning parameters. Modify only the properties which can be reported by the tuner.
[in]reset_unknownIf true, the unknown values (those which are not reported by the tuner) are reset to unknown/zero/auto values. Otherwise, they are left unmodified.
Returns
True on success, false on error.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ setSignalTimeout()

virtual void ts::TunerBase::setSignalTimeout ( MilliSecond  t)
virtual

Set the timeout before getting a signal on start.

If zero, do not wait for signal on start. Must be set before start().

Parameters
[in]tNumber of milliseconds to wait after start() before receiving a signal.

Reimplemented in ts::TunerDevice, ts::TunerDevice, and ts::Tuner.

◆ setSignalTimeoutSilent()

virtual void ts::TunerBase::setSignalTimeoutSilent ( bool  silent)
virtual

Set if an error should be reported on timeout before getting a signal on start.

Must be set before start().

Parameters
[in]silentIf true, no error message will be reported if no signal is received after the timeout on start.

Reimplemented in ts::TunerDevice, ts::TunerDevice, and ts::Tuner.

◆ setReceiveTimeout()

virtual bool ts::TunerBase::setReceiveTimeout ( MilliSecond  t)
virtual

Set the timeout for receive operations.

Parameters
[in]tNumber of milliseconds to wait before receiving packets in a receive() operation. If zero (the default), no timeout is applied.
Returns
True on success, false on error.

Reimplemented in ts::TunerDevice, ts::TunerDevice, and ts::Tuner.

◆ receiveTimeout()

virtual MilliSecond ts::TunerBase::receiveTimeout ( ) const
virtual

Get the timeout for receive operation.

Returns
The timeout for receive operation.
See also
setReceiveTimeout()

Reimplemented in ts::TunerDevice, ts::TunerDevice, and ts::Tuner.

◆ setSignalPoll()

virtual void ts::TunerBase::setSignalPoll ( MilliSecond  t)
virtual

Set the poll interval for signal timeout (Linux-specific).

Must be set before start(). This is a Linux-specific method which does nothing on other systems.

Parameters
[in]tPoll interval in milliseconds.

Reimplemented in ts::TunerDevice, and ts::Tuner.

◆ setDemuxBufferSize()

virtual void ts::TunerBase::setDemuxBufferSize ( size_t  s)
virtual

Set the demux buffer size in bytes (Linux-specific).

Must be set before start(). This is a Linux-specific method which does nothing on other systems.

Parameters
[in]sThe demux buffer size in bytes.

Reimplemented in ts::TunerDevice, and ts::Tuner.

◆ setSinkQueueSize()

virtual void ts::TunerBase::setSinkQueueSize ( size_t  s)
virtual

Set the max number of queued media samples (Windows-specific).

Must be set before start(). This is a Windows-specific method which does nothing on other systems.

Parameters
[in]sMax number of media samples in the queue between the graph thread and the application thread.

Reimplemented in ts::TunerDevice, and ts::Tuner.

◆ setReceiverFilterName()

virtual void ts::TunerBase::setReceiverFilterName ( const UString name)
virtual

Specify a receiver filter name (Windows-specific).

Must be set before open(). This is a Windows-specific method which does nothing on other systems.

Parameters
[in]nameName of the receiver filter to use. The DirectShow graph will use the specified receiver filter instead of the standard search algorithm.

Reimplemented in ts::TunerDevice, and ts::Tuner.

◆ displayStatus()

virtual std::ostream& ts::TunerBase::displayStatus ( std::ostream &  strm,
const UString margin = UString(),
bool  extended = false 
)
virtual

Display the characteristics and status of the tuner.

Parameters
[in,out]strmOutput text stream.
[in]marginLeft margin to display.
[in]extendedDisplay "extended" information. Can be very verbose.
Returns
A reference to strm.

Reimplemented in ts::TunerDevice, ts::TunerDevice, ts::TunerEmulator, and ts::Tuner.

◆ report()

Report& ts::TunerBase::report ( ) const
inline

Get a reference to the error report.

Returns
A reference to the error report.

◆ checkTuneParameters()

bool ts::TunerBase::checkTuneParameters ( ModulationArgs params) const
protected

Check the consistency of tune() parameters.

Parameters
[in,out]paramsModulation parameters. Updated with default values.
Returns
True on success, false on error.

◆ unimplemented()

bool ts::TunerBase::unimplemented ( ) const
protected

Helper for unimplemented methods.

Display a standard error message.

Returns
False.

Member Data Documentation

◆ DEFAULT_SINK_QUEUE_SIZE

constexpr size_t ts::TunerBase::DEFAULT_SINK_QUEUE_SIZE = 1000
staticconstexpr

Default max number of queued media samples (Windows-specific).

See also
setSinkQueueSize().

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