adiStartTones

Starts generating one or more tones.

Supported board types

Prototype

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

Argument	Description
ctahd	Context handle returned by ctaCreateContext or ctaAttachContext.
count	Number of entries in the parms array.
parms	Pointer to an array of tones 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*/ } ADI_TONE_PARMS; Refer to ADI_TONE_PARMS for field descriptions.

Return values

Return value	Description
SUCCESS
ADIERR_INVALID_CALL_STATE	Function not available in the current call state.
CTAERR_FUNCTION_ACTIVE	Function already active.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_INVALID_STATE	Function not available in the current port state.
CTAERR_OUTPUT_ACTIVE	Function failed because there is another active output function.
CTAERR_SVR_COMM	Server communication error.

Events

Event

Description

ADIEVN_TONES_DONE

The value field contains any of the following reasons:

CTAERR_xxx or ADIERR_xxx

Tone generation failed.

CTA_REASON_FINISHED

Tones generated.

CTA_REASON_STOPPED

Tone generation stopped by adiStopTones.

Details

The following DSP file must be loaded to the board before running adiStartTones:

For these boards...	Load this DSP file...
AG	tone.m54
CG	tone.f54

See DSP file summary for DSP file descriptions. Refer to the board installation and developer's manual for a table of MIPS usage for all functions.

Use this function to start generating a sequence of tones, each consisting of one or two frequencies and an iteration count. The DONE event is generated when the tone sequence completes.

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. The final iteration is complete when the offtime expires. To generate a tone continuously, set iterations to -1 and specify an offtime of 0 (zero).

Use adiStopTones to prematurely terminate tone generation.

For more information, refer to Generating tones.

Example

/* generates an Intralata Reorder SIT per BellCore */
int myPlaySITReorder( CTAHD ctahd )
{
    ADI_TONE_PARMS p[3] = {0};
    CTA_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 ctaWaitEvent example */

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