This document lists the current API function calls. Obsolete calls have been removed. The updd version number is shown to indicate when the call was introduced. 4.1.x indicates the call was valid at the time UPDD 4.1.0 was first created. Other version numbers indicated when the call was introduced.

TBApi.h file

This is the header file that defines the complete list of API functions and should be the final reference point for the definitive list of functions and their usage. Viewed in the appropriate viewer, API functions are held in this file thus:

#undef TBApiOpen

#ifdef TBAPIDLLPFX

#define TBApiOpen DLL_TBApiOpen

#endif

BOOL TBAPI TBApiOpen();

// Establishes a connection to the device driver

// returns 0 = fail, 1 = OK

// Most API functions require an open connection

API function summary

Click on the function call name for a more detail description. Where State = Rednt the API has been withdrawn.

API call	State	Description
TBApiAbortDriver	4.1.x	Causes the driver to close all connections and free resources
TBApiActivateCalibrationStyle	4.1.x	Activate the named calibration style for the specified device id
TBApiAddDevice	4.1.x	Add or replace a new controller to/in the device list
TBApiAddToolbar	4.1.x	Adds a toolbar
TBApiAddStencil	4.1.x	Adds a new stencil to the stencil list for this device
TBApiApply	4.1.x	Updates previously modified Registry settings
TBApiApplyNoReload	4.1.x	As TBApiApply but does not reinitialise the driver
TBApiAutoSetSwapXY	4.1.x	Determines if SwapXY is correctly set and corrects if necessary.
TBApiBeep	4.1.x	Sound the beep as defined by the device sound pitch and duration settings
TBApiCalibrateToolbar	4.1.x	Calibrates a toolbar
TBApiClose	4.1.x	Closes the connection to the device driver
TBApiConvertHexString	4.1.x	Converts a hex string to its hexadecimal equivalent
TBApiCustomControllerAction	4.1.10	Perform a custom controller action
TBApiDeleteRegistryValueCached	4.1.x	Request a deletion of a registry value to be executed during the next call to TBApiApply.
TBApiDeviceSetMouseScaling	4.1.x	Direct all mouse activity for the specified device to the specified desktop rectangle
TBApiDeviceStopMouseScaling	4.1.x	Direct all mouse activity for the specified device to the standard location
TBApiDriverEnable	4.1.x	Enables or disables the driver – superseded now use TBApiMousePortInterfaceEnable / Ex
TBApiEnableToolbar	4.1.x	Enable / disable toolbar
TBApiEnableStencils	4.1.x	Enables or disables stencils for this device.
TBApiEnumAdhocValues	4.1.x	Enumerates through any ad hoc settings for a device
TBApiEnumStringTokens	4.1.x	A help function to enabling splitting a token into individual tokens
TBApiGetApiVersion	5.1.x	Returns the API version
TBApiGetCalibrationAsStyle	4.1.x	Get the calibration settings for the specified device in a _CalStyle structure
TBApiGetCalibrationStyle	Rednt	Get the calibration style details for the specified device & style. Use TBApiGetSettingsSZ instead.
TBApiGetCalibrationStyleByName	Rednt	Given a calibration style name, return the style handle. Use TBApiGetSettingsSZ instead.
TBApiGetCommsErrors	4.1.x	Returns the communications error count
TBApiGetComPortNames	Rednt	Get a list of com port names on the current machine
TBApiGetControllerDWORD	4.1.x	Get a DWORD value from the controller definition of the settings file
TBApiGetControllerSZ	4.1.x	Get a String value from the controller definition of the settings file
TBApiGetDefaultDWORD	4.1.x	Get the default value of a specified setting for a given device
TBApiGetDefaultSZ	4.1.x	Get the default value of a specified setting for a given device
TBApiGetDeviceAddress	4.1.x	Returns the DMA address used by a serial controller
TBApiGetDeviceFromSegment		Gets the device handle for the device handling a given desktop segment
TBApiGetDeviceIrq	4.1.x	Returns the IRQ used by a serial controller
TBApiGetDriverBuild	4.1.6	Removed!
TBApiGetDriverVersion	4.1.x	Returns the driver version number
TBApiGetEventSelectorOneHitMode	4.1.x	Determine whether the driver's event manager is operating in one hit mode
TBApiGetEventSelectorState	4.1.6	Returns the current value of the event selector
TBApiGetGlobalSettingDWORD	4.1.x	Retrieve DWORD value from the global section of the settings file
TBApiGetGlobalSettingSZ	4.1.x	Retrieve string value from the global section of the settings file
TBApiGetHelpFileName	4.1.x	Get the active help file name
TBApiGetIProduct	4.1.x	Get the iProduct item from the associated USB device
TBApiGetMacroStatus	4.1.x	Returns the current status of the macro processor
TBApiGetMaxX	4.1.x	Returns the X-coordinate range determined from the packet size(s)
TBApiGetMaxY	4.1.x	Returns the Y-coordinate range determined from the packet size(s)
TBApiGetMonitorMetrics	4.1.10	Get the position of the primary monitor and the position and size of a monitor associated with a specified updd device
TBApiGetNakMessage	Rednt	Gets the message associated with last received controller NAK
TBApiGetNamedDevice	4.1.x	Gets a device identification for named device
TBApiGetNamedToolbar	4.1.x	Returns the handle for a toolbar
TBApiGetOverflowErrors	4.1.x	Returns the packet overflow count
TBApiGetRawEventState	4.1.x	Returns the event state of the UPDD event handler
TBApiGetRecentToolbarButton	4.1.x	Get the number of the last button pressed in a toolbar
TBApiGetRelativeDevice	4.1.x	Gets a device identification for relative position device
TBApiGetRelativeDeviceFromHandle	4.1.x	Gets a device’s position in the list of defined controllers from a given device handle
TBApiGetRelativeDeviceIncHidden	4.1.x	Get device handle from position, including hidden (unplugged) devices
TBApiGetRelativeDeviceNoHidden	4.1.x	Get device handle from position, excluding hidden (unplugged) devices
TBApiGetRotate	4.1.x	Gets the current video rotation
TBApiGetSettingDWORD	4.1.x	Retrieve DWORD setting from the general and device section
TBApiGetSettingDWORDEx	4.1.x	Retrieve DWORD setting from device sub-tree and node section
TBApiGetSettingSZ	4.1.x	Retrieve STRING setting from the general and device section
TBApiGetSettingSZEx	4.1.x	Retrieve STRING setting from device sub-tree and node
TBApiGetSyncErrors	4.1.x	Return the sync error count
TBApiGetUSBDeviceAddress	4.1.6	Gets the address of a device on the USB bus
TBApiIgnoreToolbars	4.1.x	Enable/disable toolbar processing
TBApiInit	4.1.x	Initialises the API and establishes a connection to the driver – old
TBApiInitEx	5.x.x	Initialises the API and establishes a connection to the driver - new
TBApiIsApiActive	4.1.x	Queries if a connection is open to the driver
TBApiIsTouchingKeyboard	4.1.x	Indicates if on-screen, virtual keyboard it being touched
TBApilfind	4.1.x	Own implementation of CRT function lfind
TBApiLoadToolbar	4.1.6	Load a toolbar from a file for the named device
TBApiForwardNetworkData	Internal	Forward data to all participants in a updd/ip sharing session
TBApiMousePortInterfaceEnable	4.1.x	Enable / disable the mouse port interface
TBApiMousePortInterfaceEnableEx	4.1.x	Enable / disable the mouse port interface for a device
TBApiOpen	4.1.x	Establishes a connection to the device driver
TBApiPostPacketBytes	4.1.x	Post touch data packets into the driver
TBApiRawDataMode	4.1.x	Instructs the driver to return raw data or defined packets.
TBApiRawDataModeBlockSize	4.1.x	Determines the block size for raw data mode (see TBApiRawDataMode)
TBApiReadEEPROMCalibrationData	4.1.10	read calibration data from controller eeprom (must have a supported eeprom protocol)
TBApiReadEETIEEPROM	4.1.6	Read eGalax/EETI eeprom
TBApiReadSerialNumber	4.1.6	Read serial number from device
TBApiReadSmartsetUSBSerialNumber	4.1.6	Get the value of the serial number for a smartset device
TBApiReadTSHARCEEPROM	4.1.6	Read EEPROM values from a TSHARC controller
TBApiRegDeleteBranchCached	Internal	Queue a request for deletion of a registry branch
TBApiRegisterDataCallback	4.1.x	Register a callback function for the specified type(s) of data.
TBApiReinit	4.1.x	Execute the initialisation macro for the specified controller
TBApiReloadNoApply	4.1.x	Reloads the driver, but does not apply pending changes
TBApiRemoveCalibrationStyle	4.1.x	Delete the definition of the specified calibration style
TBApiRemoveDevice	4.1.x	Remove the UPDD device definition and any corresponding Windows device entry
TBApiRemoveToolbar	4.1.x	Removes a toolbar
TBApiRemoveStencils	4.1.10	Removes all stencils from the stencil list for this device
TBApiResetErrorCounts	4.1.x	Resets all error counts
TBApiSaveToolbar	4.1.x	Save the named toolbar for the device
TBApiScaleCoordinates	4.1.x	Modifies co-ordinates to fit in a rectangle specified in TBApiSetScaleDimensions
TBApiSendData	4.1.x	Sends data to a controller
TBApiSendMacro	4.1.x	Sends a macro to the controller using the UPDD macro language
TBApiSendMacroSynchronous	4.1.10	Sends a macro to the controller using the UPDD macro language, await a response.
TBApiSendNetworkData	Internal	Broadcasts data to all participants in a updd/ip sharing session
TBApiSendUnloadMessage	4.1.x	Instructs registered applications to terminate
TBApiSetApiTraceLevel	4.1.x	Controls internal tracing of API function calls
TBApiSetCalibrationStyle	4.1.x	Change the settings for an existing calibration style or add a new style
TBApiSetEventSelectorOneHitMode	4.1.x	Set or unset one hit mode for the driver's event manager
TBApiSetEventSelectorState	4.1.x	Sets the state of the event selector
TBApiSetGlobalSettingDWORD	4.1.x	Set DWORD value from the global section of the settings file
TBApiSetGlobalSettingSZ	4.1.x	Set a String value in the global section of the settings file
TBApiSetMouseScaling	4.1.x	Direct all mouse activity for a given device to a desktop rectangle, scaling as appropriate
TBApiSetRotate	4.1.x	Set the rotation factor
TBApiSetScaleDimensions	4.1.x	Specify scaling factors for subsequent calls to TBApiScaleCoordinates
TBApiSetScreenSaverMode	Internal	Indicates to UPDD that a screen saver is active
TBApiSetSettingDWORD	4.1.x	Set DWORD value in the general and device section of the settings file
TBApiSetSettingDWORDEx	4.1.x	Set DWORD value in the device sub-tree and node of the settings file
TBApiSetSettingSZ	4.1.x	Set STRING value in the general and device section of the settings file
TBApiSetSettingSZEx	4.1.x	Set STRING value in the device sub-tree and node of the settings file
TBApiSetStencilInverted	4.1.10	Set stencil to be inverted
TBApiSetStencilPos	4.1.10	Sets the stencils location on the screen. All coordinates are in UPDD logical screen coordinates (where the primary monitor is 0-65535 x 0-65535 )
TBApiSettingsCacheDirty	4.1.x	Determines if the settings cache has unwritten changes
TBApiSetVirtualDesktopMetrics	4.1.x	Used with virtual desktop modes
TBApiStopMouseScaling	4.1.x	Direct all mouse activity for a given device to the standard location
TBApiTerminate	4.1.x	Closes a connection to the driver
TBApiUnregisterDataCallback	4.1.x	Unregister a previously registered callback function.
TBApiUnregisterDataCallbackContext	4.1.x	Unregister callback function(s) for specified context only.
TBApiUPDDCoordinateFromScreen	4.1.10	Given a co-ordinate in screen pixels (relative to the origin of the primary monitor) return the UPDD co-ordinate (65535 based)
TBApiValidateDevice	4.1.x	Determines if the device exists
TBApiWriteEEPROMCalibrationData	4.1.10	write calibration data to controller eeprom (must have a supported eeprom protocol)
TBApiWriteEETIEEPROM	4.1.8	Write eGalax/EETI eeprom
TBApiWriteSmartsetUSBSerialNumber	4.1.6	Set the value of the serial number for a ELO Smartset device
TBApiWriteTSHARCEEPROM	4.1.6	Write EEPROM values to a TSHARC controller

API function Groups

This lists the functions by their related grouping:

Group

Related API functions

Settings

The settings group is used to set and retrieve settings from the different sections of the settings file.

Calibration

The calibration group is used during calibration.

Toolbars

This API group is used to handle toolbars.

TBApiAddToolbar, TBApiRemoveToolbar, TBApiCalibrateToolbar, TBApiGetNamedToolbar, TBApiIgnoreToolbars, TBApiGetRecentToolbarButton, TBApiSaveToolbar, TBApiLoadToolbar, TBApiEnableToolbar

Stencils

The purpose of this API group is to allow a means by which an application can finely tune where a user may interact with an application via the touch interface

TBApiEnableStencils, TBApiAddStencil, TBApiRemoveStencils, TBApiSetStencilPos, TBApiSetStencilInverted

To allow total control there are two types of stencil.

1) Normal, this identifies a usable area of the screen. If a user touches a point in a nomal stencil the touch is passed through (for example to the system mouse) as normal

2) Inverted, this identifies a unusable area of the screen, If a user touches a point in a normal stencil the touch is blocked (although registered callbacks are still sent for this touch)

Stencils are order based so the topmost (last defined) stencil at a given point is used

In the example below stencil 0 is defined first

A touch at point A is accepted (because it is outside any stencil)

A touch at point B is not accepted (because it is inside inverted stencil 0)

A touch at point C is accepted (because it is inside normal stencil 1, the touch is also inside stencil 0 but stencil 1 takes priority as it was defined later)

Data Conversion Chart

The following is useful for converting datatypes between Visual C++ and Visual Basic:-

C++ Datatype	VB Equivalent
short	Integer
WORD	Integer
int	Long
long	Long
UINT	Long
ULONG	Long
DWORD	Long
WPARAM, LPARAM	Long
WMSG, UMSG	Long
HRESULT	Long
BOOL	Long
COLORREF	Long
HWND, HDC, HBRUSH, HKEY, etc.	Long
LPSTR, LPCSTR	String
LPWSTR, OLECHAR, BSTR	String
LPTSTR	String
VARIANT_BOOL	Boolean
unsigned char	Byte
BYTE	Byte
VARIANT	Variant
(Any data type ending with * or **)	Long

Contact

For further information or technical assistance please email the technical support team at technical@touch-base.com.