CA_Poll()

Purpose

Request to wait for a certain event to occur on a set of specified message queues, file descriptors, voice channels, or the custom server-to-Blueworx Voice Response message queue.

Libraries

Blueworx Voice Response library (libvae.a)

Custom Server library (libca.a)

Syntax

#include "CA_header.h"
int CA_Poll (
  void   *ListPointer,
  unsigned long    Nfdsmsgs,
  CHANNEL_POLL_ST    ChanListPointer[],
  unsigned long    NChans,
  long   *CAqueueFlag,
  long    Timeout
);

Description

This subroutine waits for a certain event to occur on a set of specified message queues, file descriptors, voice channels, or the custom server-to-Blueworx Voice Response message queue. This is an extension of the AIX poll subroutine.

When CA_Set_CA_Version() has been called with a version higher than CA_VERSION_UNSPECIFIED, polling is allowed for full duplex operations, otherwise only read or write is active on the channel for half duplex operation.

Full duplex operation is also supported when you allocate two CHANNEL_POLL_ST structures (one for read, one for write) for one voice channel. For information on the CHANNEL_POLL_ST structure, see CHANNEL_POLL_ST.

If CA_Poll() is waiting for an event on a voice channel that is opened for recording, with POLL_MODE_READ or POLL_MODE_NOT_DEFINED it will return when the amount of recorded data is greater than the Remote Play/Record Min Data or if the channel is not recording. The rtnevents parameter of the CHANNEL_POLL_ST structure will have the POLLIN bit set (see /usr/include/sys/poll.h). The Remote Play/Record Min Data is a system parameter which can be changed in the Application Server Interface parameter group. The calling function can quickly detect if recording is not running by issuing CA_Record_Voice_Stream() for the channel and checking to see if CA_errno is set to CA_END_OF_DATA_REACHED.

If CA_Poll() is waiting for an event on a voice channel that is opened for playing, with POLL_MODE_WRITE or POLL_MODE_NOT_DEFINED it will return when at least 4000 bytes can be written or the channel is not playing. The rtnevents parameter of the CHANNEL_POLL_ST structure will have the POLLOUT bit set (see /usr/include/sys/poll.h).

If CA_Poll() is waiting for an event on a voice channel that is opened for playing, with POLL_MODE_PRIORITY it will return when the channel is no longer available to play voice. Examples of events which cause this are hangup and stopped by DTMF. CA_Close_Channel() should be called immediately to complete the PlayVoiceFromHost state table action. The rtnevents parameter of the CHANNEL_POLL_ST structure will have the POLLPRI bit set (see /usr/include/sys/poll.h).

POLL_MODE_WRITE_AND_PRIORITY allows use of POLL_MODE_WRITE and POLL_MODE_PRIORITY together in the same CHANNEL_POLL_ST structure. The POLLPRI bit should be tested before the POLLOUT bit as POLLOUT is set when the POLLPRI conditions are met as well as when more data can be written by CA_Play_Voice_Stream().

If CA_Poll() is waiting for an event on a voice channel that is opened using CA_Open_Record_Channel(), it returns immediately if the channel is not recording and updates the rtnevents parameter in the CHANNEL_POLL_ST structure. The calling function can quickly detect if recording is not running by issuing CA_Record_Voice_Stream() for the channel and checking to see if CA_errno is set to CA_END_OF_DATA_REACHED.

If the end of data has been reached, then it is normally most efficient to remove the channel information from the ChanListPointer and decrement the number of channels in NChans. If this is not done, CA_Poll() might return immediately on the channel because it is not recording.

Parameters

ListPointer
For information, see the ListPointer parameter to the AIX poll subroutine.
Nfdsmsgs
For information, see the Nfdsmsgs parameter to the AIX poll subroutine.
ChanListPointer
A pointer to an array of CHANNEL_POLL_ST structures, as defined in CHANNEL_POLL_ST. These define the voice channels to be polled. On return, the rtnevents values are set for each voice channel.
NChans
The number of structures in the array pointed to by ChanListPointer.
CAqueueFlag
Set to 1 if you want to poll the custom server-to-Blueworx Voice Response message queue, otherwise set it to 0. On return contains the rtnevents value for the message queue.
Timeout
For information, see the Timeout parameter to the AIX poll subroutine.

Return codes

-1
Unsuccessful (global error number CA_errno is set to indicate the error). For more information, see the AIX poll subroutine.

If CA_errno is 65 (CA_FUNC_FAILED) use the errno global variable to check why the poll() system call invoked by the CA_library failed. For example, when the custom server receives a SIGINT from Blueworx Voice Response to tell the custom server to terminate, the errno for the poll() system call is 4 (EINTR) which indicates that the poll() system was interrupted by a signal.

0
Timeout. The subroutine timed out and none of the specified files or message queues indicated the presence of an event (all rtnevents fields were values of 0).
>0
Successful. The value indicates the total number of file descriptors and message queues that satisfy the selection criteria. The return value is similar to the Nfdsmsgs parameter in that the low-order 16 bits give the number of file descriptors, and the high-order 16 bits give the number of message queue identifiers that had nonzero rtnevents values. The NFDS and NMSGS macros, found in the sys/select.h file, can be used to separate these two values from the return value. If rc contains the value returned from the CA_Poll() subroutine NFDS(rc) is the number of files reporting some event or error and NMSGS(rc) is the number of message queues reporting some event or error.

Sometimes in a multi-processing custom server, CA_Poll() can return indicating that there is a message on a message queue, but a msgrcv() does not find one. This is because of internal processing by Blueworx Voice Response, and should not be treated as an error.

Error names

CA_CHANNEL_NOT_OPEN
CA_FUNC_FAILED
CA_INTERNAL_CHANNEL_MODE_ERROR
CA_INV_ADDR
CA_INV_CHANNEL
CA_INV_POLL_MODE
CA_MALLOC_FAILED
CA_NOT_CHANNEL_OWNER
CA_NOT_INIT
CA_TERMINATING

Related information

CA_Close_Channel(), CA_Open_Channel(), CA_Play_Voice_Elements(), CA_Play_Voice_Stream(), CA_Record_Voice_Stream().