libvpb  4.2.61
ToneGen Class Referenceabstract

Base type for the programmable tone generator interface. More...

#include <tonegen.h>

Inheritance diagram for ToneGen:
Inheritance graph
Collaboration diagram for ToneGen:
Collaboration graph

Classes

class  Config
 ToneGen configuration data structure. More...
 
class  Exception
 ToneGen runtime exception type More...
 

Public Types

enum  State { IDLE , SEQUENCE , CONTINUOUS , ONESHOT }
 ToneGen state information More...
 
typedef std::vector< ToneGen * > List
 Container type for a list of pointers to ToneGen structures.
 
typedef void(* CompletionCallback) (ToneGen &)
 Call back type for tone completion notification.
 

Public Member Functions

 ToneGen ()
 Default constructor.
 
virtual ~ToneGen ()
 Virtual destructor.
 
Tone generation
void Start (Config *tone, bool sync=false)
 Begin generation of a single tone. More...
 
void Stop ()
 Stop tone generation. More...
 
State GetState () const
 Return the current state of this ToneGen. More...
 
Tone sequences
void BeginSequence (Config *tone, bool sync=false)
 Prepare the tone generator for playing a sequence of related tones. More...
 
void ContinueSequence ()
 Begin the next discrete tone in an atomic sequence. More...
 
void EndSequence ()
 Signal the completion of an atomic sequence of tones. More...
 
Tone completion
void SignalCompletion ()
 Notify the tone generator of an external completion event. More...
 
ConfigGetConfig () const
 Return the ToneGen::Config data. More...
 

Protected Member Functions

virtual State ImplStart ()=0
 Called by Start() for implementation specific operations.
 
virtual void ImplStop ()
 Called by Stop() for implementation specific operations.
 

Detailed Description

Base type for the programmable tone generator interface.

The ToneGen interface facilitates the definition and creation of pure or composite tones, of fixed, cadenced, or continuous duration. The number of frequency components per tone is implementation defined. For the HostToneGen it is unlimited, but the hardware based generators typically have a fixed number of oscillators available.

Member Enumeration Documentation

◆ State

ToneGen state information

Enumerator
IDLE 

Tone generator is idle.

SEQUENCE 

Tone generator is handling a sequence of tones.

CONTINUOUS 

Continuous tone generation in progress.

ONESHOT 

One-shot tone generation in progress.

Member Function Documentation

◆ BeginSequence()

void ToneGen::BeginSequence ( Config tone,
bool  sync = false 
)
inline

Prepare the tone generator for playing a sequence of related tones.

At times it may be desirable to generate a complex sequence of tones which should appear to the calling application as a single coherent tone generation cycle, for example: dialling a DTMF string, or signal tones which consists of a series of discrete tones. If you were to simply call Start() repeatedly, then a completion event would be generated for each discrete tone to be played and other threads may try to interleave tones between those calls.

To initiate an atomic sequence of tones, call BeginSequence() instead of Start(), and supply a CompletionCallback in the Config data. The callback will be invoked at the completion of each discrete tone. Subsequent tones may be played by modifying the tone parameters of the config (retrieved with GetConfig()), and then calling the ContinueSequence() method to begin that tone. When all tones in the sequence have been played, the EndSequence() method must be called to signal that to the ToneGen and wake the thread that blocked on the BeginSequence() call if its sync flag was set.

Parameters
toneThe Config data for the first tone to play. The ToneGen will take ownership of this data and will destroy it when it is no longer required. The caller must make no assumptions about the lifetime of this data after passing it to this method, it may already be destroyed by the time this method returns control to the calling thread.
syncIf true, this method will block the calling thread until the full sequence has completed playing and EndSequence() is called, else this function will return immediately.
Note
Any call which performs an explicit termination of a tone, such as Stop(), Start(), or another call to BeginSequence(), will terminate an active sequence as if EndSequence() had been called immediately prior. You must not call such functions from a CompletionCallback, but other threads may invoke them and interrupt a sequence before its natural completion.

References IDLE, ImplStart(), and SEQUENCE.

◆ ContinueSequence()

void ToneGen::ContinueSequence ( )
inline

Begin the next discrete tone in an atomic sequence.

This function should only be used between calls to BeginSequence() and EndSequence(). It must be called with the ToneGen mutex locked and assumes that any tone previously started with a call to BeginSequence() or ContinueSequence() has already terminated. To ensure these conditions are met, it should only be called from a CompletionCallback that was set with the initial call to the BeginSequence() method.

References ImplStart().

◆ EndSequence()

void ToneGen::EndSequence ( )
inline

Signal the completion of an atomic sequence of tones.

This function should be called after the last tone in a sequence has completed. It will wake the thread blocked on a call to BeginSequence() if that method was called with the sync flag set. It must be called with the ToneGen mutex locked. To ensure this conditions is met, it should only be called from a CompletionCallback that was set with the initial call to the BeginSequence() method. It will not invoke the CompletionCallback function (again).

◆ GetConfig()

Config& ToneGen::GetConfig ( ) const
inline

Return the ToneGen::Config data.

This method may be called from a CompletionCallback, either to retrieve user data that was associated with the current ToneGen operation, or to modify the ToneGen parameters for a subsequent tone in a SEQUENCE.

Warning
It is not safe to use the object returned by this call at any other time when the ToneGen mutex is not locked, since the Config it returns may be destroyed at any time by any asynchronous operation that stops the ToneGen.

Referenced by V4PCIToneGen::ImplStart(), and V4PCIToneGen::ImplStop().

◆ GetState()

State ToneGen::GetState ( ) const
inline

Return the current state of this ToneGen.

Note
The return value from this function must not be relied upon by the calling function if it does not hold the ToneGen mutex, since the real state may have already changed even before control is returned to the calling thread. In those cases it must be considered as an unreliable hint and any following code should be well behaved for any state the ToneGen may really be in.

◆ SignalCompletion()

void ToneGen::SignalCompletion ( )
inline

Notify the tone generator of an external completion event.

This function should be called by specialised ToneGen instances upon normal completion of a generated tone. It will set the ToneGen::State to IDLE and notify the user of that transition. It will do nothing if the current state is already IDLE.

References CONTINUOUS, IDLE, ImplStart(), ONESHOT, and SEQUENCE.

◆ Start()

void ToneGen::Start ( Config tone,
bool  sync = false 
)
inline

Begin generation of a single tone.

If a tone is already playing it will be terminated before playing the new tone as if you had called Stop() immediately prior.

Parameters
toneThe Config data for the tone to play. The ToneGen will take ownership of this data and destroy it when it is no longer required. The calling function should make no assumptions about the lifetime of this data after passing it to this method, it may already be destroyed by the time this method returns control to the calling thread.
syncIf true, this method will block the calling thread until the tone has completed playing, else this function will return immediately.

Most well behaved applications should confirm the completion of a tone started with this function (whether they are terminated by cadence or an explicit call to the Stop() function) before any subsequent calls to Start() are made.

See also
BeginSequence() for composing atomic sequences of discrete tones.

References IDLE, and ImplStart().

◆ Stop()

void ToneGen::Stop ( )
inline

Stop tone generation.

This function may be used to explicitly terminate a tone. Any threads that are blocked waiting for its completion will be woken up.

Note
The CompletionCallback function (if any) will not be called if the tone is explicitly terminated. You should call SignalCompletion() instead if you wish to create the appearance of a normal tone completion event.