vcePlay

Starts playing from the current position in the current message.

Prototype

DWORD vcePlay ( CTAHD ctahd, unsigned maxtime, VCE_PLAY_PARMS *parms)

Argument

Description

ctahd

Handle returned by ctaCreateContext or ctaAttachContext.

maxtime

Maximum amount to play, in milliseconds. Use VCE_NO_TIME_LIMIT to play with no time limit.

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_CTAHD

Context handle is invalid.

CTAERR_OUTPUT_ACTIVE

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

CTAERR_SVR_COMM

Server communication error.

VCEERR_NO_MESSAGE

No current message in the context.


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.

CTA_REASON_TIMEOUT
Time limit maxtime was reached.

CTAERR_FUNCTION_NOT_AVAIL
Played object has encoding that is not supported.


Details

vcePlay initiates playing from the current position in the current message for the specified context. The current message is defined by vceConvertMessage, vceCopyMessage, vceEraseMessage, vcePlayList, vcePlayMessage, vceRecordMessage, vceSetCurrentList, or vceSetCurrentMessage.

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

The current position is advanced by the number of milliseconds actually played. The number of milliseconds played is reported in the size field of the VCEEVN_PLAY_DONE event.

If the current position is already at the end of the current message, vcePlay returns SUCCESS and the DONE event occurs immediately.

Use this function to resume play after stopping a message in the middle. Use vceSetPosition to adjust the current position before resuming (for example, if you want to rewind or fast forward).

EDTX encoding types are not supported.

Refer to Playing for more information.

See also

vceStop

Example

/* Sample to reposition play. Play a message, allowing pause, forward, and */
/* rewind using digits 8, 9, and 7, respectively. Any other digit stops    */
/* play. The function returns the reason for stopping.                     */

extern CTAHD      Ctahd;
extern CTAQUEUEHD CtaQueueHd;

int myFancyPlay(VCEHD vh, unsigned message)
{
    BOOL      done   = FALSE;
    BOOL      paused = FALSE;
    CTA_EVENT event;
    char      digit;

    vcePlayMessage (vh, message, NULL);
    while (!done)
    {
        ctaWaitEvent( CtaQueueHd, &event, CTA_WAIT_FOREVER);
        if (event.id == VCEEVN_PLAY_DONE)
        {
            if (event.value == CTA_REASON_DIGIT)
            {
                adiPeekDigit(Ctahd, &digit);
                switch (digit)
                {
                    case '7':                     /* Rewind 2 seconds */
                        vceSetPosition (Ctahd, -2000, VCE_SEEK_CUR, NULL);
                        break;
                    case '8':                     /* Toggle pause     */
                        paused = !paused;
                        break;
                    case '9':                    /* Forward 2 seconds */
                        vceSetPosition (Ctahd, 2000, VCE_SEEK_CUR, NULL);
                        break;
                    default:
                        done = TRUE;
                        break;

                 }
                 if (!done)
                 {

                    /* Remove and discard the digit */
                    adiGetDigit (Ctahd, &digit);

                    if (!paused)
                        vcePlay(Ctahd, VCE_NO_TIME_LIMIT, NULL);
                }
            }
            else
                done = TRUE;
        }
        /* Ignore other events */
    }
    return event.value;
}