Loading...
Searching...
No Matches
ToneGen Class Referenceabstract

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

`#include <tonegen.h>`

Inheritance diagram for ToneGen:
Collaboration diagram for ToneGen:

## 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.
void | Stop ()
| Stop tone generation.
State | GetState () const
| Return the current state of this `ToneGen`.
Tone sequences
void | BeginSequence (Config *tone, bool sync=false)
| Prepare the tone generator for playing a sequence of related tones.
void | ContinueSequence ()
| Begin the next discrete tone in an atomic sequence.
void | EndSequence ()
| Signal the completion of an atomic sequence of tones.
Tone completion
void | SignalCompletion ()
| Notify the tone generator of an external completion event.
Config & | GetConfig () const
| Return the `ToneGen::Config` data.

## 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

enum ToneGen::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

  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.

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.

## ImplStart()

virtual State ToneGen::ImplStart | ( |  | ) |

protected pure virtual

Called by `Start()` for implementation specific operations.

Implemented in HostToneGen, and V4PCIToneGen.

Referenced by BeginSequence(), ContinueSequence(), SignalCompletion(), and Start().

## ImplStop()

virtual void ToneGen::ImplStop | ( |  | ) |

inline protected virtual

Called by `Stop()` for implementation specific operations.

Reimplemented in V4PCIToneGen.

## 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

  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.

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.

Referenced by vpb_tone_terminate().