2.8 Asynchronous Programming

(Page 9 of 11 in this chapter)

In order to take advantage of concurrent processing between the host CPU and the AG board, AG Access supports an asynchronous programming model. Activities that do not complete inline are performed asynchronously from the application's primary execution path. Examples include: Placing an outbound call Recording or playing speech Generating tones Detecting tones
The application initiates asynchronous functions by executing AG Access commands. Commands are executed by invoking functions resident in the AG Access library. AG Access processes data locally and then constructs a message that is sent to the AG board. During the function execution, AG Access generates events indicating the occurrence of certain conditions or state changes.
Receiving events is a two-step process. The application first waits for an AG event to occur by invoking an operating system specific wait routine and then invokes the adiFetchAndProcess function. Event detection and retrieval are discussed in Section 7.4, Command and Event Processing.
Each asynchronous function is terminated once AG Access generates a "done event" for the function. It is the last event generated relative to the function. The completion status is stored in the event value field.
Sample events include: ADIEVN_PLAY_DONE event is the done event generated when terminating speech playback. ADIEVN_CALL_DISCONNECTED event is generated when the remote party disconnects. ADIEVN_DIGIT_BEGIN event is generated when the remote party depresses a digit on the telephone keypad. ADIEVN_DIGIT_END event is generated when the remote party releases the digit on the keypad.
All events are represented as an ADI_EVENT `C' data structure. The structure informs the application what event occurred on which port, and provides ancillary information specific to the event. The ADI_EVENT structure contains the following information:

Field

Description

id

An AG Access event code for the event. All AG Access event codes are prefixed with ADIEVN_ (e.g., ADIEVN_PLAY_DONE).

porthd

The port handle on which the event occurred as returned from adiOpenPort.

timestamp

The AG board time when the event occurred. The value is always in milliseconds. The resolution for AG board events is 10 milliseconds. The adiGetTimeStamp function can convert this value into seconds and milliseconds since January 1, 1970. The seconds value can then be passed to 'C' runtime functions.

userid

User context value supplied to the adiOpenPort function.

value

An event-specific value used to communicate a single 32-bit datum.

size

Size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field may be used to hold an event-specific value.

buffer

If a buffer is returned with the event, this field points to data that is event-specific. The field contains an application buffer address while the event's size field contains the actual size of the buffer.
A comprehensive list of events can be found in Appendix B of the AG Access Function Reference Manual.

Field	Description
`id`	An AG Access event code for the event. All AG Access event codes are prefixed with `ADIEVN_` (e.g., `ADIEVN_PLAY_DONE`).
`porthd`	The port handle on which the event occurred as returned from adiOpenPort.
`timestamp`	The AG board time when the event occurred. The value is always in milliseconds. The resolution for AG board events is 10 milliseconds. The adiGetTimeStamp function can convert this value into seconds and milliseconds since January 1, 1970. The seconds value can then be passed to 'C' runtime functions.
`userid`	User context value supplied to the adiOpenPort function.
`value`	An event-specific value used to communicate a single 32-bit datum.
`size`	Size (bytes) of the area pointed to by `buffer`. If the buffer is `NULL`, this field may be used to hold an event-specific value.
`buffer`	If a buffer is returned with the event, this field points to data that is event-specific. The field contains an application buffer address while the event's `size` field contains the actual size of the buffer.

(Page 9 of 11 in this chapter)