Table of Contents

Index

NMS Glossary

Previous Page

Next Page

(Page 27 of 41 in this chapter) Version

vcePlayMessage

Description

Starts playing one message from the specified voice object.

Prototype

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.

Return Values

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.
VCEERR_INVALID_MESSAGE
The specified message number is invalid.

Events

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_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.

Details

This function 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: The special message number VCE_ALL_MESSAGES allows you to play all messages in an object as one message.
After play ends, call vceGetContextInfo to get the number of milliseconds actually played and look at the position field of the context information.
The voice object and message number become the current message for the 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 B for more information about the play parameters.

See Also

vceDefineMessages, vcePlay, vcePlayList, vceSetPosition, 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 */
}

Table of Contents

Index

NMS Glossary

Previous Page

Next Page

(Page 27 of 41 in this chapter) Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com

Copyright © 2001, Natural MicroSystems, Inc. All rights reserved.