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 Keysight 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.

Please note, this function is available for both Windows and Linux users, however, VXI and PXI functionality are Windows only.

Event Name	Attributes	Data Type	Range
Instrument Control (INSTR) Resource Events
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 VI_ATTR_SIGP_STATUS_ID	ViEventType ViUInt16	VI_EVENT_VXI_STOP 0 to FFFFh
VI_EVENT_TRIG	VI_ATTR_EVENT_TYPE VI_ATTR_RECV_TRIG_ID	ViEventType ViInt16	VI_EVENT_TRIG VI_TRIG_TTL0 to VI_TRIG_TTL11; VI_TRIG_ECL0 to VI_TRIG_ECL5; VI_TRIG_STAR_INSTR
VI_EVENT_IO_COMPLETION	VI_ATTR_EVENT_TYPE VI_ATTR_STATUS VI_ATTR_JOB_ID VI_ATTR_BUFFER VI_ATTR_RET_COUNT VI_ATTR_RET_COUNT_32 VI_ATTR_RET_COUNT_64 VI_ATTR_OPER_NAME	ViEventType ViStatus ViJobId ViBuf ViUInt32 ViString	VI_EVENT_IO_COMPLETION N/A N/A N/A 0 to FFFFFFFFh N/A
VI_EVENT_VXI_VME_INTR	VI_ATTR_EVENT_TYPE VI_ATTR_INTR_STATUS_ID VI_ATTR_RECV_INTR_LEVEL	ViEventType ViUInt32 ViInt16	VI_EVENT_VXI_VME_INTR 0 to FFFFFFFFh 1 to 7, VI_UNKNOWN_LEVEL
Not supported by Keysight VISA:
VI_EVENT_USB_INTR	VI_ATTR_EVENT_TYPE VI_ATTR_USB_RECV_INTR_SIZE VI_ATTR_USB_RECV_INTR_DATA VI_ATTR_STATUS	ViEventType ViUInt16 ViBuf ViStatus	VI_EVENT_USB_INTR 0 to FFFFh N/A N/A
Memory Access (MEMACC) Resource Events
Event Name	Attributes	Data Type	Range
VI_EVENT_IO_COMPLETION	VI_ATTR_EVENT_TYPE VI_ATTR_STATUS VI_ATTR_JOB_ID VI_ATTR_BUFFER VI_ATTR_RET_COUNT VI_ATTR_RET_COUNT_32 VI_ATTR_RET_COUNT_64 VI_ATTR_OPER_NAME	ViEventType ViStatus ViJobId ViBuf ViUInt32 ViString	VI_EVENT_IO_COMPLETION N/A N/A N/A 0 to FFFFFFFFh N/A
GPIB Bus Interface (INTFC) Resource Events
Event Name	Attributes	Data Type	Range
VI_EVENT_GPIB_CIC	VI_ATTR_EVENT_TYPE VI_ATTR_GPIB_RECV_CIC_STATE	ViEventType ViBoolean	VI_EVENT_GPIB_CIC VI_TRUE VI_FALSE
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_TRIG	VI_ATTR_EVENT_TYPE VI_ATTR_RECV_TRIG_ID	ViEventType ViInt16	VI_EVENT_TRIG VI_TRIG_SW
VI_EVENT_IO_COMPLETION	VI_ATTR_EVENT_TYPE VI_ATTR_STATUS VI_ATTR_JOB_ID VI_ATTR_BUFFER VI_ATTR_RET_COUNT VI_ATTR_RET_COUNT_32 VI_ATTR_RET_COUNT_64 VI_ATTR_OPER_NAME	ViEventType ViStatus ViJobId ViBuf ViUInt32 ViString	VI_EVENT_IO_COMPLETION N/A N/A N/A 0 to FFFFFFFFh N/A
Backplane (BACKPLANE) Resource Events
Event Name	Attributes	Data Type	Range
VI_EVENT_TRIG	VI_ATTR_EVENT_TYPE VI_ATTR_RECV_TRIG_ID	ViEventType ViInt16	VI_EVENT_TRIG VI_TRIG_TTL0 to VI_TRIG_TTL11; VI_TRIG_ECL0 to VI_TRIG_ECL5; VI_TRIG_STAR_SLOT1 to VI_TRIG_STAR_SLOT12
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 VI_ATTR_STATUS VI_ATTR_JOB_ID VI_ATTR_BUFFER VI_ATTR_RET_COUNT VI_ATTR_RET_COUNT_32 VI_ATTR_RET_COUNT_64 VI_ATTR_OPER_NAME	ViEventType ViStatus ViJobId ViBuf ViUInt32 ViString	VI_EVENT_IO_COMPLETION N/A N/A N/A 0 to FFFFFFFFh N/A

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

Completion Code	Description
Type ViStatus	This is the function return status. It returns either a completion code or an error code as follows.
VI_SUCCESS	Event queue flushed successfully.
VI_SUCCESS_NCHAIN	Event handled successfully. Do not invoke any other handlers on this session for this event.

viEventHandler

Syntax

Description

Instrument Control (INSTR) Resource Events

Not supported by Keysight VISA:

Memory Access (MEMACC) Resource Events

GPIB Bus Interface (INTFC) Resource Events

Backplane (BACKPLANE) Resource Events

TCPIP Socket (SOCKET) Resource Events

Parameters

Return Values

See Also