Having downloaded the files you may wish to write a simple application to see the UPDD API interface in action.
The following code segment shows the skeleton of a simple C++ fragment that demonstrates:-
1. initialising the API
2. registering a callback routine to receive raw X/Y co-ordinates and notification of driver unload
3. shutting down
A .net c# user reported the following was required to run the API in C#
Import the functions from TBAPI.DLL using the DllImport command
Then for each function, such as this example, (on a Windows system)
void TBAPI TBApiInit(const TBCHAR* aSettingsPath);
where TBAPI = _stdcall
and TBCHAR = char
Use mangled reference names DLL_TBApiInit - use a utility like dumpbin to identify the mangled entry names to avoid entry point errors such as ‘Unable to find an entry point named 'TBApiInit' in DLL 'C:\Program Files\UPDD\TBAPI.dll'.
With the exception of Windows CE, which is Unicode only, the UPDD API is MBCS based only. Including the tbapi.h file in a Unicode program causes the Unicode definitions (intended for Windows CE) to be activated.
This can be avoided as follows.
4.1.10 and above
The API uses MBCS in the public interface all environments except Windows CE, where Unicode must be used. An error in the previous implementation meant that tbapi.h could not be used directly in a Unicode based program. This is no longer the case and previous partial solutions (such as “undef’ing” _UNICODE) are no longer required.
Under CE you need to pass UNICODE, so for example, the TBApiInit call is coded as:
After advising a user on API usage within a Objective-C Cocoa application with Xcode 5 project we wrote up our finding as follows:
1. Install the UPDD driver.
2. Use the API files included with the driver as installed in /Library/Application Support/UPDD/api and copy them into your project directory.
3. Add libTBApi.a to your Xcode project.
4. Locate libACE.dylib in /usr/local/lib. It can be found in the Finder by selecting the “Go to folder” menu item in the Go menu, and typing in:
Add it to your Xcode project.
5. In Xcode, open your project’s settings, and in the “Build settings” section, locate the following settings and change them to the indicated values:
· Under the “Architectures” group, the “Architectures” settings should be set to “64-bit Intel (X86_64)”
· Under the “Search paths” group, add the following path to “Library Search Paths”: /usr/local/lib
· Under the “Apple LLVM 5.0 - Language - C++” group, the “C++ Standard Library” setting should be set to “libstdc++ (GNU C++ standard library)”
6. Change the extension of all Objective-C files that will make calls to the UPDD API from “.m” to “.mm”, so that they are Objective-C++ files.
7. Use header files nonwindows.h and tbapi.h in your application
The UPDD settings file is usually located in the UPDD application folder. When writing an application using the UPDD API then at the time the TBApiInit function is called the current working directory must be set to the folder containing the settings file. One way to achieve this is might be to run the program from the updd application folder.
The nature of the registered callback determines the type of data returned in a PointerData structure (although not all events are accompanied by additional data).
It is important that applications are aware if the driver is no longer available. This can be as a result of:-
1. The driver is being un-installed
To receive notification of these ‘unload’ events applications should register interest via TBApiRegisterDataCallback supplying the _ReadDataTypeUnload parameter.
Calibration Style Structure
UPDD version 4.1.10 introduces a number of changes to resolve problems reported with previous API implementations.
API programs written for earlier versions must be rebuilt and minor changes are required.
The requirement to set the working directory before calling TBApiInit no longer applies.
A change must be made to the call to TBApiInit to determine the desired method to locate the UPDD settings.
1) Using the “usual default” location.
This approach uses the default installation path used in most cases.
Unless your installation is manually installed to a nonstandard location or you are writing advanced code to work with pre-installation settings during an installation, this approach should suffice.
2) Using an explicit path
TBApiInit(“c:\\program files\\updd\\unusual location”);
3) Using a NULL argument to force the same behaviour as used in previous 4.x version
To overcome a number of niggly issues with the pathname definition with TBApiInit we introduced a new initialisation function call TBApiInitEx.
The function call initialises the API, and establishes a connection to the device driver and must be called before any other API functions
Pass a path to folder containing settings file (tbupdd.ini)
NULL to use the current working directory
or use TBApiDefaultSettingsPath()
Windows Symbol Tables
Since UPDD version 5.1.1460 you can utilise our symbol server at http://symbols.touch-base.com/symbols.
For example in visual studio at tools -> options -> debugging ->symbols
For further information or technical assistance please email the technical support team at firstname.lastname@example.org.