Starts a recording operation using a callback routine to deliver data.

DWORD adiStartRecording( CTAHD ctahd,
unsigned encoding,
unsigned maxtime,
ADIRECORD_ACCESS access,
void *userarg,
ADI_RECORD_PARMS *parms )

ctahd Context handle returned by adiOpenPort.

encoding Encoding type (refer to adidef.h for a complete list of ADI_ENCODING_xxx values).

maxtime Maximum recording time (in milliseconds). Use zero for no time limit.

access Pointer to a function that will receive recorded data (a prototype of this function is given in the Details section).

userarg An arbitrary pointer, whose value is passed to the callback function (access) on every invocation.

parms Pointer to record parameters according to the following structure (NULL uses default values):

typedef struct
{  
 DWORD size;     /* size of this structure         */
 DWORD DTMFabort;     /* abort on DTMF         */
 INT32 gain;     /* recording gain in dB         */
   /*-[SLC parms (used if silence det)]-----            */
 DWORD novoicetime;     /* length of initial silence to stop */
   /* recording (ms); use 0 to deactivate            */
   /* initial silence detection.            */
 DWORD silencetime;     
   /* length of silence to stop recording            */
   /* after voice has been detected (ms);            */
   /* use 0 to deactivate.            */
 INT32 silenceampl;     /* qualif level for silence (dBm)         */
 DWORD silencedeglitch;     
   /* deglitch while qualifying silence(ms)            */
   /*-[Beep for record]---------------------------*/
 DWORD beepfreq;     /* beep frequency (Hz)         */
 INT32 beepampl;     /* beep amplitude (dBm)         */
 DWORD beeptime;     /* beep time (ms) 0=no beep         */
 /*--[AGC parms]----------------------------------------*/
 DWORD AGCenable;     /* enable AGC; use 1 to activate         */
 INT32 AGCtargetampl; /* target AGC level (dBm)             */
 INT32 AGCsilenceampl; /* silence level (dBm)             */
 DWORD AGCattacktime;     /* attack time (ms)         */
 DWORD AGCdecaytime;     /* decay time (ms)         */
} ADI_RECORD_PARMS;

• SUCCESS
• ADIERR_INVALID_CALL_STATE
• CTAERR_BAD_ARGUMENT
  Either invalid encoding selected or NULL buffer pointer passed.
• CTAERR_BAD_SIZE
  size is less than one frame.
• CTAERR_FUNCTION_NOT_AVAIL
  Silence detector has been reserved by the protocol (TCP).
• CTAERR_INVALID_CTAHD
• CTAERR_INVALID_STATE
• CTAERR_FUNCTION_ACTIVE
  Record is already active, or the energy detector is active.
• CTAERR_OUTPUT_ACTIVE
• CTAERR_RESOURCE_CONFLICT
  Silence detector is in use by adiStartEnergyDetector.

• ADIEVN_RECORD_DONE
  The value field can contain one of the following:
• CTAERR_xxx or ADIERR_xxx
  AG Access error code indicates record failed.
• CTA_REASON_DIGIT
  Aborted due to DTMF.
• CTA_REASON_NO_VOICE
  No voice ever detected.
• CTA_REASON_RELEASED
  The call was terminated.
• CTA_REASON_STOPPED
  Stopped by application request.
• CTA_REASON_TIMEOUT
  Record time limit reached.
• CTA_REASON_VOICE_END
  User stopped speaking.

Each encoding rate of this function requires a specific DSP file to be loaded by agmon as shown in the following table:

DSP File	Encoding Rate
voice.dsp/voxr.dsp	ADI_ENCODE_NMS_16, ADI_ENCODE_NMS_24, ADI_ENCODE_NMS_32, ADI_ENCODE_NMS_64
rvoice.dsp	ADI_ENCODE_MULAW, ADI_ENCODE_ALAW, ADI_ENCODE_PCM8M16
okirec.dsp	ADI_ENCODE_OKI_24, ADI_ENCODE_OKI_32
wavrec.dsp	ADI_ENCODE_PCM11M8, ADI_ENCODE_PCM11M16
g726r.dsp	ADI_ENCODE_G726

This function starts a recording operation, which uses a callback routine (access) to deliver data.

DTMFabort, a field in the ADI_RECORD_PARMS structure, is a mask indicating which DTMFs abort recording.

gain, a field in the ADI_RECORD_PARMS structure, indicates the gain (or attenuation) in dB applied while recording. Use zero to record with no gain. Valid range is -54 to +24. Values specified out of range will be translated into one of the boundary values.

The novoicetime and silencetime values in the ADI_RECORD_PARMS structure determine how to treat silence detected during a record operation. novoicetime is the maximum time to wait for the speaker to start speaking at the beginning of a record operation. If no voice is detected by this time, record terminates with the reason CTA_REASON_NO_VOICE. After the speaker has started, if silence is detected for the duration specified by maxsilence, then the record operation terminates with the reason CTA_REASON_VOICE_END. You may bypass either of these timer parameters by passing a value of zero (0).

The silenceampl and silencedeglitch values in the ADI_RECORD_PARMS structure define the threshold for silence and a deglitch time when qualifying silence, respectively. We recommend that you use the default values.

AG Access allocates buffers and initiates recording. When a buffer fills with voice data, AG Access invokes the access function, passing it the buffer address and size. The application must copy the buffer to a storage medium before returning from the access function.

The access callback function is invoked from within adiFetchAndProcess. The prototype for the access function is as follows:

int NMSSTDCALL access( void *userarg,
void *buffer,
unsigned size )

userarg Pointer to value previously passed in to adiStartRecording.

buffer Pointer to memory allocated by AG Access.

size Size (bytes) of valid data in the buffer.

If the application's access returns any value other than SUCCESS, AG Access terminates the record operation and generates an ADIEVN_RECORD_DONE event with a value field of ADIERR_PLAYREC_ACCESS.

Note: You cannot initiate a record operation while playing voice or generating tones. You cannot start a record operation if the energy detector is active, unless both novoicetime and silencetime are zero.

adiRecordAsync, adiRecordToMemory, adiStopRecording, adiGetRecordStatus

The following example illustrates a fragment of a program which records into the file test.vce using adiStartRecording.

int NMSSTDCALL writeAccess(
    void *userarg,
    void *buffer,
    unsigned size )
{
    FILE *fp = (FILE *)userarg;

    fwrite( buffer, 1, size, fp );
    if ( ferror( fp ) )
        return -1;
    return SUCCESS;
}


int myRecordFile( CTAHD ctahd, unsigned encoding, char *filename )
{
    ADI_EVENT event;
    FILE     *fp;

    /* note: binary open */
    if( (fp = fopen( filename, "wb" )) == NULL )
        return MYFAILURE;

    if( adiStartRecording( ctahd, encoding, 0,
                           writeAccess, fp, NULL ) != SUCCESS )
        return MYFAILURE;

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

    fclose( fp );

    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 */
}