All UPDD driver and device setting are held in in single settings file as described here.
UPDD settings are “sparsely populated”, meaning that in many cases there is no value and the software uses an implied default.
The reason for this is that in previous UPDD versions a vast number of unused settings provided for a confusing picture.
Generally speaking this should not cause any issue, as used settings generally have a value, but in cases where they do not; the default definition is rather loose.
Currently defaults are hard coded in the UPDD software. We have online documentation and an internal reference database, but these are for reference purposes only as there is no hard and fast link.
As a long term goal we will likely link the internal reference database to software, so that the defaults in the database are used in the software and published via the API. However, the scale of this task set against minimal benefit means this is not a priority and will more likely be implemented piecemeal.
What this means in practice is that for settings that give a blank value a sensible default should be assumed.
The current version of the settings API’s implemented Oct 2018 allow for getting all possible settings as opposed to those currently defined.
UPDD client programs can manipulate these settings using a number of related API functions as follows:
// a set of functions to set / retrieve UPDD settings
TBBOOL TBAPI TBApiGetSetting(HTBDEVICE aHandle,const TBCHAR* aName, TBCHAR* aSZ, int lBuff);
TBBOOL TBAPI TBApiGetSettingAsInt(HTBDEVICE aHandle,const TBCHAR* aName, int32_t* val);
TBBOOL TBAPI TBApiSetSetting(HTBDEVICE aHandle, const TBCHAR* aName, const TBCHAR* aSZ, TBBOOL aDeviceSpecific);
TBBOOL TBAPI TBApiSetSettingFromInt(HTBDEVICE aHandle, const TBCHAR* aName, int32_t val, TBBOOL aDeviceSpecific);
// this variant retrieves the default setting for the controller type as opposed to a specific installed instance of the controller
TBBOOL TBAPI TBApiGetControllerSetting(int aControllerHandle, const TBCHAR* aName, TBCHAR* aSZ, int lBuff);
// remove a setting
TBBOOL TBAPI TBApiRemove(HTBDEVICE aHandle, const TBCHAR* aName);
// get the length of buffer needed to hold any setting as a NULL terminated string
TBBOOL TBAPI TBApiGetSettingSize(HTBDEVICE aHandle, const TBCHAR* aName, int* lBuff);
TBBOOL TBAPI TBApiGetControllerSettingSize(HTBDEVICE aHandle, const TBCHAR* aName, int* lBuff);
// get the names of all settings matching a pattern
// aIncludeUnused: if true (1) indicates that all known matching names are to be returned as opposed to those currently used in the package
// if a null value is passed for aSZ, the return value addressed by lBuff will be set to the required buffer size
// the list of names is returned as a multi line string (separated by '\n' characters)
TBBOOL TBAPI TBApiGetSettings(HTBDEVICE aHandle, TBBOOL aIncludeUnused, const TBCHAR* aPattern, TBCHAR* aSZ, int* lBuff);
// get the help text associated with a named setting
// if a null value is passed for aSZ, the return value addressed by lBuff will be set to the required buffer size
TBBOOL TBAPI TBApiGetSettingHelp(const TBCHAR* aName, TBCHAR* aSZ, int* lBuff);
// export settings
// aDevices is a comma separate list of device handles to support OR * for all real (non zero) devices OR ** for all devices + NODEVICE
// aNames is a comma separated list of setting names to export; can use standard wildcard characters * or ?
// aTargetFileName is the path to the export file
// aFailIfExists if true and the target file exists the API call will fail (return false)
TBBOOL TBAPI TBApiExportSettings(TBCHAR* aDevices, TBCHAR* aNames, TBCHAR* aTargetFileName, TBBOOL aFailIfExists);
// import settings previouly exported by TBApiExportSettings
// aSourceFileName is the path to the import file
TBBOOL TBAPI TBApiImportSettings(TBCHAR* aSourceFileName);