Starts playing one message from the specified voice object.

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

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;

See the Details section for a description of these fields.

• SUCCESS
• CTAERR_FUNCTION_ACTIVE
  Playing or recording is already active on the CTA 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 CTA context.
• VCEERR_INVALID_MESSAGE
  The specified message number is invalid.

• VCEEVN_PLAY_DONE
  Play completed. The value field of the event contains one of the following reasons or an error code:
• CTA_REASON_DIGIT
  A touch-tone digit was received and the corresponding bit in the DTMF abort parameter was set.
• CTA_REASON_FINISHED
  The end of the current message or list was reached.
• CTA_REASON_RECOGNITION
  Stopped because of a speech recognition event.
• 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.
• CTA_REASON_TIMEOUT
  The time limit maxtime was reached.
• CTAERR_FUNCTION_NOT_AVAIL
  The played object has encoding that is not supported.

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

vcePlayMessage always returns immediately and, 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 dependent on the object type:

Type	Range of Valid Message Numbers
VOX	0 to 32,767
Flat	0 to 65,535
Memory	0 to 65,535
WAVE	0 only

Note: The special message number VCE_ALL_MESSAGES allows you to play all messages in an object as one message.

After play ends, you can call vceGetContextInfo to get the number of milliseconds actually played, by looking at the position field of the context information.

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

The VCE_PLAY_PARMS structure contains the following fields:

Field Name	Default	Description
size	sizeof (VCE_PLAY_PARMS)	Size of this structure in bytes.
DTMFabort	0xffff	Abort on DTMF (bit mask).
gain	0 dB	Playing gain in decibels, or VCE_CURRENT_VALUE to use the most recent gain setting.
speed	100%	Initial speed in percent or VCE_CURRENT_VALUE to use the most recent speed setting.
maxspeed	100%	Maximum play speed in percent.

Note: Refer to Appendix C for more information about the play parameters.

vceDefineMessages, vcePlay, vcePlayList, vceSetPosition, vceStop

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