cnfStartTone

Plays a tone to all members of the conference.

Prototype

DWORD cnfStartTone ( CNFRESOURCEHD reshd, DWORD confid, CNF_TONE_PARMS *parms)

Argument	Description
reshd	Resource handle returned by cnfOpenResource.
confid	Conference identifier returned by cnfCreateConference.
parms	Pointer to a CNF_TONE_PARMS structure: 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 */ } CNF_TONE_PARMS; Refer to CNF.TONE for a description of these fields.

Return values

Return value	Description
SUCCESS
CTAERR_BOARD_ERROR	Tone cannot be generated because the board stopped responding.
CTAERR_INVALID_HANDLE	reshd is not a valid conference handle.
CNFERR_CONFERENCE_EMPTY	Conference confid currently has no members.
CNFERR_INVALID_IDENTIFIER	confid is not a valid conference identifier.
CNFERR_INVALID_PARAMETER	parms is inconsistent or out of range.

Events

Event	Description
CNFEVN_TONE_DONE	Tone generation completed or was stopped. Generated only if event_mask is set to CNF_EVNMSK_TONE_DONE when the function is called and the function returns SUCCESS.

Details

cnfStartTone plays a tone to all conference members to indicate that a new member is joining or leaving the conference. When this function is invoked, members stops hearing each other and hear only the tone.

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 (forever), set iterations to -1 and specify an offtime of 0 (zero). Use cnfStopTone to terminate tone generation prematurely.

For more information, refer to Playing a tone.

Example

extern CNFRESOURCEHD cnfresourcehd;

int myConferenceTone( DWORD confid )
{
CTA_EVENT event;
CNF_TONE_PARMS toneparms;

  // Fill the tone structure
  toneparms.size = sizeof(CNF_TONE_PARMS);
  toneparms.freq1 = 1000;
  toneparms.ampl1 = -20;
  toneparms.freq2 = 500;
  toneparms.ampl2 = -20;
  toneparms.ontime = 200;
  toneparms.offtime = 200;
  toneparms.iterations = 2;

  cnfStartTone ( cnfresourcehd, confid, &toneparms);

    do
    {
        myGetEvent( &event );        /* see ctaWaitEvent example */
    } while( event.id != CNFEVN_TONE_DONE );

    if( CTA_IS_ERROR( event.value ) )
        return MYFAILURE;            /* API error                */
    else
        return SUCCESS;              /* started successfully     */
}