WaitEvent

Purpose

Use WaitEvent to specify a time to wait for an event to occur.

A screen capture of the Action WaitEvent window

Description

Use WaitEvent to find out when different events are posted, for example, when a caller has pressed a DTMF key, so that your state table can take appropriate action while a background record is in progress.

If multiple events have already occurred, all are flushed (cleared) but only one is reported. The order of precedence is:

Hangup
Line problem
Long silence
DTMF, fax or voice
Server event.

The hangup, line problem, and long silence events cannot be cleared. If it is likely that there is a server event to be received after one of these events has occurred, your state table should check by issuing a SendData followed by a ReceiveData.

In addition to DTMF, WaitEvent also detects custom server channel events indicated by the Host Event edge. WaitEvent handles the custom server event and updates SV232 (System: Custom server event: name of server), SV233 (System: Custom server event: information field), and SV234 (System: Custom server event: event data) with information about the event. These system variables are updated by the custom server using the CA_Report_Channel_Event() subroutine. WaitEvent also supports silence detection during remote duplex record.

Parameters

WaitEvent has one parameter.

Timeout. Specify the timeout in seconds, either as a variable or a constant. The valid range is -1 to MAXLONG/1000, where -1 means infinite timeout. (MAXLONG/1000 is 2147483647/1000 seconds, nearly 600 hours.)

Possible results

WaitEvent can have one of the following results:

Host Event: An event has been posted by a custom server. The name of the server posting the event is given in system variable SV232. The information field is stored in SV233, and the event data is stored in SV234.
The event will be cleared from the queue.
DTMF Event: The caller pressed a DTMF key. This event remains in the event queue until the key is read using the GetKey state table action.
Fax Event: A fax tone has been detected. Fax tones are detected only if system variable SV227 is not zero.
The event remains in the queue, so you should transfer this call to a fax line.
Voice Event: Voice energy has been detected. Voice energy is detected only if system variable SV217 is not zero, and is subject to the level and duration parameters specified by SV218, SV219 and SV220.
The event will be cleared from the queue.
Long Silence Event: The value defined in the maximum silence duration system parameter has been exceeded during a record. This event is not raised if the channel is operating in full duplex, that is, during simultaneous play and record.
If a long silence occurs, this is usually because there is no caller responding at the end of the line, perhaps because the caller has hung up, but this is not detected by the telephony protocol. Because of this, no further voice input or output is allowed on the line and it is expected thatthe call will now be hung up. If your application wishes to continue with voice input or output after receiving this event, you may perform a short record operation to clear the event.
Line Problem Event: A line problem has occurred.
There was a problem with the voice channel. The application should hang up the call.
Caller Hung Up: The caller has hung up, or the value defined in the maximum silence duration system parameter has been exceeded and the system has hung up the call to comply with homologation requirements.
The caller has hung up. The application should now hang up the call.
Timeout: No event occurred within the timeout period.
Invalid Timeout: The timeout value given was out of range.

ASCII syntax

When using an ASCII editor, code this action as shown below. The single parameter, either a constant or a variable, is used to specify the timeout value.

For example:

label3: "WaitEvent with 'timeout' as a variable"
WaitEvent(timeout)
edge EDGE_EVENT_HOST:
edge EDGE_EVENT_DTMF:
edge EDGE_EVENT_FAX:
edge EDGE_EVENT_VOICE:
edge EDGE_EVENT_LONG_SILENCE:
edge EDGE_EVENT_LINE_PROBLEM:
edge EDGE_HUP:
edge EDGE_TIMEOUT:
edge EDGE_EVENT_INVALID_TIMEOUT:
;

or,

label4: "WaitEvent with constant timeout value"
WaitEvent("12345")
edge EDGE_EVENT_HOST:
edge EDGE_EVENT_DTMF:
edge EDGE_EVENT_FAX:
edge EDGE_EVENT_VOICE:
edge EDGE_EVENT_LONG_SILENCE:
edge EDGE_EVENT_LINE_PROBLEM:
edge EDGE_HUP:
edge EDGE_TIMEOUT:
edge EDGE_EVENT_INVALID_TIMEOUT:
;

The parameters and edges are described above under "Parameters" and "Possible results". For more information, see Testing a state table using the debugger.