# Event data structure

The ADI service uses an asynchronous programming model to capitalize on the concurrent processing between board processors and the host CPU. In response to commands executed by the application, the ADI service generates events that indicate certain conditions or state changes. All events are represented as a CTA_EVENT C data structure, as shown:

typedef struct
{
DWORD id; /* event id (ADIEVN_xxx in 'adidef.h') */
CTAHD ctahd; /* context handle */
DWORD timestamp; /* timestamp */
DWORD userid; /* user id (defined by ctaCreateContext) */
DWORD size; /* size of buffer if buffer != NULL */
/* otherwise, may contain event */
/* specific data */
void *buffer; /* buffer pointer */
DWORD value; /* Event status or event-specific data */
DWORD objHd; /* service client side object handle */
} CTA_EVENT;

This structure, returned by ctaWaitEvent, informs the application which event occurred on which context, and includes additional information specific to the event.

The CTA_EVENT structure contains the following fields:

Field | Description
--- | ---
id | ADI event code defined in the adidef.h header file. All ADI events are prefixed with ADIEVN_ (for example, ADIEVN_SOMETHING_HAPPENED).
ctahd | Context handle (the same as the one returned from ctaCreateContext).
timestamp | Time when the event was created in milliseconds. Use ctaGetTimeStamp to interpret the value. The resolution for AG board events is 10 milliseconds. For CG board events, the resolution is 1 millisecond.
userid | User-supplied value to ctaCreateContext. This field is unaltered by the ADI service and facilitates asynchronous programming. Its purpose is to correlate a port with an application object or context when events occur.
size | Size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field can hold an event-specific value.
buffer | Pointer to data returned with the event. The field contains an application process address and the event's size field contains the actual size of the buffer.
value | Event-specific value.
objHd | Service object handle for the client side.

## DONE events

A DONE event is a Natural Access event informing the application that an asynchronous function completed processing. DONE event codes are in the form ADI_function_DONE where function is the completed function (for example, PLAY, RECORD, COLLECTION). DONE events have no special physical or processing characteristics; they have the same physical structure and are retrieved identically as all other events.

An asynchronous function can return SUCCESS to the application when invoked and the function can later fail on the board. If the board detects an error when running a function, the ADI service delivers a DONE event to the application, and the event value field contains an error code.