ctaWaitEvent

Retrieves an event from the specified queue.

Prototype

DWORD ctaWaitEvent ( CTAQUEUEHD ctaqueuehd, CTA_EVENT *ctaevt, unsigned timeout)

Argument

Description

ctaqueuehd

Context handle.

ctaevt

Pointer to the event structure to be filled. The CTA_EVENT structure is:

typedef struct
{
   DWORD   id;            /* Event code and source service ID       */
   CTAHD   ctahd;         /* Natural Access context handle          */
   DWORD   timestamp;     /* Timestamp                              */
   DWORD   userid;        /* Userid(defined by ctaCreateContext)    */
   DWORD   size;          /* Size of buffer if buffer != NULL       */
   void    *buffer;       /* Buffer pointer                         */
   DWORD   value;         /* Event status or event-specific data    */
   DWORD   objHd;         /* Service object handle                  */
} CTA_EVENT;

timeout

Time to wait (in milliseconds) for an event before returning control to the caller. Use CTA_WAIT_FOREVER for an infinite timeout.


Return values

Return value

Description

SUCCESS

 

CTAERR_INVALID_CTAQUEUEHD

Queue is being destroyed or has already been destroyed.

CTAERR_NOT_INITIALIZED

Natural Access is not initialized. Call ctaInitialize first.

CTAERR_SVR_COMM

Server communication error.

CTAERR_WAIT_FAILED

Operating-system-specific wait function returned an error.

CTAERR_WAIT_PENDING

Another thread already called ctaWaitEvent on the same queue.


Events

CTAEVN_WAIT_TIMEOUT

Details

Call ctaWaitEvent to retrieve an event from the application event queue.

If no events are already queued, the function blocks for the specified timeout, waiting for events to appear. If the timeout is exceeded, the event structure returns with a CTAEVN_WAIT_TIMEOUT code indicating that no events were pending and that the timeout condition occurred. In this case, the function returns SUCCESS.

If another thread destroys the queue, this function returns CTAERR_INVALID_CTAQUEUEHD. Subsequent calls to this function fail with the same error code.

An application can wait on wait objects outside of ctaWaitEvent by setting the ctaInitialize ctaflags field in initparms to CTA_NOTIFY_UPDATE_WAITOBJS. If wait objects are signaled in this instance, call ctaWaitEvent with timeout set to zero (0) to process and retrieve a waiting event. CTAEVN_WAIT_TIMEOUT is returned if there is no application event available as a result of wait object processing.

Refer to Using wait objects for more information.

See also

ctaFormatEvent, ctaQueryWaitObjects, ctaQueueEvent

Example

extern CTAQUEUEHD ctaqueuehd;
void myGetEvent( CTAHD ctahd, CTA_EVENT *event )
{
    DWORD ctaret ;
    BOOL ctaOwnsBuf = FALSE;

    ctaret = ctaWaitEvent( ctaqueuehd, event, CTA_WAIT_FOREVER );
    if (ctaret != SUCCESS)
    {
        printf( "\007ctaWaitEvent returned %x\n", ctaret);
        exit( 1 );
    }
    if ( event->buffer ) 
    {
       ctaOwnsBuf = event->size & CTA_INTERNAL_BUFFER;
       if ( ctaOwnsBuf )
       {
           /* This buffer is owned by Natural Access and will need to be
            * released back to Natural Access after processing of the buffer
            * is complete. Clear the Natural Access flags from the size field.
            */
           event->size &= ~CTA_INTERNAL_BUFFER;
       }
    }

    /* ... Process incoming event here .... */

    /* In Natural Access Client/Server mode, ensure proper release of
     * Natural Access owned buffers.
     */
    if ( ctaOwnsBuf )
    {
        ctaFreeBuffer( event->buffer );
    }
    return ;
}