libvpb
4.2.61
|
Base type for the programmable tone generator interface. More...
#include <tonegen.h>
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... | |
Config & | GetConfig () 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. | |
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.
enum ToneGen::State |
|
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.
tone | The 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. |
sync | If 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. |
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.
|
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().
|
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).
|
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
.
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().
|
inline |
Return the current state of this ToneGen
.
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.
|
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.
|
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.
tone | The 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. |
sync | If 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.
BeginSequence()
for composing atomic sequences of discrete tones. References IDLE, and ImplStart().
|
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.
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.