viWaitOnEvent
Purpose
Waits for an occurrence of the specified event for a given session.
C Syntax
ViStatus viWaitOnEvent(ViSession vi, ViEventType inEventType, ViUInt32 timeout, ViPEventType outEventType, ViPEvent outContext)
Visual Basic Syntax
viWaitOnEvent&(ByVal vi&, ByVal inEventType&, ByVal timeout&, outEventType&, outContext&)
Resource Classes
All I/O session types
Parameters
| Name | Direction | Description |
|---|---|---|
|
vi |
IN |
Unique logical identifier to a session. |
|
inEventType |
IN |
Logical identifier of the event(s) to wait for. |
|
timeout |
IN |
Absolute time period in time units that the resource shall wait for a specified event to occur before returning the time elapsed error. The time unit is in milliseconds. |
|
outEventType |
OUT |
Logical identifier of the event actually received. |
|
outContext |
OUT |
A handle specifying the unique occurrence of an event. |
Return Values
| Completion Codes | Description |
|---|---|
|
VI_SUCCESS |
Wait terminated successfully on receipt of an event occurrence. The queue is empty. |
|
VI_SUCCESS_QUEUE_NEMPTY |
Wait terminated successfully on receipt of an event notification. There is still at least one more event occurrence of the type specified by inEventType available for this session. |
|
VI_WARN_QUEUE_OVERFLOW |
The event returned is valid. One or more events that occurred have not been raised because there was no room available on the queue at the time of their occurrence. This could happen because VI_ATTR_MAX_QUEUE_LENGTH is not set to a large enough value for your application and/or events are coming in faster than you are servicing them. |
| Error Codes | Description |
|---|---|
|
VI_ERROR_INV_OBJECT |
The given session reference is invalid. |
|
VI_ERROR_INV_EVENT |
Specified event type is not supported by the resource. |
|
VI_ERROR_TMO |
Specified event did not occur within the specified time period. |
|
VI_ERROR_NENABLED |
The session must be enabled for events of the specified type in order to receive them. |
|
VI_ERROR_QUEUE_OVERFLOW |
No new event is raised because there is no room available on the queue. This means you have already received all previous events but not closed them. You must call viClose on each event you receive from viWaitOnEvent. |
Description
The viWaitOnEvent() operation suspends the execution of a thread of an application and waits for an event of the type specified by inEventType for a time period specified by timeout. You can wait only for events that have been enabled with the viEnableEvent() operation. Refer to individual event descriptions for context definitions. If the specified inEventType is VI_ALL_ENABLED_EVENTS, the operation waits for any event that is enabled for the given session. If the specified timeout value is VI_TMO_INFINITE, the operation is suspended indefinitely. If the specified timeout value is VI_TMO_IMMEDIATE, the operation is not suspended; therefore, this value can be used to dequeue events from an event queue.
When the outContext handle returned from a successful invocation of viWaitOnEvent() is no longer needed, it should be passed to viClose().
If a session's event queue becomes full and a new event arrives, the new event is discarded. The default event queue size (per session) is 50, which is sufficiently large for most applications. If an application expects more than 50 events to arrive without having been handled, it can modify the value of the attribute VI_ATTR_MAX_QUEUE_LENGTH to the required size.
The outEventType and outContext parameters are optional and can be VI_NULL. This can be used if the event type is known from the inEventType parameter, or if the outContext handle is not needed to retrieve additional information. If VI_NULL is used for the outContext parameter, VISA will automatically close the event context.
Related Topics