# vcePlayMessage

Starts playing one message from the specified voice object.

#### Prototype

DWORD vcePlayMessage ( VCEHD vh, unsigned message, VCE_PLAY_PARMS *parms)

Argument | Description
vh | Handle of an open voice object.
message | Message number to play. Use zero (0) to play the contents of a flat file, WAVE file, or memory block.
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 | Specified message number is invalid.

#### 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

vcePlayMessage starts playing from the beginning of the specified message number in the voice object specified by vh.

vcePlayMessage always returns immediately. If the return is SUCCESS, a VCEEVN_PLAY_DONE event occurs when play completes.

All unused (or deleted) message numbers in the valid range refer to zero-length messages and do not result in an error when referenced.

The range of valid message numbers is determined by the file type:

File type | Range of valid message numbers
--- | ---
VOX | 0 to 32,767
Flat | 0 to 65,535
WAVE | 0 only
Memory | 0 to 65,535

Note: Use the special message number VCE_ALL_MESSAGES to play all messages in an object as one message.

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

The voice object and message number become the current message for the context in which the voice handle was opened. After play stops, resume playing from the current position with vcePlay. You can adjust the current position with vceSetPosition before resuming.

Refer to Playing for more information.

#### See also

vceDefineMessages, vcePlayList, vceStop

#### Example

/* play a message and wait for completion */
extern CTAHD CtaHd;
extern CTAQUEUEHD CtaQueueHd;
void myPlaymsg(VCEHD vh, unsigned message)
{
CTA_EVENT event;
vcePlayMessage (vh, message, NULL) ;
do
{
ctaWaitEvent( CtaQueueHd, &event, CTA_WAIT_FOREVER);
} while (event.id != VCEEVN_PLAY_DONE); /* Ignore other events */
}