# 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 ;
}