viInstallHandler
Syntax
viInstallHandler(ViSession vi, ViEventType eventType, ViHndlr handler, ViAddr UserHandle);
Description
This function allows applications to install handlers on sessions for event callbacks. The handler specified in the handler parameter is installed along with previously installed handlers for the specified event. Applications can specify a value in the userHandle parameter that is passed to the handler on its invocation.
VISA identifies handlers uniquely using the handler reference and the userHandle value.
Note: Versions of VISA prior to Version 2.0 allow only a single handler per event type per session.
Parameters
|
Name |
Dir |
Type |
Description |
|
vi |
IN |
ViSession |
Unique logical identifier to a session. |
|
eventType |
IN |
ViEventType |
Logical event identifier. |
|
handler |
IN |
ViHndlr |
Interpreted as a valid reference to a handler to be installed by an application. |
|
userHandle |
IN |
ViAddr |
A value specified by an application that can be used for identifying handlers uniquely for an event type. |
|
The following events are valid: |
|
|
|
|
Event Name |
|
|
Description |
|
VI_EVENT_IO_COMPLETION |
|
|
Notification that an asynchronous operation has completed. |
|
VI_EVENT_TRIG |
|
|
Notification that a hardware trigger was received from a device. |
|
VI_EVENT_SERVICE_REQ |
|
|
Notification that a device is requesting service. |
|
VI_EVENT_CLEAR |
|
|
Notification that the local controller has been sent a device clear message |
|
VI_EVENT_EXCEPTION |
|
|
Notification that an error condition has occurred during an operation invocation. (Note: the VI_QUEUE and VI_SUSPEND_HNDLR mechanisms cannot be used with this event.) |
|
VI_EVENT_GPIB_CIC |
|
|
Notification that the GPIB controller has gained or lost CIC (controller in charge) status. |
|
VI_EVENT_GPIB_TALK |
|
|
Notification that the GPIB controller has been addressed to talk. |
|
VI_EVENT_GPIB_LISTEN |
|
|
Notification that the GPIB controller has been addressed to listen. |
|
VI_EVENT_PXI_INTR |
|
|
Notification that a vendor-specific PXI interrupt was received from the device. |
|
VI_EVENT_VXI_VME_SYSFAIL |
|
|
Notification that the VXI/VME SYSFAIL* line has been asserted. |
|
VI_EVENT_VXI_VME_SYSRESET |
|
|
Notification that the VXI/VME SYSRESET* line has been asserted |
|
VI_EVENT_VXI_SIGP |
|
|
Notification that a VXI signal or VXI interrupt has been received from a device. |
|
VI_EVENT_VXI_VME_INTR |
|
|
Notification that a VXIbus interrupt was received from the device. |
|
Not supported by Agilent VISA: |
|||
|
VI_EVENT_TCPIP_CONNECT |
|
|
Notification that a TCP/IP connection has been made. |
|
VI_EVENT_USB_INTR |
|
|
Notification that a vendor-specific USB interrupt was received from the device. |
Note: Refer to the viEventHandler topic and the VISA Attributes topics for information on the event types that are available for various VISA resource classes (e.g. INSTR, INTFC …).
Return Values
|
Type ViStatus |
This is the function return status. It returns either a completion code or an error code as follows. |
|
Completion Code |
Description |
|
VI_SUCCESS |
Event handler installed successfully. |
|
Error Codes |
Description |
|
VI_ERROR_HNDLR_NINSTALLED |
The handler was not installed. This may be returned if an application attempts to install multiple handlers for the same event on the same session. |
|
VI_ERROR_INV_EVENT |
Specified event type is not supported by the resource. |
|
VI_ERROR_INV_HNDLR_REF |
The given handler reference is invalid. |
|
VI_ERROR_INV_SESSION |
The given session or object reference is invalid (both are the same value). |
See Also