CA_Play_Voice_Stream()

Purpose

Play voice data 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_Stream (
  PLAY_VOICE_STREAM_PARM_ST *pvs_parm_sp,
  PLAY_VOICE_STREAM_RTN_ST *pvs_rtn_sp
);

Description

This subroutine plays digital voice data down the telephony connection on the specified channel. Use this subroutine when the voice data has been retrieved from an external speech server or other source, rather than CA_Play_Voice_Elements() (which is to be used when the data has come from another Blueworx Voice Response system). Your voice data must consist of 8-bit samples, sampled at 8000 Hz, in either μ-law or A-law format, depending on the trunk interface type.

The digitized voice data is played on the channel exactly as you present it. There is no check that the volume of the data is within permitted levels, nor that the format of the data is correct, for example that the data is in μ-law format on a T1 trunk, or in A-law format on an E1 trunk. It is the caller's responsibility to ensure that the directives of the network provider are obeyed.

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

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.

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

pvs_parm_sp: A pointer to a PLAY_VOICE_STREAM_PARM_ST input structure filled in as described in PLAY_VOICE_STREAM_PARM_ST.
pvs_rtn_sp: A pointer to a PLAY_VOICE_STREAM_RTN_ST output structure filled in on return from this subroutine, as described in PLAY_VOICE_STREAM_RTN_ST.

Return codes

0: Successful. All the voice data has 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_RECORD_COUNT
CA_NOT_CHANNEL_OWNER
CA_NOT_INIT
CA_TERMINATING

Related information

CA_Close_Channel(), CA_Close_Music_Channel(), CA_Open_Channel(), CA_Open_Music_Channel(), CA_Play_Voice_Elements(), CA_Poll(), CA_Record_Voice_Stream().