Table of Contents Index NMS Glossary Previous Page Next Page (Page 41 of 69 in this chapter) Version

adiStartPlaying

Description

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

Note: This function operates in L mode only.

Prototype

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

ctahd CTA context handle returned by ctaCreateContext.

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;

Return Values

Events

DSP File

For AG and CG hardware, each encoding rate of this function requires a specific DSP file to be loaded by agmon. For more information about DSP files and encoding rates refer to the table in the adiPlayAsync description.

Note: Refer to the QX 2000 Installation and Developer's Manual for DSP file information specific to the QX board family. Refer to the AG 2000 Installation and Developer's Manual, the AG 4000 Installation and Developer's Manual, and the AG 4000C Installation and Developer's Manual for the DSP files for the AG 2000 and AG 4000/C boards. Refer to the CG 6000C Installation and Developer's Manual for the DSP files for the CG 6000C board.

Refer to the board-specific installation and developer's manual for a table of MIPS usage for all functions.

Details

The ADI_PLAY_PARMS structure holds the following fields:
Field

 Description

DTMFabort

 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 zero (0) 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

 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

 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.

For QX hardware, the maxspeed and speed parameters are not used.

The ADI service 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 (for example, read data from a file) before returning.

access is invoked from within adiStartPlaying for the first buffer and subsequently invoked from within ctaWaitEvent. 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 the ADI service).

access has the following return values:

If the access return value is neither SUCCESS nor ADI_PLAY_LAST_BUFFER, then the ADI service 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 the ADI service 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. You may not be able to run the number of ports normally supported. Refer to the board-specific installation and developer's manual for more information.

See Also

adiPlayAsync, adiPlayFromMemory, adiStopPlaying, adiGetPlayStatus, adiModifyPlayGain, adiModifyPlaySpeed

Example

This 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 )
{
 CTA_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 ctaWaitEvent example */
    } while( event.id != ADIEVN_PLAY_DONE );

    fclose( fp );

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

Table of Contents Index NMS Glossary Previous Page Next Page (Page 41 of 69 in this chapter) Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com
Copyright © 2000, Natural MicroSystems, Inc. All rights reserved.