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.