TBApiRegisterDataCallback API Call

Description

Informs the API that a function is to be used as a callback function for receipt of the specified type(s) of data.

Parameters

The device handle, a context identifier, the required data type(s) which may be OR’d together and a pointer to the callback routine. Possible parameters are:

_ReadDataTypeXY 0x0001	pointer co-ordinates
_ReadDataTypeEvent 0x0002	button state changes
_ReadDataTypeHardware 0x0004	changes of hardware registers
_ReadDataTypeData 0x0008	non-pointer data
_ReadDataTypeToolbar 0x0010	toolbar events
_ReadDataSettings 0x0020	notifications of changes to driver parameters (e.g. via DCU)
_ReadDataTypeSelector 0x0040	notifications of change in event selector state
_ReadDataTypeZ 0x0080	notifications of change in Z values
_ReadDataTypeRelative 0x0100	notifications or relative movement
_ReadDataTypeUnload 0x0200	the driver is about to attempt an unload
_ReadDataTypeRawEvent 0x0400	a change in state of an internal event handler has occurred
_ReadDataTypeMacroEvent 0x0800	a macro event has occured (currently completions only)
_ReadDataTypeXYCal 0x1000	same as ReadDataTypeXY but not masked by toolbars

Returns

0 = fail, 1 = OK.

Notes

The context value is passed unchanged to the callback function for identification purposes. All functions registered must be unregistered before the program terminates, see calls below.

To trap all events, pass a value of 0xFFFF (or &HFFFF for VB) in the aTypes parameter.

To get data for all devices pass device handle 0.

Note that underscore prefixes are omitted in Visual Basic declarations, i.e. _ReadDataTypeXY becomes ReadDataTypeXY.

You should always ensure that a callback for _ReadDataTypeUnload is registered; the driver will invoke this callback:-

1) During uninstall.

2) When all device instances are deleted from the device manager (explicity or implicitly by the removal of hot pluggable PnP hardware).

3) During Windows shutdown (although this happens so late in the process as to be irrelevant for practical purposes).

…at which time you should unregister any other callbacks and terminate.

See also

TBApiRegisterDataCallback

TBApiUnregisterDataCallback

Unregister data callback routine

TBApiUnregisterDataCallbackContext

Unregister data callback routine context

Visual C++ Declaration/example

BOOL TBAPI TBApiRegisterDataCallback(HTBDEVICE aDeviceHandle, unsigned long aContext, unsigned long aTypes, TB_DATA_CALL aFunc);

// In the following example CBFunc is called whenever pointer co-ordinates are processed by relative device 1 until TBApiUnregisterDataCallback is called

HTBDEVICE hd = TBApiGetRelativeDevice(0);

TBApiRegisterDataCallback(hd,0,_ReadDataTypeXY,CBFunc);

...

…

void TBAPI CBFunc(unsigned long context, _PointerData* data)

{

char buf[100];

sprintf(buf, "device %d Generated x=0x%x y=0x%x\n",

(int)data->pd.device,

(int)data->pd.xy->rawx,

(int)data->pd.xy->rawy);

AfxMessageBox(buf);

}

Visual Basic Declaration/example

Public Declare Function TBApiRegisterDataCallback Lib "TBapi" Alias “_DLL_TBApiRegisterDataCallback@16" (ByVal aDeviceHandle As Byte, ByVal aContext As Long, ByVal aTypes As Long, ByVal aFunc As Long) As Long

Dim dev as byte

dev = TBApiGetRelativeDevice(0)

TBApiRegisterDataCallback dev, 0, ReadDataTypeXY, CBFunc

…

...

Public Sub CBFunc(ByVal iContext As Long, ByRef pMyData As CoordinateData)

With pMyData

MsgBox "device “ & .device & _

“ generated x=" & .RawX & _

" y=" & .RawY

End With

End Sub