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) constants which may be OR’d together and a pointer to the callback routine. Possible constants are:

Constanst	Mask	Note
_ReadDataTypeXY	0001	pointer co-ordinates
_ReadDataTypeEvent	0002	button state changes
_ReadDataTypeHardware	0004	changes of hardware registers
_ReadDataTypeData	0008	non-pointer data
_ReadDataTypeToolbar	0010	toolbar events
_ReadDataSettings	0020	notifications of changes to driver parameters (e.g. via DCU)
_ReadDataTypeSelector	0040	notifications of change in event selector state
_ReadDataTypeZ	0080	notifications of change in Z values
_ReadDataTypeRelative	0100	notifications or relative movement
_ReadDataTypeUnload	0200	the driver is about to attempt an unload
_ReadDataTypeRawEvent	0400	a change in state of an internal event handler has occurred
_ReadDataTypeMacroEvent	0800	a macro event has occured (currently completions only)
_ReadDataTypeXYCal	1000	same as ReadDataTypeXY but not masked by toolbars
_ReadDataTypeDynamicAdd	2000	Driver reports that a controller must be dynamicaly added
_ReadDataTypeInteractiveTouch	4000	mouse pointer state events for interactive touch mode
_ReadDataTypeIPConnection	8000	upddip connection
_ReadDataTypeNetworkData	10000	network data
_ReadDataTypeForwardNetworkData	20000	network data
_ReadDataTypeZytronicHack	40000	special for zytronic
_ReadDataTypeDeviceChanged	80000	notify tbdaemon of a device change
_ReadDataTypeSound	100000	request a beep in user mode

Returns

0 = fail, 1 = OK.

Notes

1. The callback function is executed in the context of a dedicated thread therefore only thread safe (reentrant) functions should be called from the callback function - many windowing api functions are non-reentrant - if you need to call non-reentrant functions you need to provide synchronisation management - a common way to achieve this is to post a message to the primary process thread and perform all non-reentrant operations from the primary thread.

2. 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.

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

4. To get data for all devices pass device handle 0.

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

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

• During uninstall.
• When all device instances are deleted from the device manager (explicity or implicitly by the removal of hot pluggable PnP hardware).
• 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.

TBApiRegisterDataCallback

Register data callback routine

See also

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