viEventHandler
Purpose
Event service handler procedure prototype.
C Syntax
ViStatus _VI_FUNCH viEventHandler(ViSession vi, ViEventType eventType, ViEvent context, ViAddr userHandle)
Visual Basic Syntax
N/A
Resource Classes
All I/O session types
Parameters
| Name | Direction | Description |
|---|---|---|
|
vi |
IN |
Unique logical identifier to a session. |
|
eventType |
IN |
Logical event identifier. |
|
context |
IN |
A handle specifying the unique occurrence of an event. |
|
userHandle |
IN |
A value specified by an application that can be used for identifying handlers uniquely in a session for an event. |
Return Values
| Completion Codes | Description |
|---|---|
|
VI_SUCCESS |
Event handled successfully. |
|
VI_SUCCESS_NCHAIN |
Event handled successfully. Do not invoke any other handlers on this session for this event. |
Description
viEventHandler() is not an actual VISA operation. Rather, it is the prototype for a user event handler that is installed with the viInstallHandler() operation. The user handler is called whenever a session receives an event and is enabled for handling events in the VI_HNDLR mode. The handler services the event and returns VI_SUCCESS on completion. The VISA system automatically invokes the viClose() operation on the event context when a user handler returns.
Because the event context must still be valid after the user handler returns (so that VISA can free it up), an application should not invoke the viClose() operation on an event context passed to a user handler.
 |
Note For advanced users—If the user handler will not return to VISA, the application should call viClose() on the event context to manually delete the event object. This situation may occur when a handler throws a C++ exception in response to a VISA exception event. |
Normally, an application should always return VI_SUCCESS from all callback handlers. If a specific handler does not want other handlers to be invoked for the given event for the given session, it should return VI_SUCCESS_NCHAIN. No return value from a handler on one session will affect callbacks on other sessions. Future versions of VISA (or specific implementations of VISA) may take actions based on other return values, so a user should return VI_SUCCESS from handlers unless there is a specific reason to do otherwise.
Related Topics