viEventHandler
Syntax
viEventHandler(ViSession vi, ViEventType eventType, ViEvent context, ViAddr userHandle);
Description
This is a prototype for a function, which you define. The function you define 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. VISA event handlers must be declared as follows.
ViStatus _VI_FUNCH MyEventHandler(ViSession vi, ViEventType eventType, ViEvent context, ViAddr userHandle);
The _VI_FUNCH declaration is required to make sure the handler is of the proper type. If _VI_FUNCH is not included, stack corruption may occur on the function call or return. The _VI_FUNCH declaration is very important since it declares the function of type stdcall that VISA requires. Visual Studio C++ defaults to cdecl that will not work. When the handler returns, it will generate an access violation because the stack gets corrupted.
Because each eventType defines its own context in terms of attributes, refer to the appropriate event definition to determine which attributes can be retrieved using the context parameter.
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.
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 may occur when a handler throws a C++ exception in response to a VISA exception event.
Normally, an application should 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.
This table lists events and associated read-only attributes implemented by Agilent VISA that can be read to get event information on a specific event. Use the viReadSTB function to read the status byte of the service request.
|
Instrument Control (INSTR) Resource Events |
|||
|
Event Name |
Attributes |
Data Type |
Range |
|
VI_EVENT_PXI_INTR |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_PXI_INTR |
|
VI_EVENT_SERVICE_REQ |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_SERVICE_REQ |
|
VI_EVENT_VXI_SIGP |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_VXI_STOP |
|
VI_EVENT_TRIG |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_TRIG |
|
VI_EVENT_IO_COMPLETION |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_IO_COMPLETION |
|
VI_EVENT_VXI_VME_INTR |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_VXI_VME_INTR |
|
Not supported by Agilent VISA: |
|||
|
VI_EVENT_USB_INTR |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_USB_INTR |
|
Memory Access (MEMACC) Resource Events |
|||
|
Event Name |
Attributes |
Data Type |
Range |
|
VI_EVENT_IO_COMPLETION |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_IO_COMPLETION |
|
GPIB Bus Interface (INTFC) Resource Events |
|||
|
Event Name |
Attributes |
Data Type |
Range |
|
VI_EVENT_GPIB_CIC |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_GPIB_CIC |
|
VI_EVENT_GPIB_TALK |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_GPIB_TALK |
|
VI_EVENT_GPIB_LISTEN |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_GPIB_LISTEN |
|
VI_EVENT_CLEAR |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_CLEAR |
|
VI_EVENT_TRIGGER |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_TRIGGER |
|
VI_EVENT_IO_COMPLETION |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_IO_COMPLETION |
|
VXI Mainframe Backplane (BACKPLANE) Resource Events |
|||
|
Event Name |
Attributes |
Data Type |
Range |
|
VI_EVENT_TRIG |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_TRIG |
|
VI_EVENT_VXI_VME_SYSFAIL |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_VXI_VME_SYSFAIL |
|
VI_EVENT_VXI_VME_SYSRESET |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_VXI_VME_SYSRESET |
|
TCPIP Socket (SOCKET) Resource Events |
|||
|
Event Name |
Attributes |
Data Type |
Range |
|
VI_EVENT_IO_COMPLETION |
VI_ATTR_EVENT_TYPE |
ViEventType |
VI_EVENT_IO_COMPLETION |
Parameters
|
Name |
Dir |
Type |
Description |
|
vi |
IN |
ViSession |
Unique logical identifier to a session. |
|
eventType |
IN |
ViEventType |
Logical event identifier. |
|
context |
IN |
ViEvent |
A handle specifying the unique occurrence of an event. |
|
userHandle |
IN |
ViAddr |
A value specified by an application that can be used for identifying handlers uniquely in a session for an event. |
Return Values
|
Type ViStatus |
This is the function return status. It returns either a completion code or an error code as follows. |
|
Completion Codes |
Description |
|
VI_SUCCESS |
Event queue flushed successfully. |
|
VI_SUCCESS_NCHAIN |
Event handled successfully. Do not invoke any other handlers on this session for this event. |
See Also
See Programming with VISA in the Agilent VISA User’s Guide for more information on event handling and exception handling.