(Page 8 of 10 in this chapter)

2.7 About Asynchronous Programming and Events

In order to take advantage of concurrent processing between the host CPU and the AG board, AG Access supports an asynchronous programming model. Operations that do not complete inline are performed asynchronously from the application's primary execution path. Some of the AG Access operations that can be performed asynchronously are: Placing an outbound call Recording or playing voice data Generating tones Detecting tones
The application initiates asynchronous operations by invoking AG Access functions. AG Access constructs a command message that is sent to the AG board. During the operation's execution, events are sent up from the AG board 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. When the wait routine receives an event, the application invokes adiFetchAndProcess. adiFetchAndProcess may yield an event for the application, or the event may be consumed by the AG Access library (or by another API library in use by the application). Event detection and retrieval are discussed in Section 10.3.
Each asynchronous operation is terminated once AG Access generates a DONE event for the operation. A DONE event is the last event associated with the operation. The completion status is stored in the event value field.
Sample events include: ADIEVN_PLAY_DONE is the DONE event generated when a voice playback operation terminates. ADIEVN_CALL_DISCONNECTED is generated when the remote party disconnects. ADIEVN_DIGIT_BEGIN is generated when the remote party depresses a digit key on the telephone keypad. ADIEVN_DIGIT_END 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 additional information specific to the event. The ADI_EVENT structure contains the following fields: 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). ctahd The context handle of the port on which the event occurred. timestamp The AG board time when the event occurred. The value is always in milliseconds. The resolution for AG board events is 10 milliseconds. adiGetTimeStamp can convert this value into seconds and milliseconds since January 1, 1970. The seconds value can then be passed to C runtime functions. userid A user value supplied to adiOpenPort. value An event-specific value used to communicate a single 32-bit datum. size The 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.
For a comprehensive list of AG Access events, refer to 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`).
`ctahd`	The context handle of the port on which the event occurred.
`timestamp`	The AG board time when the event occurred. The value is always in milliseconds. The resolution for AG board events is 10 milliseconds. adiGetTimeStamp can convert this value into seconds and milliseconds since January 1, 1970. The seconds value can then be passed to C runtime functions.
`userid`	A user value supplied to adiOpenPort.
`value`	An event-specific value used to communicate a single 32-bit datum.
`size`	The 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 8 of 10 in this chapter)

tech_support@nmss.com