CA_Open_Record_Channel()

Purpose

Open a record channel to read digital voice data.

Libraries

Blueworx Voice Response library (libvae.a)

Custom Server library (libca.a)

Syntax

#include “CA_header.h”
int CA_Open_Record_Channel(
short link_id,
   RECORD_CHANNEL_OPEN_ST * record_open_sp;
   CHANNEL_INFO_ST * channel_info_sp
);

Description

This subroutine opens a connection so that a custom server can read voice data from the telephony channel. Use this subroutine from a user function invoked with the SendData state table action when a call is active. This opens the record channel as a background task, leaving the state table free to continue.

The channel can only be opened once for recording. File descriptors for open channels are not inherited by child processes, so any subsequent actions to start, stop, or close the record channel must be issued by the process which issued the open.

Voice data cannot be read from the record channel once it has been opened. Before any data can be read, you must start the channel using the CA_Start_Record_Channel() subroutine.

You should not add the channel to the CA_Poll() until the channel is started, otherwise CA_Poll() returns immediately to inform the custom server that recording is not yet active.

If the subroutine is issued when the channel process (referenced by the link_id parameter) does not have an active call, this subroutine fails with an appropriate error.

It is the responsibility of the custom server to close the record channel, using CA_Close_Record_Channel(), before it can be used again to record more voice data, for a new call instance on the same trunk and channel.

The record channel can also be used for barge in applications where the associated state table is playing voice while the record channel is running in the background passing voice data to external speech servers awaiting a result.

Open and start the record channel in the background before the play actions are run as foreground tasks controlled by the channel process.

Parameters

link_id

The ID of the channel process that owns the voice channel, provided by a previous call to CA_Receive_DT_Msg(). Blueworx Voice Response uses this parameter to check that there is an active call associated with the channel process.

record_open_sp

A pointer to a RECORD_CHANNEL_OPEN_ST structure described in RECORD_CHANNEL_OPEN_ST. This specifies the maximum number of records predefined for storing voice, and the length of time to record before interrupting the custom server to read the data.

channel_info_sp

A pointer to a CHANNEL_INFO_ST output structure that will be filled in on return as described in CHANNEL_INFO_ST.

Return codes

0

Successful

-1

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

Error names

CA_CHANNEL_ALREADY_ALLOCATED
CA_CHANNEL_ALREADY_OPEN
CA_FUNC_FAILED
CA_INV_ADDR
CA_INV_CHANNEL
CA_INV_LINK_ID
CA_INV_MAX_RECORDS
CA_INV_PACK
CA_INV_RECORD_COUNT
CA_INV_VERSION
CA_NOT_INIT
CA_TERMINATING

Related information

CA_Close_Record_Channel(), CA_Record_Voice_Stream(), CA_Open_Channel(), CA_Poll(), CA_Start_Record_Channel(), CA_Stop_Record_Channel().