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	The 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 has already called ctaWaitEvent on the same queue.

Events

CTAEVN_WAIT_TIMEOUT

Details

The application must call this function 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 has 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 will fail with the same error code.

An application can wait on wait objects outside of ctaWaitEvent by setting the ctaflags field in initparms to CTA_NOTIFY_UPDATE_WAITOBJS in ctaInitialize. 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 will be returned if there was no application event available as a result of wait object processing.

Refer to Using wait objects for more information.

Example

extern CTAQUEUEHD ctaqueuehd;
void myGetEvent( CTA_EVENT *event )
{
    DWORD ctaret ;

    ctaret = ctaWaitEvent( ctaqueuehd, event, CTA_WAIT_FOREVER );

    if (ctaret != SUCCESS)
    {
        printf( "\007ctaWaitEvent returned %x\n", ctaret);
        exit( 1 );
    }
    if ( event.buffer )
        {
           if ( ctaOwnsBuf = event.size & CTA_INTERNAL_BUFFER )
             /* 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.*/
        /* In Natural Access Client/Server mode, ensure proper release of
         * Natural Access owned buffers.
        */
        if ( ctaOwnsBuf )
        {
            ctaOwnsBuf = 0;
            ctaFreeBuffer( event.buffer );
        }
        int         ctaOwnsBuf = 0;

        return ;
}