Starts the generation of one or more tones.

DWORD adiStartTones( CTAHD ctahd,
unsigned count,
ADI_TONE_PARMS *parms )

ctahd Context handle returned by adiOpenPort.

count The number of entries in the parms array.

parms Pointer to an array of tones, each defined by the following structure (NULL designates default values):

typedef struct
{
 DWORD size ;    /* size of this structure                */
 DWORD freq1;    /* first frequency (Hz)                  */
 INT32 ampl1;    /* level of first tone (dBm)             */
 DWORD freq2;    /* second frequency (Hz)                 */
 INT32 ampl2;    /* level of second tone (dBm)            */
 DWORD ontime;    /* on duration of DTMF tone (ms)         */
 DWORD offtime;    /* off duration of DTMF tone (ms)        */
 INT32 iterations; /* times to repeat above; -1 = forever  */
     /* last offtime is trimmed if repeat>1   */
} ADI_TONE_PARMS;

• SUCCESS
• ADIERR_INVALID_CALL_STATE
• CTAERR_FUNCTION_ACTIVE
• CTAERR_INVALID_CTAHD
• CTAERR_INVALID_STATE
• CTAERR_OUTPUT_ACTIVE

• ADIEVN_TONES_DONE
  The value field may contain any of the following reasons:
• CTAERR_xxx or ADIERR_xxx
  Tone generation failed.
• CTA_REASON_FINISHED
  Tones have been generated.
• CTA_REASON_STOPPED
  Tone generation stopped by adiStopTones.

This function requires that tones.dsp has been loaded by agmon.

Starts generation of a sequence of tones, each consisting of one or two frequencies and an iteration count. The DONE event is generated when the tone sequence has completed.

Each tone within the sequence comprises an ontime and an offtime, as well as an iterations count, all of which are contained in the ADI_TONE_PARMS structure. If the iterations count is one (1), the tone is not complete until the offtime has expired. If the iterations count is more than one, then the final offtime is omitted.

To generate a tone continuously (i.e. forever), set iterations to -1 and specify an offtime of 0 (zero).

Tone generation can be terminated prematurely using the adiStopTones command.

The ADI_TONE_PARMS structure contains the following fields:

Field	Description
freq1	The first of two frequencies or the only frequency of the tone to be generated (in Hz).
ampl1	The amplitude (in dBm) of the first frequency.
freq2	The second frequency (in Hz) if the tone to be generated contains two frequencies, or zero otherwise.
ampl2	The amplitude (in dBm) of the second frequency.
ontime	The duration (in ms) of the tone; specify -1 for a continuous tone.
offtime	The duration (in ms) of silence to follow the tone; specify 0 for no offtime.
iterations	The number of times to repeat the tone (and silence period); specify -1 to repeat a cadence tone forever.

adiStopTones, adiStartDTMF

/* generates an Intralata Reorder SIT per BellCore */
int myPlaySITReorder( CTAHD ctahd )
{
    ADI_TONE_PARMS p[3] = {0};
    ADI_EVENT      event;
    int            tonecnt = 3;

    p[0].freq1 = 914;  p[0].ampl1 = -24; p[0].ontime = 275; p[0].iterations = 1;
    p[1].freq1 = 1429; p[1].ampl1 = -24; p[1].ontime = 380; p[1].iterations = 1;
    p[2].freq1 = 1777; p[2].ampl1 = -24; p[2].ontime = 380; p[2].iterations = 1;

    if( adiStartTones( ctahd, tonecnt, p ) != SUCCESS )
        return MYFAILURE;

    while( 1 )
    {
        myGetEvent( &event );           /* see adiFetchAndProcess example */

        switch( event.id )
        {
            case ADIEVN_TONES_DONE:
                if( event.value == CTA_REASON_RELEASED )
                    return MYDISCONNECT;    /* call has been terminated */
                else if( IS_ADI_ERROR( event.value ) )
                    return MYFAILURE;       /* API error */
                else
                    return SUCCESS;         /* stopped normally */
                break;
        }
    }
}