CA_Start_Record_Channel()

Purpose

Start recording digital voice data on a record channel.

Libraries

Blueworx Voice Response library (libvae.a)

Custom Server library (libca.a)

Syntax

#include "CA_header.h"
int CA_Start_Record_Channel (
  RECORD_CHANNEL_START_ST *record_start_sp,
  CHANNEL_INFO_ST *chan_info_sp,
  RECORD_CHANNEL_START_RTN_ST *record_start_rtn_sp
)

Description

This subroutine specifies what events will trigger the recording of voice data.

The record channel must have already been opened using CA_Open_Record_Channel(). CA_Start_Record_Channel() must be called by the same process which opened the channel, or it fails. Once the subroutine has been issued, you can use CA_Record_Voice_Stream() to read data. Use CA_Poll() to find out when the read can take place without waiting.

If your custom server uses CA_Poll() to detect when there is data on the channel to be read, you should add the channel to the channel list after using CA_Start_Record_Channel(). When recording has not started or when it is stopped because of a DTMF event or channel problem, CA_Poll() returns immediately if it contains the channel pointer in its Poll list to say there is no data to read.

The subroutine fails if the call associated with the record channel has been cleared or is not active.

The start parameters are defined in the RECORD_CHANNEL_START_ST structure:

• Use the echo_cancel parameter to request that the voice data stream is echo cancelled. Echo cancellation is done only if the associated channel process has successfully requested echo cancellation in the application. If the request was unsuccessful the start succeeds, but the data read from the record channel will not be echo cancelled. Check the echo_cancel_state parameter in the RECORD_CHANNEL_START_RTN_ST structure to see if echo cancellation was used.
• You can program recording to start sending the voice data stream only on a trigger_event. This means that you can synchronize on a specific event. This reduces the amount of data the custom server needs to process.
• Another option to the trigger_event field of the RECORD_CHANNEL_START_ST structure is RECORDSTART_TRIGGER_ON_VOICE_OR_DTMF_DETECT. This option means recording starts when either voice energy or a valid input of DTMF keys is detected.
• You can program the record channel to stop when it receives user-specified DTMF keys. This is independent of the DTMF keys set in the state table. If recording is stopped by DTMF, issue CA_Stop_Record_Channel() before trying to start another record on the channel.

The custom server can detect either a DTMF or a call hangup event (which stops the record) when CA_Record_Voice_Stream() returns CA_END_OF_DATA_REACHED by calling the CA_Stop_Record_Channel() subroutine (see CA_Stop_Record_Channel()) and looking at the stop_reason parameter in the return structure.

Parameters

chan_info_sp

A pointer to a CHANNEL_INFO_ST input structure, as returned from a previous call to CA_Open_Record_Channel().

record_start_sp

A pointer to a RECORD_CHANNEL_START_ST input structure which contains the parameters required to start recording. This structure is described in RECORD_CHANNEL_START_ST.

record_start_rtn_sp

A pointer to a RECORD_CHANNEL_START_RTN_ST output structure (described in  RECORD_CHANNEL_START_RTN_ST), filled in on return from this subroutine.

Return codes

0

Successful

-1

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

Error names

CA_ALREADY_STARTED
CA_CALL_ACCESS_DENIED
CA_CHANNEL_NOT_OPEN
CA_FUNC_FAILED
CA_INTERNAL_FD_ERROR
CA_INV_ADDR
CA_INV_CHANNEL
CA_INV_COMPRESSION_TYPE
CA_INV_ECHO_PARAMETER
CA_INV_FILTER_TYPE
CA_INV_HISTORICS
CA_INV_KEYS
CA_INV_PACK
CA_INV_TRIGGER_TYPE
CA_NOT_CHANNEL_OWNER
CA_NOT_INIT
CA_SIGNAL_RECEIVED
CA_TERMINATING

Related information

CA_Close_Record_Channel(), CA_Get_Record_Info(), CA_Open_Record_Channel(), CA_Poll(), CA_Record_Voice_Stream(), CA_Stop_Record_Channel().