(Page 30 of 40 in this chapter)

vceRecordMessage

Description

Records a message in an open voice object.

Prototype

DWORD vceRecordMessage ( VCEHD vh,
unsigned message,
unsigned maxtime,
VCE_RECORD_PARMS *parms)
vh Handle of an open voice object.
message Message number to record.
maxtime Maximum amount to record, in milliseconds. Specify VCE_NO_TIME_LIMIT to record with no time limit.
parms Pointer to a parameter structure. Set this to NULL to use default values. The VCE_RECORD_PARMS structure is: typedef struct { DWORD size; DWORD DTMFabort; INT32 gain; DWORD novoicetime; DWORD silencetime; INT32 silenceampl; DWORD beepfreq; INT32 beepampl; DWORD beeptime; DWORD AGCenable; } VCE_RECORD_PARMS;
See the Details section for a description of these fields.

Return Values

SUCCESS
CTAERR_FUNCTION_ACTIVEPlaying or recording is already active on the CTA context.
CTAERR_INVALID_HANDLEvh is not a valid handle to an open voice object.
CTAERR_OUTPUT_ACTIVEAnother function is controlling the MVIP output timeslot of the CTA context.
VCEERR_INVALID_MESSAGEThe message number is out of range for the object.
VCEERR_OUT_OF_INDICESThe destination VOX file does not have any more free header entries.
VCEERR_PLAY_ONLYVoice file was not opened for record.

Events

VCEEVN_RECORD_DONERecording completed. The value field of the event contains one of the following reasons or an error code:
CTA_REASON_DIGITA touch-tone digit was received and the corresponding bit in the DTMF abort parameter was set.
CTA_REASON_FINISHED No more space is available, or recording in overwrite mode reached the end of the existing message.
CTA_REASON_NO_VOICE No voice detected for novoicetime milliseconds at the beginning of recording
CTA_REASON_RECOGNITION Stopped because of a speech recognition event
CTA_REASON_RELEASEDStopped because the call was disconnected.
CTA_REASON_STOPPEDStopped by vceStop, or the current message was invalidated because one of the referenced voice objects was closed.
CTA_REASON_TIMEOUT The time limit maxtime was reached.
CTA_REASON_VOICE_ENDSilence detected for silencetime milliseconds after some voice detected.
CTAERR_FUNCTION_NOT_AVAIL The recorded object has encoding that is not supported.

Details

This function starts recording to the specified message number in the voice object specified by vh. Any existing data in the message will be erased.
vceRecordMessage always returns immediately and, if the return is SUCCESS, a VCEEVN_RECORD_DONE event occurs when recording completes.
After recording ends, you can call vceGetContextInfo to get the number of milliseconds actually recorded, by looking in the position field of the status.
The voice handle and message number become the current message for the CTA context in which the voice handle was opened. After recording stops, you can resume recording at the end of the current message with vceRecord.
To trim data at the end of the recording:

Use vceSetPosition to back up the desired amount.

Use vceErase to erase data to the end of the message.
The VCE_RECORD_PARMS structure contains the following fields: Field Name Default Description size * Size of this structure in bytes. DTMFabort 0xffff Abort on DTMF (bit mask). gain 0 dB The gain in decibels applied to the signal before it is encoded. If Automatic Gain Control is enabled, this is the initial gain when recording starts. novoicetime 5000 ms The maximum length of silence at the beginning of a recording before recording will be stopped with a reason of CTA_REASON_NO_VOICE. Use zero (0) to disable this timer. silencetime 3000 ms The maximum length of silence after audio energy has been detected before record will be stopped with a reason of CTA_REASON_VOICE_END. Use zero (0) to disable this timer. silenceampl -45 dBm The maximum signal level, in dBm, that is considered to be silence. beepfreq 1000 Hz The frequency of the record beep tone. Use zero (0) to disable the beep. beepampl -20 dBm The amplitude of the beep tone. beeptime 200 ms The duration of the beep. AGCenable 0 Flag to enable Automatic Gain Control.
* The default for size field is sizeof (VCE_RECORD_PARMS). Note: Refer to Appendix C for more information about the record parameters.

See Also

vceRecord, vceStop

Example


/* Record to an existing VOX file. */

extern CTAQUEUEHD CtaQueueHd;

void myRecordFile (CTAHD ctahd, char *filename, unsigned msgnum)
{
    VCEHD     vh;
    CTA_EVENT event;

    vceOpenFile (ctahd, filename, VCE_FILETYPE_VOX,
                  VCE_PLAY_RECORD, 0, &vh) ;
    vceRecordMessage (vh, msgnum, VCE_NO_TIME_LIMIT, NULL)  ;
    do
    {
        ctaWaitEvent( CtaQueueHd, &event, CTA_WAIT_FOREVER);
    } while (event.id != VCEEVN_RECORD_DONE);/* Ignore other events */
    vceClose (vh);
}

(Page 30 of 40 in this chapter)

tech_support@nmss.com

Copyright © 1999, Natural MicroSystems, Inc. All rights reserved.