CA_Report_Channel_Event()

Purpose

Reports to the channel process that the custom server has an event to be processed.

Libraries

Blueworx Voice Response library (libvae.a)

Custom Server library (libca.a)

Syntax

#include "CA_header.h"
int CA_Report_Channel_Event(
  CHANNEL_INFO_ST *chan_info_sp
  int event;
  unsigned long information;
)

Description

Use this subroutine to report asynchronously to the channel process that an event has occurred relating to a specific trunk and channel. If there is an active call being processed by the channel process, CA_Report_Channel_Event() succeeds. If there is no active call, it fails and the channel process does not see this event.

Use this subroutine only when the event takes precedence over any play actions that the channel process application wants to perform. Play actions are executed without playing any voice until the custom server event has been retrieved by the application.

Define the event to be reported in the event parameter. Specify any additional information relating to the event in the information parameter.

The state table can detect events reported by this subroutine by using:

• The WaitEvent state table action. WaitEvent waits until an event is reported and updates SV180 with a custom server interrupt edge. WaitEvent can be issued after the event is reported. Events are queued and processed in sequence.
• Any non-forced Play state table action (except PlayVoiceFromHost, see below). If a play action is running while the event is issued by the custom server in the background, the state table action stops with a success result, and SV180 is updated with the custom server interrupt edge.
• The PlayVoiceFromHost state table action. The action currently being processed by the state table stops with a DTMF edge, and SV180 is updated with the custom server interrupt edge. It might be more appropriate to use CA_Close_Channel() to terminate the play and return the result or event by using the ReceiveData state table action.

You must use the WaitEvent state table action to retrieve events. WaitEvent dequeues the event which updates system variables with the event information, and also allows Play state table actions to play voice unless there are more events to be retrieved.

The system variables used by CA_Report_Channel_Event() are:

System : Custom server event : name of server (SV232)

This variable contains the name of the custom server that originated the event.

System : Custom server event : event data (SV234)

This variable contains a number which represents a custom server event.

System : Custom server event : information field (SV233)

This variable contains additional information about the event reported in SV234.

CA_Report_Channel_Event() fails if the call associated with it has been cleared or is not active.

Parameters

chan_info_sp

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

event

Use this parameter to define your own events to the state table. Some event values are reserved: these are listed in CA_header.h.

information

Use this parameter to add additional information for the event. Some information values are reserved: these are listed in CA_header.h.

Return codes

0

Successful

-1

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

Error names

CA_CALL_ACCESS_DENIED
CA_FUNC_FAILED
CA_INV_CHANNEL
CA_NO_DEVICE
CA_NOT_INIT
CA_SIGNAL_RECEIVED
CA_TERMINATING

Related information

CA_Open_Channel(), CA_Open_Record_Channel(), CA_TDM_Connect().