HP-UX

NAME

viEnableEvents − Enables notification of an event occurances

SYNOPSIS

EnableEvent(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.  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.
 

Parameters

vi An input parameter. Unique logical identifier to a session. 
 

eventType An input parameter. Logical event identifier. (See the following tables.) 
 

mechanism An input parameter. Specifies event handling mechanisms to be enabled.  The queuing mechanism is enabled by specifying VI_QUEUE, and the callback mechanism is enabled by specifying 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 An input parameter. (Not used for VTL.) 
 

Special Values for eventType

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:

VI_EVENT_SERVICE_REQ Notification that a device is requesting service. 
 

VI_EVENT_VXI_SIGP Notification that a VXI signal or VXI interrupt has been received from a device. 
 

VI_EVENT_TRIG Notification that a hardware trigger was received from a device. 
 
 

Special Values for mechanism Parameter

VI_QUEUE Enable this session to receive the specified event via the waiting queue.  Events must be retrieved manually via the viWaitOnEvent function. 
 

VI_HNDLR Enable this session to receive the specified event via a callback handler, which must have already been installed via viInstallHandler. 
 

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. 
 
 
NOTE Any combination of VTL-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).
 
 

Return Values

 
This is the functional return status.  It returns either a completion code or an error code as follows.
 

VI_SUCCESS Event enabled successfully. 
 

VI_SUCCESS_EVENT_EN Specified event is already enabled for at least one of the specified mechanisms. 
 

VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT The given session or object reference is invalid (both are the same value). 
 

VI_ERROR_INV_EVENT Specified event type is not supported by the resource. 
 

VI_ERROR_INV_MECH Invalid mechanism specified. 
 

VI_ERROR_INV_CONTEXT Specified event context is invalid. 
 

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. 
 

See Also

 
See the handler prototype, viEventHandler, for its parameter description.  Also refer to the viInstallHandler and viUninstallHandler descriptions for information about installing and uninstalling event handlers.
 

AUTHOR

viEnableEvents was developed by HP
 

Hewlett-Packard Comapny  —  September 29, 1999