eth32_dequeue_event

int eth32_dequeue_event(eth32 handle, eth32_event *event, int timeout);

Summary

This function retrieves information about an event from the internal API event queue and removes that entry from the queue. If the queue is empty and this function is instructed to do so, it will wait for an event to arrive from the device.

Events are dequeued in the sequence they arrived from the ETH32 device. The event queue must be enabled by setting a nonzero maximum queue size using the eth32_set_event_queue_config function.

Parameters

  • handle - The value returned by the eth32_open function.

  • event - Pointer to a structure which will receive all of the information about the event firing.

  • timeout - If the queue is empty, specifies how long to wait for an event to arrive. A positive number instructs the function to wait up to that many milliseconds, zero specifies that it should not wait, but instead return ETH32_TIMEOUT immediately, and a negative value specifies the function should wait indefinitely for an event to arrive.

Return Value

This function returns zero if an event was successfully dequeued. If an error occurs or the function times out waiting for an event, a negative error code is returned. Please see the Error Codes section for possible error codes.

Example
eth32 handle;
int result;
eth32_event event_info;

// .... Your code that establishes a connection here

// Retrieve the next event from the queue.  If there are no events 
// in the queue, wait up to 5 seconds for one to arrive.
result=eth32_dequeue_event(handle, &event_info, 5000);
if(result==ETH32_TIMEOUT)
{
	// No event was in the queue and none arrived within 5 seconds
}
else if(result)
{
	// Some other error occurred
}
else
{
	// An event was successfully dequeued
	printf("Event ID %d was dequeued.  Its new value is %d\n", event_info.id, event_info.value);
}
         
See Also

eth32_empty_event_queue, eth32_set_event_queue_config