# 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);
}