vcePlayList

Starts playing a list of messages.

Prototype

DWORD vcePlayList ( VCEHD vh, unsigned messagelist[], unsigned count, VCE_PLAY_PARMS *parms)

Argument

Description

vh

Handle of an open voice object.

messagelist

List of message numbers in vh to play as one contiguous message.

count

Number of messages in messagelist.

parms

Pointer to a parameter structure. Set this to NULL to use default values. The VCE_PLAY_PARMS structure is:

typedef struct
{
  DWORD size;
  DWORD DTMFabort;
  INT32 gain;
  DWORD speed;
  DWORD maxspeed;
} VCE_PLAY_PARMS;

Refer to VCE_PLAY_PARMS for a description of these fields.


Return values

Return value

Description

SUCCESS

 

CTAERR_FUNCTION_ACTIVE

Playing or recording is already active on the context.

CTAERR_INVALID_HANDLE

vh is not a valid handle to an open voice object.

CTAERR_OUTPUT_ACTIVE

Another function is controlling the MVIP output timeslot associated with the context.

CTAERR_SVR_COMM

Server communication error.

VCEERR_INVALID_MESSAGE

One or more message numbers is out of range for the type of voice file of vh.


Events

Event

Description

VCEEVN_PLAY_DONE

Play completed. The value field of the event contains one of the following reasons or an error code:

CTA_REASON_DIGIT
Touch-tone digit was received and the corresponding bit in the DTMF abort parameter was set.

CTA_REASON_FINISHED
End of the current message or list was reached.

CTA_REASON_RELEASED
Stopped because the call was disconnected.

CTA_REASON_STOPPED
Stopped by vceStop, or the current message was invalidated because one of the referenced voice objects was closed.

CTAERR_FUNCTION_NOT_AVAIL
Played object has encoding that is not supported.


Details

vcePlayList starts playing from the beginning of the first message in messagelist. Messages in the list are played as one contiguous message with no delays between messages.

This function enables a message to be built from a library of words or phrases contained in a single voice object. To concatenate messages from multiple objects, use vceSetCurrentList, followed by vcePlay.

vcePlayList always returns immediately. If it returns SUCCESS, a VCEEVN_PLAY_DONE event occurs when play completes. If there are no messages or if all messages have a length of zero (0), the VCEEVN_PLAY_DONE event occurs immediately.

To view the number of milliseconds actually played after play ends, call vceGetContextInfo and look at the position field of the returned structure.

The list of messages becomes the current message for the context specified by ctahd. After play stops, resume playing from the current position with vcePlay. Use vceSetPosition to adjust the current position to anywhere in the list before resuming.

Refer to Playing for more information.

See also

vceBuildPromptList, vcePlayMessage, vceStop

Example

/* Play digit string from prompt file */

/* This routine starts speaking a digit string.
 * The spoken digits "oh" through "nine" are in 10 messages in
 * DIGITS.VOX where msg 0 = "oh", msg 1 = "one", etc.
*/

extern CTAHD      CtaHd;
extern CTAQUEUEHD CtaQueueHd;

void mySpeakDigits (char *digits)
{
    unsigned  msglist[50];
    unsigned  count;
    VCEHD     vh;
    CTA_EVENT event;

    vceOpenFile (Ctahd, "DIGITS.VOX", 0, VCE_PLAY_ONLY, 0, &vh) ;

    for (count = 0;
        *digits != '\0' && count < sizeof msglist/sizeof msglist[0];
        digits++)
    {
        if (isdigit(*digits))
            msglist[count++]  = *digits - '0' ;
    }

    vcePlayList(vh, msglist, count, NULL);
do
{
        ctaWaitEvent( CtaQueueHd, &event, CTA_WAIT_FOREVER);
} while (event.id != VCEEVN_PLAY_DONE); /* Ignore other events */
vceClose(vh);
}