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.
Blueworx Voice Response library (libvae.a)
Custom Server library (libca.a)
#include "CA_header.h" int CA_Poll ( void *ListPointer, unsigned long Nfdsmsgs, CHANNEL_POLL_ST ChanListPointer[], unsigned long NChans, long *CAqueueFlag, long Timeout );
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.
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.
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.
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