Starts a playing operation using a callback routine to get data.

DWORD adiStartPlaying( CTAHD ctahd,
unsigned encoding,
ADIPLAY_ACCESS access
void *userarg,
ADI_PLAY_PARMS *parms )

ctahd Context handle returned by adiOpenPort.

encoding Data encoding selection (refer to adidef.h for a complete list of ADI_ENCODING_xxx values).

access Pointer to a callback function that supplies data to be played (a prototype of this function is given in the Details section.).

userarg An arbitrary pointer or value to be passed to the callback function every time it is invoked.

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

typedef struct
{      /* parms related to adiStartPlaying:    */
 DWORD size;     /* size of this structure          */
 DWORD DTMFabort;     /* abort on DTMF          */
 INT32 gain;     /* playing gain in dB          */
 DWORD speed;     /* initial speed in percent          */
 DWORD maxspeed;     /* maximum play speed in percent          */
} ADI_PLAY_PARMS;

• SUCCESS
• ADIERR_INVALID_CALL_STATE
• CTAERR_BAD_ARGUMENT
  Invalid encoding.
• CTAERR_FUNCTION_ACTIVE
• CTAERR_INVALID_CTAHD
• CTAERR_INVALID_STATE
• CTAERR_NO_MEMORY
  Could not allocate internal buffer
• CTAERR_OUTPUT_ACTIVE

• ADIEVN_PLAY_DONE
  Playing has terminated, with one of the following reasons in the value field:
• CTAERR_xxx or ADIERR_xxx
  AG Access error codes indicate play failed.
• CTA_REASON_DIGIT
  Aborted due to DTMF.
• CTA_REASON_FINISHED
  AG Access finished playing the last buffer.
• CTA_REASON_RECOGNITION
  Aborted because of speech recognition.
• CTA_REASON_RELEASED
  The call was terminated.
• CTA_REASON_STOPPED
  Stopped by application request.

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/voxp.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
okiply.dsp	ADI_ENCODE_OKI_24, ADI_ENCODE_OKI_32
waveply.dsp	ADI_ENCODE_PCM11M8, ADI_ENCODE_PCM11M16
g726p.dsp	ADI_ENCODE_G726

The ADI_PLAY_PARMS structure holds the following fields:

• DTMFabort is a mask indicating which DTMFs terminate playing. A bit set in the mask enables termination for the given DTMF. The bits are defined in adidef.h with the prefix ADI_DIGIT_.

• gain indicates the gain (or attenuation), in dB, applied while playing. Use 0 (zero) to play without applying gain. Valid range is -54 to +24. Values specified out of range will be translated into one of the boundary values.

• speed is the initial speedup/slowdown factor to apply to the encoded audio. The valid range is 50 - maxspeed. This value is ignored for encoding types for which speed modification is not supported.

• maxspeed is the maximum speed that will be used. The valid range is 100-200. This value is ignored for encoding types for which speed modification is not supported.

AG Access allocates a buffer and invokes the access function provided by the programmer. The buffer and size are passed to the callback function and the application must fill the buffer with voice data (e.g., read data from a file) before returning.

The access function is invoked from within adiStartPlaying for the first buffer, and subsequently invoked from within adiFetchAndProcess. The prototype for the callback function is:

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

userarg Pointer to value previously passed to adiStartPlaying.

buffer Pointer to memory to be filled with voice data.

size Size (bytes) of the buffer.

rsize Returned number of bytes of voice data put into the buffer by the callback routine (this value is returned to AG Access).

The access function has the following return values:

• SUCCESS
  Play continues as normal. AG Access will invoke access again when needed.
• ADI_PLAY_LAST_BUFFER
  When AG Access finishes playing the buffer being returned from access, ADIEVN_PLAY_DONE is generated with the value field set to CTA_REASON_FINISHED. access will not be invoked again for the current playing instance.

If the access return value is neither SUCCESS nor ADI_PLAY_LAST_BUFFER, then AG Access immediately terminates the playing instance. An ADIEVN_PLAY_DONE event is generated with the value field set to ADIERR_PLAYREC_ACCESS .

access returns the number of bytes written to the buffer in the rsize variable. If the returned size is larger than the buffer or the returned size is not a multiple of the framesize for the given encoding, then AG Access terminates the play function and generates an ADIEVEN_PLAY_DONE with the value field set to CTAERR_BAD_SIZE.

Note: Starting a play operation with the maxspeed parameter greater than 100 consumes additional DSP cycles on the AG board. You may not be able to run the number of ports normally supported. See the "Configuring Task Processors" appendix in the AG Access Installation Manual for more information.

adiPlayAsync, adiPlayFromMemory, adiStopPlaying, adiGetPlayStatus, adiModifyPlayGain, adiModifyPlaySpeed

The following example illustrates a fragment of a program which plays the file test.vce using adiStartPlaying and the associated access routine.

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

    *rsize = fread( buffer, 1, size, fp );

    if ( ferror( fp ) )
        return -1;
    if ( feof( fp ) )
        return ADI_PLAY_LAST_BUFFER;
    return SUCCESS;
}


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

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

    if( adiStartPlaying( ctahd, encoding, readAccess, fp, NULL ) != SUCCESS )
        return MYFAILURE;

    do 
    {
        myGetEvent( &event );           /* see adiFetchAndProcess example */
    } while( event.id != ADIEVN_PLAY_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 */
}