viEnableEvent
Syntax
viEnableEvent(ViSession vi, ViEventType eventType, ViUInt16 mechanism, ViEventFilter context);
Description
This function enables notification of an event identified by the eventType parameter for mechanisms specified in the mechanism parameter. The specified session can be enabled to queue events by specifying VI_QUEUE.
Note: VISA cannot callback to a Visual Basic function. Thus, you can only use the VI_QUEUE mechanism in viEnableEvent. There is no way to install a VISA event handler in Visual Basic.
Applications can enable the session to invoke a callback function to execute the handler by specifying VI_HNDLR. The applications are required to install at least one handler to be enabled for this mode.
Specifying VI_SUSPEND_HNDLR enables the session to receive callbacks, but the invocation of the handler is deferred to a later time. Successive calls to this function replace the old callback mechanism with the new callback mechanism.
Specifying VI_ALL_ENABLED_EVENTS for the eventType parameter refers to all events which have previously been enabled on this session, making it easier to switch between the two callback mechanisms for multiple events.
Event queuing and callback mechanisms operate completely independently. As such, enabling and disabling of the two modes in done independently (enabling one of the modes does not enable or disable the other mode). For example, if viEnableEvent is called once with VI_HNDLR and called a second time with VI_QUEUE, both modes would be enabled.
If viEnableEvent is called with the mechanism parameter equal to the "bit-wise OR" of VI_SUSPEND_HNDLR and VI_HNDLR, viEnableEvent returns VI_ERROR_INV_MECH.
If the event handling mode is switched from VI_SUSPEND_HNDLR to VI_HNDLR for an event type, handlers that are installed for the event are called once for each occurrence of the corresponding event pending in the session (and dequeued from the suspend handler queue) before switching the modes.
A session enabled to receive events can start receiving events before the viEnableEvent operation returns. In this case, the handlers set for an event type are executed before the completion of the enable operation.
If the event handling mode is switched from VI_HNDLR to VI_SUSPEND_HNDLR for an event type, handler invocation for occurrences of the event type is deferred to a later time. If no handler is installed for an event type, the request to enable the callback mechanism for the event type returns VI_ERROR_HNDLR_NINSTALLED.
If a session has events pending in its queue(s) and viClose is invoked on that session, all pending event occurrences and the associated event contexts that have not yet been delivered to the application for that session are freed by the system.
Parameters
|
Name |
Dir |
Type |
Description |
|
vi |
IN |
ViSession |
Unique logical identifier to a session. |
|
eventType |
IN |
ViEventType |
Logical event identifier. (See the following tables.) |
|
mechanism |
IN |
ViUInt16 |
Specifies event handling mechanisms to be enabled. The queuing mechanism is enabled by VI_QUEUE, and the callback mechanism is enabled by VI_HNDLR or VI_SUSPEND_HNDLR. It is possible to enable both mechanisms simultaneously by specifying "bit-wise OR" of VI_QUEUE and one of the two mode values for the callback mechanism. |
|
context |
IN |
ViEventFilter |
VI_NULL (Not used for VISA 1.0.) |
|
Special Values for eventType Parameter |
|||
|
Value |
|
|
Action Description |
|
VI_ALL_ENABLED_EVENTS |
|
|
Switch all events that were previously enabled to the callback mechanism specified in the mechanism parameter. |
|
The following events can be enabled: |
|||
|
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 …). |
|||
|
Special Values for mechanism Parameter |
|||
|
Note: Any combination of VISA-defined values for different parameters of this function is also supported (except for VI_HNDLR and VI_SUSPEND_HNDLR, which apply to different modes of the same mechanism). |
|||
|
Value |
|
|
Action Description |
|
VI_HNDLR |
|
|
Enable this session to receive the specified event via a callback handler, which must have already been installed via viInstallHandler. |
|
VI_QUEUE |
|
|
Enable this session to receive the specified event via the waiting queue. Events must be retrieved manually via the viWaitOnEvent function. |
|
VI_SUSPEND_HNDLR |
|
|
Enable this session to receive the specified event via a callback queue. Events will not be delivered to the session until viEnableEvent is invoked again with the VI_HNDLR mechanism. |
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 enabled successfully. |
|
VI_SUCCESS_EVENT_EN |
Specified event is already enabled for at least one of the specified mechanisms. |
|
Error Codes |
Description |
|
VI_ERROR_HNDLR_NINSTALLED |
A handler is not currently installed for the specified event. The session cannot be enabled for the VI_HNDLR mode of the callback mechanism. |
|
VI_ERROR_INV_CONTEXT |
Specified event context is invalid. |
|
VI_ERROR_INV_EVENT |
Specified event type is not supported by the resource. |
|
VI_ERROR_INV_MECH |
Invalid mechanism specified. |
|
VI_ERROR_INV_SESSION |
The given session or object reference is invalid (both are the same value). |
|
VI_ERROR_NSUP_MECH |
The specified mechanism is not supported for the given event type. |
See Also
See the handler prototype viEventHandler for its parameter description and viDisableEvent. Also, see the viInstallHandler and viUninstallHandler descriptions for information about installing and uninstalling event handlers.