• 5.16.1. TN_GENCAD Overview
• 5.16.2. TN_GENCAD Definition
• 5.16.3. TN_GENCAD Parameters
• 5.16.4. Example of TN_GENCAD Cadenced Tone Definitions

5.16. TN_GENCAD: Cadenced Tone Generation Template

The TN_GENCAD data structure contains parameters for the Cadenced Tone Generation Template.

5.16.1. TN_GENCAD Overview

TN_GENCAD is a voice library data structure (DXXXLIB.H) that defines a cadenced tone that can be generated by using the dx_playtoneEx( ) function.

TN_GENCAD defines a signal by specifying the repeating elements of the signal (the cycle) and the number of desired repetitions. The cycle can contain up to 4 segments, each with its own tone definition and on/off duration, which creates the signal pattern or cadence. Each segment consists of a TN_GEN single- or dual-tone definition (frequency, amplitude, & duration) followed by a corresponding off-time (silence duration) that is optional. The dx_bldtngen( ) convenience function can be used to set up the TN_GEN components of the TN_GENCAD structure. The segments are seamlessly concatenated in ascending order to generate the signal cycle.

5.16.2. TN_GENCAD Definition

The typedef for the structure is as follows:

typedef struct {

   unsigned char cycles;      /* Number of cycles        */

   unsigned char numsegs;     /* Number of tones         */

   short         offtime[4];  /* Array of off-times      */

                              /* one for each tone       */

   TN_GEN        tone[4];     /* Array of tone templates */

} TN_GENCAD;

Since the 4 elements of tone array are TN_GEN data structures (Tone Generation Templates) the data structure is shown below for reference purposes.

typedef struct {

   unsigned short tg_dflag;   /* Dual Tone - 1, Single Tone - 0 */

   unsigned short tg_freq1;   /* Frequency for Tone 1 (HZ)      */

   unsigned short tg_freq2;   /* Frequency for Tone 2 (HZ)      */

   short          tg_ampl1;   /* Amplitude for Tone 1 (db)      */

   short          tg_ampl2;   /* Amplitude for Tone 2 (db)      */

   short          tg_dur;     /* Duration of the Generated Tone */

                              /* Units = 10ms           */

} TN_GEN;




5.16.3. TN_GENCAD Parameters

Field Name	Description
cycles	The cycles parameter specifies the number of times the cycle will be played from 1--255 (255 = infinite repetitions).
Numsegs	The numsegs parameter specifies the number of segments used in the cycle, from 1--4. A segment consists of a tone definition in the tone[ ] array plus the corresponding off-time in the offtime[ ] array. If you specify less than 4 segments, any data values in the unused segments will be ignored (if you specify 2 segments, the data in segments 3 and 4 will be ignored). The segments are seamlessly concatenated in ascending order to generate the cycle.
offtime[4]	The offtime[ ] array contains 4 elements, each specifying an off-time (silence duration) in 10 ms units that corresponds to a tone definition in the tone[ ] array. The offtime[ ] element is ignored if the segment is not specified in numsegs. The off-times are generated after the tone on-time (TN_GEN tg_dur), and the combination of tg_dur and offtime produce the cadence for the segment. Set the offtime = 0 to specify no off-time for the tone.
tone[4]	The tone[ ] array contains 4 elements that specify TN_GEN single- or dual-tone definitions (frequency, amplitude, & duration). The tone[ ] element is ignored if the segment is not specified in numsegs. The dx_bldtngen( ) function can be used to set up the TN_GEN tone[ ] elements. At least one tone definition, tone[0], is required for each segment used, and you must specify a valid frequency (tg_freq1); otherwise an EDX_FREQGEN error is produced. See the TN_GEN structure for more information.

5.16.4. Example of TN_GENCAD Cadenced Tone Definitions

For examples of TN_GENCAD, refer to the standard call progress signals used with the dx_playtoneEx( ) function.

Click here to contact Dialogic Customer Engineering