Revision 1.3  10th April 2012
www.touch-base.com\documentation\API
                       UPDD API  Functions

 

Header file

API Summary

API Groups

Conversion chart

Contact

 

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