User's Manual

156 Voice API Programming Guide — June 2005
Global Tone Detection and Generation, and Cadenced Tone Generation
• Duration of tone
The functions and data structures associated with global tone generation are described in the Voice
API Library Reference.
13.2.2 GTG Functions
The following functions are used to generate tones:
dx_bldtngen( )
Builds a tone generation template. This convenience function sets up the tone generation
template data structure (TN_GEN) by allowing the assignment of specified values to the
appropriate fields. The tone generation template is placed in the user’s return buffer and can
then be used by the dx_playtone( ) function to generate the tone.
dx_playtone( )
Plays a tone specified by the tone generation template (pointed to by tngenp). Termination
conditions are set using the DV_TPT structure. The reason for termination is returned by the
ATDX_TERMMSK( ) function. dx_playtone( ) returns a 0 to indicate that it has completed
successfully.
13.2.3 Building and Implementing a Tone Generation Template
The tone generation template defines the frequency, amplitude, and duration of a single or dual
frequency tone to be played. You can use the convenience function dx_bldtngen( ) to set up the
structure. Use dx_playtone( ) to play the tone.
The TN_GEN data structure is defined as:
typedef struct {
unsigned short tg_dflag; /* dual tone = 1, single tone = 0 */
unsigned short tg_freq1; /* frequency of tone 1 (in Hz) */
unsigned short tg_freq2; /* frequency of tone 2 (in Hz) */
short int tg_ampl1; /* amplitude of tone 1 (in dB) */
short int tg_ampl2; /* amplitude of tone 2 (in dB) */
short int tg_dur; /* duration (in 10 msec units) */
} TN_GEN;
After you build the TN_GEN data structure, there are two ways to define each tone template. You
may either:
• Include the values in the structure
• Pass the values to TN_GEN using the dx_bldtngen( ) function
If you include the values in the structure, you must create a structure for each tone template. If you
pass the values using the dx_playtone( ) function, then you can reuse the structure. If you are only
changing one value in a template with many variables, it may be more convenient to use several
structures in the code instead of reusing just one.
After defining the template by either of these methods, pass TN_GEN to dx_playtone( ) to play the
tone.