cbEnableEvent()

Binds one or more event conditions to a user-defined callback function. Upon detection of an event condition, the user-defined function is invoked with board- and event-specific data. Detection of event conditions occurs in response to interrupts. Typically, this function is used in conjunction with interrupt driven processes such as cbAInScan(), cbAPretrig(), or cbAOutScan().

Function Prototype

C/C++

int cbEnableEvent(int BoardNum, unsigned EventType, unsigned EventParam, void* CallbackFunc, void* UserData)

Visual Basic

Function cbEnableEvent(ByVal BoardNum&, ByVal EventType&, ByVal EventParam&, ByVal CallbackFunc&, ByRef UserData as Any) as Long

Arguments

BoardNum

The board number used to indicate which device will generate the event conditions. BoardNum may be 0 to 99. Refers to the number associated with the board when it was installed with InstaCal or created with cbCreateDaqDevice()..

EventType

Specifies one or more event conditions that will be bound to the user-defined callback function. More than one event type can be specified by bitwise OR'ing the event types. Refer to the constants in the EventType argument values below.

EventParam

Additional data required to specify some event conditions, such as an ON_DATA_AVAILABLE event or ON_EXTERNAL_INTERRUPT event.

For ON_DATA_AVAILABLE events, EventParam is used to determine the minimum number of samples to acquire during an analog input scan before generating the event. For ON_EXTERNAL_INTERRUPT events, EventParam is used to latch digital bits on supported hardware by setting it to one of the constants in the EventParam argument values section below.

Most event conditions ignore this value.

CallbackFunc

The address of or pointer to the user-defined callback function to handle the above event type(s). This function must be defined using the standard call (__stdcall) calling convention. Consequently, Visual Basic programs must define their callback functions in standard modules (.bas) and cannot be object methods. C++ programs can define this callback function as either a global function or as a static member function of a class (note that static members do NOT have access to instance specific data).

Refer to the "User Callback function" for proper function syntax.

UserData

The address of or pointer to user-defined data that will be passed to the user-defined callback function. This parameter is NOT dereferenced by the library or its drivers; as a consequence, a NULL pointer can be supplied.

Returns

Error code or 0 if no errors

EventType argument values

ON_DATA_AVAILABLE	Generates an event whenever the number of samples acquired during an analog input scan increases by EventParam samples or more. Note that for BLOCKIO scans, events will be generated on packet transfers; for example, even if EventParam is set to 1, events will only be generated every packet-size worth of data (256 samples for the PCI-DAS1602) for aggregate rates greater than 1 kHz for the default cbAInScan() mode. For cbAPretrig(), the first event is not generated until a minimum of EventParam samples after the pretrigger.
ON_END_OF_INPUT_SCAN	Generates an event upon completion or fatal error of cbAInScan() or cbAPretrig(). Some devices, such as the USB-1208FS and USB-1408FS, will generate an end of scan event after cbStopBackground is called, but most devices do not. Handle post-scan tasks directly after calling cbStopBackground.
ON_END_OF_OUTPUT_SCAN	Generates an event upon completion or fatal error of cbAOutScan(). Some devices, such as the USB-1208FS and USB-1408FS, will generate an end of scan event after cbStopBackground is called, but most devices do not. Handle post-scan tasks directly after calling cbStopBackground.
ON_EXTERNAL_INTERRUPT	For some digital and counter boards, generates an event upon detection of a pulse at the External Interrupt pin.
ON_PRETRIGGER	For cbAPretrig(), generates an event upon detection of the first trigger.
ON_SCAN_ERROR	Generates an event upon detection of a driver error during BACKGROUND input and output scans. This includes OVERRUN, UNDERRUN, and TOOFEW errors.

EventParam argument values

LATCH_DI	Returns the data that was latched in at the most recent interrupt edge.
LATCH_DO	Latches out the data most recently written to the hardware.

Notes

This function cannot be called while any background operations (cbAInScan(), cbAPretrig(), or cbAOutScan()) are active. If a background operation is in progress when cbEnableEvent() is called, the function returns an ALREADYACTIVE error. Perform a cbStopBackground() call before calling cbEnableEvent().
Events will not be generated faster than the user callback function can handle them. If an event type becomes multi-signaled before the event handler returns, events are merged. The event handler is called once per event type, and is supplied with the event data corresponding to the latest event. When more than one event type is generated, the event handler for each event type is called in the same order in which they are enabled.
Events are generated while handling board-generated interrupts. Therefore, using cbStopBackground() to abort background operations does not generate ON_END_OF_INPUT_SCAN or ON_END_OF_OUTPUT_SCAN events. However, the event handlers can be called immediately after calling cbStopBackground().
cbEnableEvent() is intended for use with Windows applications. Use with console applications can produce unpredictable results.