Reads an event from the AG driver and updates AG Access internal state.

DWORD adiFetchAndProcess( unsigned drvid,
ADI_EVENT *event )

drvid Driver ID returned from adiOpenDriver.

event Pointer to the ADI_EVENT structure to be returned to the application.

• SUCCESS
• ADIERR_INVALID_QUEUEID
  Invalid drvid.
• CTAERR_BAD_ARGUMENT
  event is NULL.
• CTAERR_DRIVER_RECEIVE_FAILED
  No events pending in the AG driver.

Any of the AG Access events may be returned, depending on the contents of the AG driver queue.

This function retrieves an event from the AG driver and processes it. While processing, AG Access may generate an event for the application.

The application must supply a pointer to an ADI_EVENT structure in the event argument. AG Access assigns the structure before returning to the application.

Note: If the returned ADI_EVENT ID field is zero (0), this does not indicate an error condition. The event has been consumed by the AG Access library, and there is no event for the application to process.

To determine if an event is pending in the driver queue, use one of the following OS-specific mechanisms:

• UNIX - use poll with the muxhandle returned from adiOpenDriver as the file descriptor in the poll_fds[] array.

• OS/2 - use DosWaitEventSem with the muxhandle returned from adiOpenDriver as the event semaphore.

• NT - use any Win32 event-object wait function with the muxhandle returned from adiOpenDriver as the event- object. Examples include WaitForSingleObject, and WaitForMultipleObjects.

When the application is notified that an AG event is available, adiFetchAndProcess must be called to read and process the event. The event structure, shown below, is included in adi.h:

typedef struct
{
    DWORD   id;        /* event id                      */
    CTAHD   ctahd;     /* context handle                */
    DWORD   timestamp; /* timestamp                     */
    DWORD   userid;    /* user id                       */
    DWORD   size;      /* buffer size                   */
    void    *buffer;   /* buffer pointer                */
    DWORD   value;     /* Event-specific data           */
    DWORD   reserved ; 
} ADI_EVENT;

The ADI_EVENT structure contains the following fields:

Field	Description
id	All event codes are defined in the adidef.h header file and are prefixed with ADIEVN_ (e.g., ADIEVN_SOMETHING_DONE).
ctahd	Contains the context handle returned from adiOpenPort.
timestamp	The current system time in milliseconds since Midnight January 1, 1970 modulo 49 days. The value has a resolution of 10 milliseconds. See adiGetTimeStamp for details.
userid	The application supplies the userid to AG Access when opening the context; the userid is never altered. The userid facilitates asynchronous programming. Its purpose is to map the event with an application object/context.
value	An event-specific value. The value field may contain an AG Access error code if the AG board rejects a command. The error codes are identical to those returned by the API functions, and take the form CTAERR_xxx or ADIERR_xxx.
size	The amount of data (bytes) written to the address contained in ADI_EVENT buffer field.
buffer	Application buffer address when data is returned from AG Access. The address will always be one that was supplied by the application in a previous function call.

Note:	 If no data is contained in an event, buffer is NULL and size may contain a second event-specific DWORD value.

adiOpenDriver, adiOpenPort

/* This function blocks until an event message is available
 * and returns the received event to the calling routine.
 */
#if defined (OS2)
  #define INCL_DOSSEMAPHORES
  #include <os2.h>
#elif defined (UNIX)
  #include <poll.h>
#elif defined (WIN32)
  #include <windows.h>
#endif

extern unsigned   drvid;     /* driver id */
extern MUX_HANDLE muxhandle; /* muxable handle for event queue */

DWORD myGetEvent( ADI_EVENT *event )
{
    DWORD ret;

    do 
    {
        /*
         * Wait for an event (in a manner appropriate to the OS).
         */
#ifdef UNIX
        struct pollfd fds[1];
        fds[0].events = POLLIN;
        fds[0].fd     = muxhandle;

        if ( poll( fds, 1, -1 ) < 0 )
        {
            if ( errno == EINTR )
                continue;
            perror("poll");
            exit( 1 );
        }
#elif defined OS2
        APIRET ret = DosWaitEventSem( muxhandle, SEM_INDEFINITE_WAIT );
        if( ret != 0 )
        {
            printf( "Error on DosWaitEventSem: %d\n", ret );
            exit( 1 );
        }
#elif defined WIN32
        if( WaitForSingleObject( muxhandle, INFINITE ) == WAIT_FAILED )
        {
            printf( "Error on WaitForSingleObject: %d\n",
                    GetLastError() );
            exit( 1 );
        }
#endif

        /*
         * Have AG Access fetch the event and process it through its
         * internal state machine.
         */
        if( ( ret = adiFetchAndProcess( drvid, event ) ) != SUCCESS )
            break;

    } while( event->id == 0 );

    return ret;
}