CA_Play_Voice_Elements()

Purpose

Play voice data (stored as Blueworx Voice Response voice elements) to the caller.

Libraries

Blueworx Voice Response library (libvae.a)

Custom Server library (libca.a)

Syntax

#include "CA_header.h"
#include "CA_access_db.h"
int CA_Play_Voice_Elements (
  PLAY_VOICE_ELEMENTS_PARM_ST *pve_parm_sp,
  PLAY_VOICE_ELEMENTS_RTN_ST *pve_rtn_sp
);

Description

This subroutine plays digital voice data down the telephony connection on the specified channel or a music channel. Use this subroutine, rather than CA_Play_Voice_Stream(), when playing voice data retrieved from a remote Blueworx Voice Response system because this data is stored in the correct format.

The voice data must be of the format returned by CA_Get_Audio_Name(), CA_Get_Greeting(), CA_Get_Segment(), or CA_Get_Voice_Msg(). For voice channels (opened with CA_Open_Channel()), the data may be compressed or uncompressed. For music channels (opened with CA_Open_Music_Channel()) it must be uncompressed.

The voice channel must have been opened in write mode, by a call to CA_Open_Channel() or CA_Open_Music_Channel().

When the voice data is played it is important that there is no delay between the end of one piece of voice data and the start of the next. This delay is called underrun. The value of the play flag in the input PLAY_VOICE_ELEMENTS_PARM_ST should be set to indicate whether the voice data should be continuous with a subsequent call to this routine. On return, the underrun value in the PLAY_VOICE_ELEMENTS_RTN_ST has been set to inform you whether underrun occurred. If your program cannot provide the voice data quickly enough, it may be necessary to buffer the voice data to avoid underrun. This buffering is the responsibility of your custom server code. For music channels it is recommended that you set play_flags to PERMIT_UNDERRUN.

The use of memory is most efficient when this subroutine is called with voice data in integer multiples of 4000 bytes. For example, repeatedly sending 2000 bytes would only populate half the voice data buffer memory within the device driver.

Parameters

pve_parm_sp

A pointer to a PLAY_VOICE_ELEMENTS_PARM_ST input structure filled in as described in PLAY_VOICE_ELEMENTS_PARM_ST.

pve_rtn_sp

A pointer to a PLAY_VOICE_ELEMENTS_RTN_ST output structure filled in on return from this subroutine, as described in PLAY_VOICE_ELEMENTS_RTN_ST.

Return codes

0

Successful. All the elements have been written and CA_errno is set to CA_NO_ERROR. However, if the wait flag was set to CA_NOWAIT, CA_errno may be set to CA_CHANNEL_WOULD_BLOCK indicating that a blocking condition occurred, and the write is incomplete.

-1

Unsuccessful (global error number CA_errno is set to indicate the error)

Error names

CA_CHANNEL_NOT_OPEN
CA_FUNC_FAILED
CA_HANGUP
CA_INV_ADDR
CA_INV_CHANNEL
CA_INV_CHANNEL_MODE
CA_INV_COMPRESSION_TYPE
CA_INV_ELEMENT_COUNT
CA_INV_VOICE_ELEMENT
CA_NOT_CHANNEL_OWNER
CA_NOT_INIT
CA_TERMINATING

Related information

CA_Close_Channel(), CA_Close_Music_Channel(), CA_Get_Audio_Name(), CA_Get_Greeting(), CA_Get_Segment(), CA_Get_Voice_Msg(), CA_Open_Channel(), CA_Open_Music_Channel(), CA_Play_Voice_Stream(), CA_Poll(), CA_Record_Voice_Stream().