═══ 1. How to Use this Book ═══ This reference is a detailed technical guide and reference for application programmers. It gives reference information and code examples to enable you to write source code using the Workplace Shell Toolkit. It is assumed that you are familliar with the handling of OS/2 online book files. More, you need to be familiar with the usage of the Toolkit for OS/2 Warp and Workplace Shell programming in general. If not, please refer to How to use this book and other chapters of the Workplace Shell Programming Reference. Note: The information of the section How to Use this Bookof the Workplace Shell Programming Reference not being included in this book applies also here. ═══ 1.1. Conventions used in this Reference ═══ The purpose of this reference is to give information about classes, methods, constants, and data types. It provides information about the methods which enables the user to call functions in the C programming language. The following information is provided:  The syntax and parameters for each method.  The syntax of each data type and structure. ═══ 1.2. Reference Notation Conventions ═══ The following notation conventions are used in this reference: NULL The term NULL applied to a parameter is used to indicate the presence of the pointer parameter, but with no value. NULLHANDLE The term NULLHANDLE applied to a parameter is used to indicate the presence of the handle parameter, but with no value. Implicit Pointer If no entry for a data type "Pxxxxxxx" is found in Data Types, then it is implicitly a pointer to the data type "xxxxxxx". See Implicit Pointer Data Types for more information about implicit pointers. CONSTANT NAMES All constants are written in uppercase to match the header files. Where applicable, constant names have a prefix derived from the name of a function, message, or idea associated with the constant. In this book, references to a complete set of constants with a given prefix is written as shown in the following examples: Window message WM_* System value SV_* ═══ 1.3. Header files ═══ All functions require an "#include" statement for the system header file wtk.h. #include Most functions also require a "#define" statement to select an appropriate (conditional) section of the header file, and hence, the required prototype. Where this is necessary, it is shown at the head of the function definition in the form: #define INCL_name Note:  These "#define" statements must precede the "#include " statement.  If you also include os2.h, you must do this before including wtk.h !!! ═══ 1.4. Implicit Pointer Data Types ═══ A data type name beginning with "P" (for example, PERRORCODE) is likely to be a pointer to another data type (in this instance, ERRORCODE). In the data type summary, Data Types, no explicit "typedefs" are shown for pointers; therefore, if no data type definition can be found in the summary for a data type name "Pxxxxxx", it represents a pointer to the data type "xxxxxx", for which a definition should be found in the reference. The implicit type definition needed for such a pointer "Pxxxxxx" is: typedef xxxxxx *Pxxxxxx; Such definitions are provided in the header files. ═══ 2. Why a Workplace Shell Toolkit ? ═══ The Workplace Shell has by far the most innovative and extendible interface of all computer GUIs around. While this is recognized by many programmers aas well as users, coding Workplace Shell classes requires some more knowledge compared to plain GUI programming. Even when someone has got this knowledge, coding certain functionality that a Workplace Shell class either should or must have, is most often a very time consuming task. More, one often needs to create somewhat redundant code, only changing a few things within a lot of code lines, blowing out your source files and most likely leading to a lot of little nasty bugs, requiring a lot of tests hunting them. Even worse, if you are creating not only one, but several Workplace Shell classes in one project, then you will quickly come to code several parts several times. Beside giving you a lot of little helper functions, the API of the Workplace Shell Toolkit encapsulates the complexity of the handling of some of the tasks being most time consuming to code. See the following guides to specific major APIs of the Workplace Shell Toolkit:  Text Message Files (TMF)  Settings and Details Manager  Extended Attributes Manager  Memory Mapped Files Manager ═══ 3. Source and binary distributions of the Workplace Shell Toolkit ═══ The Workplace Shell Toolkit comes in two flavours, source and binary dsitributions. See Supported compilers / Prerequisites for prerequisites that apply to the two distributions in association with the used compiler. source distribution Beside the sample programs and the header files this version includes the sources for the library and the online documentation of the Workplace Shell Toolkit. Unlike the binary distribution this version is not ready to use - it must be compiled first. Note:  This version is available ony via the CVS server of the Netlabs Open Source Archive. See Getting the source from Netlabs for more information. binary distribution Beside the sample programs and the header files this version includes the compiled versions of the library for all supported compilers and the online documentation, thus being ready to use. The sources for the library and the online documentation of the Workplace Shell Toolkit are not included. Note:  This version is - available via The Hobbes OS/2 archive or other ftp servers within the internet wpstknnn.zip, where nn is the version number. - will be announced via comp.os.os2.announce - is maintained only by the project team. ═══ 4. Supported compilers / Prerequisites ═══ The following compilers are currenty supported for using the Workplace Shell Toolkit. See the following sections for prerequisites:  IBM C Set ++ V2.1 / IBM VisualAge C++ V3.0 for OS/2  emx 0.9d for OS/2 ═══ 4.1. IBM C Set ++ V2.1 / IBM VisualAge C++ V3.0 for OS/2 - Prerequisites ═══ The following prerequisites apply when using the Workplace Shell Toolkit with the IBM compilers:  Users of a source distribution of the Workplace Shell Toolkit are required to download it via CVS to an HPFS drive. A HPFS partition is also required in order to to compile it completely. One could copy a CVS development tree to a FAT partition, this would allow to compile at least the library itself and the sample programs, but the online docs could not be compiled, as the source files for this require long filenames.  Users of a binary distribution of the Workplace Shell Toolkit (not including the sources for the library or online doc) can install it onto a FAT drive without problems, when using the IBM compilers. In that case ignore or delete the files GNUMAKEF where existing, as they are not required by the IBM compilers (these are the GNUmakefile, but just with a filename cut off after the eight characters).  You are reqired to append the pathname of the include and lib directories of the installed Workplace Shell Toolkit to the INCLUDE and LIB environment variables. Optionally, if you use the EPM, you might also want to add the help index file to the HELPNDX environment variable. This can be done either in - your config.sys file (not recommended !) - a batch file that you use to call to setup your environment. you may want to use the batchfile bin\wtkenv.cmd, setting up the environment automatically - your makefile Note: - when you compile the Workplace Shell Toolkit yourself, the resulting libraries are put into directories named either debug or release instead of lib, depending on the debug status during compilation. Further, for each compiler there is a separate subdirectory below the lib directory for each version of the Workplace Shell Toolkitlibrary file. Where the compiler does not allow mixing of single- and multithread-compiled code (for currently one compiler only) a suffix for single- or multithreaded code is appended to the name of the subdirectory: cset2s IBM C Set ++ V2.1 - singlethreaded cset2m IBM C Set ++ V2.1 - multithreaded vac3 IBM VisualAge C++ V3.0 for OS/2 Provided that you have installed the Workplace Shell Toolkit in a directory d:\wpstk, you extend the variables as follows in - your config.sys file (This is not recommended, if you use different library versions at a time !) SET INCLUDE=d:\wpstk\include; SET LIB=d:\wpstk\lib\; SET BOOKSHELF=d:\wpstk\book; SET HELPNDX=+d:\wpstk\book\wpstk.ndx - a batch file SET INCLUDE=d:\wpstk\include;%INCLUDE% SET LIB=d:\wpstk\lib\;%LIB% SET BOOKSHELF=d:\wpstk\book;%BOOKSHELF% SET HELPNDX=%HELPNDX%+d:\wpstk\book\wpstk.ndx - a makefile INCLUDE=d:\wpstk\include;$(INCLUDE) LIB=d:\wpstk\lib\;$(LIB) BOOKSHELF=d:\wpstk\book;$(BOOKSHELF) HELPNDX=$(HELPNDX)+d:\wpstk\book\wpstk.ndx  You are required to use NMAKE as the make tool to compile the toolkit and its samples. Using GNU make is not supported for the IBM compilers.  If you use the EPM when developing programs, you might further want to use the syntax-highlight extension for empkwds.c provided with the Workplace Shell Toolkit in order to have function names and defines of it highlighted. Simply append the contents of the file book\epm\epmkwds.c__ to the file epmkwds.c in your EPM directory and restart the EPM. ═══ 4.2. emx 0.9d for OS/2 - Prerequisites ═══ The following prerequisites apply when using the Workplace Shell Toolkit with the emx compiler:  Users of a source distribution of the Workplace Shell Toolkit are required to download it via CVS to an HPFS drive. A HPFS partition is also required in order to to compile it completely. One could copy a CVS development tree to a FAT partition, but then would have to manually copy the former GNUmakefile over the makefile in each directory, where existing. This would allow to compile at least the library itself and the sample programs, but the online docs could not be compiled, as the source files for this require long filenames.  Users of a binary distribution of the Workplace Shell Toolkit (not including the sources for the library or online doc) can install it onto a FAT drive, as long they need not to compile the sample programs.  You are reqired to append the pathname include and lib directories of the installed Workplace Shell Toolkit to the C_INCLUDE_PATH and LIBRARY_PATH environment variables. Optionally, if you use the EPM, you might also want to add the help index file to the HELPNDX environment variable. Note: - when you compile the Workplace Shell Toolkit yourself, the resulting libraries are put into directories named either debug or release instead of lib, depending on the debug status during compilation. - The emx reference states that all pathnames in the environment variables C_INCLUDE_PATH and LIBRARY_PATH should not include backslashes, but only forward slashes. Normally, you should not experience any problems when using backslashes, but in order to be on the safe side the makefiles of the Workplace Shell Toolkit will convert backslashes to forward slashes within these variables during the makefile process. - It is strongly recommended to setup the LIB environment variable to the same value as the environment variable LIBRARY_PATH. The Workplace Shell Toolkit must be compiled and can link only in the OMF format and thus uses LINK386.EXE, which in turn uses the LIB environment variable instead of LIBRARY_PATH. The Workplace Shell Toolkit will not enforce this automatically, as this severely changes your system configuration. You should be the person to do so... You can extend the environment variables either in - your config.sys file (not recommended !) - a batch file that you use to call to setup your environment. you may want to use the batchfile bin\wtkenv.cmd, setting up the environment automatically - your makefile Provided that you have installed the Workplace Shell Toolkit in a directory d:\wpstk, you extend the variables as follows in - your config.sys file SET C_INCLUDE_PATH=d:\wpstk\include; SET LIBRARY_PATH=d:\wpstk\lib\gcc; SET BOOKSHELF=d:\wpstk\book; SET HELPNDX=+d:\wpstk\book\wpstk.ndx - a batch file SET C_INCLUDE_PATH=d:\wpstk\include;%C_INCLUDE_PATH% SET LIBRARY_PATH=d:\wpstk\lib\gcc;%LIBRARY_PATH% SET BOOKSHELF=d:\wpstk\book;%BOOKSHELF% SET HELPNDX=%HELPNDX%+d:\wpstk\book\wpstk.ndx - a makefile C_INCLUDE_PATH=d:\wpstk\include;$(C_INCLUDE_PATH) LIBRARY_PATH=d:\wpstk\lib\gcc;$(LIBRARY_PATH) BOOKSHELF=d:\wpstk\book;$(BOOKSHELF) HELPNDX=$(HELPNDX)+d:\wpstk\book\wpstk.ndx  The Workplace Shell Toolkit must be compiled and can be linked only in the OMF format. To prepare your system for this, all GNUmakefiles implicitely call bin/config.cmd to determine, wether the OMF versions (.lib) of the emx libraries (.a) are already present. If not, it creates them directly in the lib directory of the emx compiler tree. See also emx 0.9d for OS/2 - makefile configuration Note: - If the OMF versions of the emx libraries do not already exist in the lib directory of the emx compiler tree, write access and approx. 4 MB free disk space are required on the drive, where you have installed the emx compiler in order to create them.  You are required to use GNU make as the make tool to compile the toolkit and its samples. Using NMAKE is not supported for the emx compiler.  If you use the EPM when developing programs, you might further want to use the syntax-highlight extension for empkwds.c provided with the Workplace Shell Toolkit in order to have function names and defines of it highlighted. Simply append the contents of the file book\epm\epmkwds.c__ to the file epmkwds.c in your EPM directory and restart the EPM. ═══ 5. Limitations ═══ The Workplace Shell Toolkit has not been tested with Object Rexx activated, so errors might occurr using the makefiles, which in turn call Rexx scripts. If errors occurr, please send a report to wpstk@netlabs.org. ═══ 6. Limitations for specific compilers ═══ The following prerequisites apply when using the Workplace Shell Toolkit with one of the following compilers:  emx 0.9d for OS/2 ═══ 6.1. Limitations for emx 0.9d for OS/2 ═══ The following limitations apply when using the Workplace Shell Toolkit with the emx compiler:  The Workplace Shell Toolkit must be compiled and can be linked only in the OMF format, as only with this format a standalone DLL for Workplace Shell classes can be compiled (gcc flags -Zsys and -Zso can only be used with -Zomf).  Due to several reasons, emx compiled Workplace Shell DLLs cannot be debugged with the GNU debugger. If you require debug information, use the pmprintf technique to obtain information what your program does when running. Also the test programs cannot be debugged with GDB, as GDB can debug only DOS programs or bound programs (DOS and OS/2). For more information, please refer to method E3 for creating executables with the emx compiler under OS/2: Introduction to the emx Application Developer's Guide ═══ 7. Linking the the Workplace Shell Toolkit runtime ═══ The Workplace Shell Toolkit can be linked to your application in two ways:  directly to your application, linking the compiler dependent code library wpstk.lib  to the runtime DLL wpstk.dll, linking the compiler dependent import library wpstki.lib Note:  For single Workplace Shell class DLLs or single executables direct code linkage is recommended.  It is no good idea to copy the runtime DLL with the original name wpstk.dll to a directory within the LIBPATH on a target system, as this would prevent from loading any other version of it once it is loaded in memory and used by an application or Workplace Shell class DLL. Having said that, if you plan to ship the runtime DLL for usage with multiple binaries (exe or DLL) of your application package, it is recommended to perform one or all of the following steps in order not to interfere with older versions of the runtime, having possibly an incompatible API:  run a DLLRNAME utility onto a copy of wpstk.dll and the executables being linked to it and so ship the DLL with a different name (as a DLL must comply to 8.3)  explicitely check the version number of wpstk.dll within the startup code of your application and exit, if it does not apply to the version required. This makes sense even with a renamed runtime DLL for the case, if older versions of your application package are already installed and accidentally newer binaries are installed to a system without updating the runtime DLL. While the code and import libraries are well compiler dependent and therefore a version for each supported compiler is  created in the directories debug or release within the development tree of a source distribution  shipped in the directory lib within the installation tree of a binary distibution, the runtime DLLs can be mixed between compilers. All DLLs are linked with a standalone mutlithreading compiler runtime and using system linkage, so that they are compatible among binaries linked to them, being complied with different of the supported compilers. ═══ 8. Workplace Shell Toolkit Functions ═══ This chapter contains a list of the functions available in the Workplace Shell Toolkit. WPS Toolkit version function  WtkQueryVersion Module helper functions (EXE and DLL)  WtkGetModuleHandle  WtkGetModuleInfo  WtkGetPackageFilename PM control helper functions  WtkInitializeNumSpinbuttonArray  WtkIsOfPublicPmClass  WtkQueryClassIndex  WtkQueryNumSpinbuttonIndex System helper functions  WtkIsWarp4  WtkQueryBootDrive  WtkQuerySysLanguage device IO control helper functions  WtkDevIOCtl  WtkOpenDevice Error helper functions  WtkSetErrorInfo File helper functions  WtkCreatePath  WtkCreateTmpFile  WtkDeletePath  WtkDirExists  WtkFileExists  WtkFileMaskExists  WtkFileModified  WtkFilespec  WtkGetNextDirectory  WtkGetNextFile  WtkIsDirectory  WtkIsFile  WtkQueryCurrentDir  WtkQueryFileSize  WtkQueryFullname  WtkReadFile  WtkSetCurrentDir  WtkWriteFile Date and time related helper functions  WtkCDateTimeToTime  WtkDateTimeToTime  WtkFDateTimeToTime  WtkQueryCDateTimeStamp  WtkQueryDateTimeStamp  WtkQueryFDateTimeStamp  WtkQueryFileCDateTime  WtkQueryFileDateTime  WtkQueryFileFDateTime  WtkSetCDateTime  WtkSetDateTime  WtkSetFDateTime  WtkTimeToCDateTime  WtkTimeToDateTime  WtkTimeToFDateTime CRC related helper functions  WtkCalcFileCRC32  WtkCalcMemCRC32 Text Message File functions  WtkGetTextMessage Settings and details manager functions  WtkAddClassDetail  WtkAddClassSetting  WtkCloseClassSettingsTable  WtkCreateClassSettingsTable  WtkCreateObjectValueTable  WtkDeregisterSettingsDialog  WtkDestroyClassSettingsTable  WtkDestroyObjectValueTable  WtkDumpClassSettingsTable  WtkEvaluateObjectSettings  WtkQueryClassDetailsInfo  WtkQueryGUIControlsChanged  WtkQueryObjectDetailsData  WtkQueryObjectSettings  WtkReadObjectValueTable  WtkRegisterSettingsDialog  WtkRegisterSettingsNotebook  WtkRelocateNotebookpageControls  WtkRestoreObjectSettings  WtkRestoreObjectState  WtkSaveObjectSettings  WtkSaveObjectState  WtkValidateObjectValueTable  WtkWriteObjectValueTable Extended Attributes manager functions  WtkAppendEaValue  WtkCloseEa  WtkCreateEa  WtkFindFirstEaValue  WtkFindNextEaValue  WtkGetNextEaValue  WtkPutEaValue  WtkQueryEaSize  WtkReadEa  WtkReadStringEa  WtkSaveEa  WtkWriteStringEa Memory Mapped Files manager functions  WtkAllocMmf  WtkFreeMmf  WtkInitializeMmf  WtkQueryMmfSize  WtkSetMmfSize  WtkTerminateMmf  WtkUpdateMmf ═══ 8.1. WtkAddClassDetail ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkAddClassDetail - Syntax ═══ This function adds a detail to the class settings table. #define INCL_WTKSETTINGS #include HSETTINGTABLE hst; /* Settingstable handle. */ ULONG ulSettingId; /* Settings ID. */ BOOL fResult; /* Success indicator. */ fResult = WtkAddClassDetail( hst, ulSettingId); ═══ WtkAddClassDetail - Parameter hst ═══ hst (HSETTINGTABLE) - input Settingstable handle. ═══ WtkAddClassDetail - Parameter ulSettingId ═══ ulSettingId (ULONG) - input Settings ID. This ID must be greater than zero and unique among all settings and details added to a class settingstable. While it is used to save and restores object instance settings values to or from the WPS repository, details are not stored, but still need an ID to be uniquely identified, as they do not have a symbolic name. See also the remarks on the same parameter ulSettingId for the function WtkAddClassSetting, as both APIs work nearly the same ! ═══ WtkAddClassDetail - Parameters ═══ hst (HSETTINGTABLE) - input Settingstable handle. ulSettingId (ULONG) - input Settings ID. This ID must be greater than zero and unique among all settings and details added to a class settingstable. While it is used to save and restores object instance settings values to or from the WPS repository, details are not stored, but still need an ID to be uniquely identified, as they do not have a symbolic name. See also the remarks on the same parameter ulSettingId for the function WtkAddClassSetting, as both APIs work nearly the same ! fResult (BOOL) - returns Success indicator. TRUE Detail could be added to the class settings table FALSE An error occurred. ═══ WtkAddClassDetail Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Detail could be added to the class settings table FALSE An error occurred. ═══ WtkAddClassDetail - Remarks ═══ This function is to be called during _wpclsInitData, right after having created the class settingstable with WtkCreateClassSettingsTable. WtkAddClassDetail has to be called once for each detail to be added to the class settingstable. After having added all details and settings to class settingstable, the WPS Class needs to close the class settingstable with WtkCloseClassSettingsTable in order make the table available for the objects (instances) of the WPS class. ═══ WtkAddClassDetail - Related functions ═══ Related Functions none ═══ 8.2. WtkAddClassSetting ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkAddClassSetting - Syntax ═══ This function adds a setting to the class settings table. #define INCL_WTKSETTINGS #include HSETTINGTABLE hst; /* Settingstable handle. */ ULONG ulSettingId; /* Settings ID. */ PSZ pszSetting; /* Address of the ASCIIZ name and default value string of the setting. */ ULONG ulQueryCount; /* Query count of a setting. */ BOOL fResult; /* Success indicator. */ fResult = WtkAddClassSetting( hst, ulSettingId, pszSetting, ulQueryCount); ═══ WtkAddClassSetting - Parameter hst ═══ hst (HSETTINGTABLE) - input Settingstable handle. ═══ WtkAddClassSetting - Parameter ulSettingId ═══ ulSettingId (ULONG) - input Settings ID. This ID must be either zero or unique among all settings and details added to a class settingstable. Note:  A none-zero value allows to have the corresponding object instance settings values saved and restored to or from the WPS repository by WtkSaveObjectState and WtkRestoreObjectState. For the added setting a range of settings IDs instead of only the specified one will automatically be reserved for if the setting - has subvalues - this is the case if the string pointed to by pszSetting contains more than one value, separated by commas - and/or can be queried multiple times - this is the case if ulQueryCount is greater than 1 All IDs within that range cannot be used by other settings. The reserved range will be all IDs from ulSettingId to ulSettingId + (subvaluecount * querycount) - 1.  If used (not setting this value to zero), do not change this id for a given setting in future versions of your WPS class, otherwise values of existing instances cannot be restored properly with WtkRestoreObjectState. This may lead to unpredictable results !  Th same applies to the order of subvalues, they may not be changed in their order, as the calculated ID for a subvalue cannot be changed for existing instances at a later point of time. ═══ WtkAddClassSetting - Parameter pszSetting ═══ pszSetting (PSZ) - input Address of the ASCIIZ name and default value string of the setting. This string must have the form NAME=value; where value can  may be either empty or specify a default value, which is used, when no value is specified for this setting when a settings string is sended to an object of this class  consist of several subvalues, each separated by commas. Each subvalue then may either be empty or specify a default value. For each subvalue, a comma must be included within the string. Here are some examples: "IPCONFIG=DYNAMIC;" "LOCALIP=;" "MTU=1500;" "DEFAULTROUTE=YES;" "COMINIT=9600,n,8,1;" The following example defines a setting with four subvalues, but with no default values: "MYSETTING=,,,;" ═══ WtkAddClassSetting - Parameter ulQueryCount ═══ ulQueryCount (ULONG) - input Query count of a setting. This value must not be zero! It may be set to a value  of one, indicating that this setting can have only one value.  greater than one, indicating that this setting can have more than one value. When the WPS class determines the current settings by calling WtkQueryObjectSettings or saves the settings with either WtkSaveObjectState or WtkSaveObjectSettings, the Settings Manager asks the callback of the WPS class "ulQueryCount" times for the current value of that setting. For to be able to handle a setting with multiple values, it needs to have at least one subvalue per dimension to build up a twodimensional matrix internally. An example for a multidimensional setting is: name CURRENTDIR value 1 drive value 2 current dir of drive In order to query all drives, you would set ulQueryCount to 26 and let WtkQueryObjectSettings query 26 times the value for the setting CURRENTDIR. When being asked for that setting, you would place the current directory of the drive into the target buffer for that setting accoring to the query index (0-25). WtkQueryObjectSettings would then place somewhat like this into the resulting settingstring: "CURRENTDIR=A:,\;" "CURRENTDIR=C:,\OS2;" "CURRENTDIR=D:,\TCPIP;" etc. The alternative would be to define a separate setting for each drive (CURRENTDIRA, CURRENTDIRB) or have a separate WPS class for such instances. ═══ WtkAddClassSetting - Parameters ═══ hst (HSETTINGTABLE) - input Settingstable handle. ulSettingId (ULONG) - input Settings ID. This ID must be either zero or unique among all settings and details added to a class settingstable. Note:  A none-zero value allows to have the corresponding object instance settings values saved and restored to or from the WPS repository by WtkSaveObjectState and WtkRestoreObjectState. For the added setting a range of settings IDs instead of only the specified one will automatically be reserved for if the setting - has subvalues - this is the case if the string pointed to by pszSetting contains more than one value, separated by commas - and/or can be queried multiple times - this is the case if ulQueryCount is greater than 1 All IDs within that range cannot be used by other settings. The reserved range will be all IDs from ulSettingId to ulSettingId + (subvaluecount * querycount) - 1.  If used (not setting this value to zero), do not change this id for a given setting in future versions of your WPS class, otherwise values of existing instances cannot be restored properly with WtkRestoreObjectState. This may lead to unpredictable results !  Th same applies to the order of subvalues, they may not be changed in their order, as the calculated ID for a subvalue cannot be changed for existing instances at a later point of time. pszSetting (PSZ) - input Address of the ASCIIZ name and default value string of the setting. This string must have the form NAME=value; where value can  may be either empty or specify a default value, which is used, when no value is specified for this setting when a settings string is sended to an object of this class  consist of several subvalues, each separated by commas. Each subvalue then may either be empty or specify a default value. For each subvalue, a comma must be included within the string. Here are some examples: "IPCONFIG=DYNAMIC;" "LOCALIP=;" "MTU=1500;" "DEFAULTROUTE=YES;" "COMINIT=9600,n,8,1;" The following example defines a setting with four subvalues, but with no default values: "MYSETTING=,,,;" ulQueryCount (ULONG) - input Query count of a setting. This value must not be zero! It may be set to a value  of one, indicating that this setting can have only one value.  greater than one, indicating that this setting can have more than one value. When the WPS class determines the current settings by calling WtkQueryObjectSettings or saves the settings with either WtkSaveObjectState or WtkSaveObjectSettings, the Settings Manager asks the callback of the WPS class "ulQueryCount" times for the current value of that setting. For to be able to handle a setting with multiple values, it needs to have at least one subvalue per dimension to build up a twodimensional matrix internally. An example for a multidimensional setting is: name CURRENTDIR value 1 drive value 2 current dir of drive In order to query all drives, you would set ulQueryCount to 26 and let WtkQueryObjectSettings query 26 times the value for the setting CURRENTDIR. When being asked for that setting, you would place the current directory of the drive into the target buffer for that setting accoring to the query index (0-25). WtkQueryObjectSettings would then place somewhat like this into the resulting settingstring: "CURRENTDIR=A:,\;" "CURRENTDIR=C:,\OS2;" "CURRENTDIR=D:,\TCPIP;" etc. The alternative would be to define a separate setting for each drive (CURRENTDIRA, CURRENTDIRB) or have a separate WPS class for such instances. fResult ( BOOL) - returns Success indicator. TRUE Setting could be added to the class settings table FALSE An error occurred. ═══ WtkAddClassSetting Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Setting could be added to the class settings table FALSE An error occurred. ═══ WtkAddClassSetting - Remarks ═══ This function is to be called during _wpclsInitData, right after having created the class settingstable with WtkCreateClassSettingsTable. WtkAddClassSetting has to be called once for each setting to be added to the class settingstable. After having added all details and settings to class settingstable, the WPS Class needs to close the class settingstable with WtkCloseClassSettingsTable in order make the table available for the objects (instances) of the WPS class. ═══ WtkAddClassSetting - Related functions ═══ Related Functions none ═══ 8.3. WtkAllocMmf ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkAllocMmf - Syntax ═══ This function allocates a dynamic memory buffer either for a file or plain memory access. #define INCL_WTKMMF #include HMMF hmmf; /* Handle to the MMF manager. */ PVOID *ppvdata; /* Pointer to a variable receiving the pointer to the allocated address space. */ PSZ pszFilename; /* Address of the ASCIIZ path name or MMF_FILE_INMEMORY. */ ULONG ulOpenFlags; /* Access and open mode flags for file access. */ ULONG ulMaxSize; /* Maximum possible size of the dynamic memory in bytes. */ APIRET ulrc; /* Return Code. */ ulrc = WtkAllocMmf( hmmf, *ppvdata, pszFilename, ulOpenFlags, ulMaxSize); ═══ WtkAllocMmf - Parameter hmmf ═══ hmmf (HMMF) - input Handle to the MMF manager. ═══ WtkAllocMmf - Parameter *ppvdata ═══ *ppvdata (PVOID) - output Pointer to a variable receiving the pointer to the allocated address space. ═══ WtkAllocMmf - Parameter pszFilename ═══ pszFilename (PSZ) - input Address of the ASCIIZ path name or MMF_FILE_INMEMORY. If no file is specified, MMF_FILE_INMEMORY (equals NULL) will allocate a dynamic memory buffer only. The path name may contain ?: for the drive in order to open the file on the boot drive. The name may not include wildcards. ═══ WtkAllocMmf - Parameter ulOpenFlags ═══ ulOpenFlags (ULONG) - input Access and open mode flags for file access. The following access modes are valid (specify one): MMF_ACCESS_READONLY open file in readonly mode and deny write by others (default) MMF_ACCESS_WRITEONLY open file in writeonly mode and deny write by others MMF_ACCESS_READWRITE open file in readwrite mode and deny read and write by others The following open modes are valid (specify one): MMF_OPENMODE_OPENFILE open existing file or create new one MMF_OPENMODE_RESETFILE reset existing file or create new one ═══ WtkAllocMmf - Parameter ulMaxSize ═══ ulMaxSize (ULONG) - input Maximum possible size of the dynamic memory in bytes. This maximum size cannot be changed later. ═══ WtkAllocMmf - Parameters ═══ hmmf (HMMF) - input Handle to the MMF manager. *ppvdata (PVOID) - output Pointer to a variable receiving the pointer to the allocated address space. pszFilename (PSZ) - input Address of the ASCIIZ path name or MMF_FILE_INMEMORY. If no file is specified, MMF_FILE_INMEMORY (equals NULL) will allocate a dynamic memory buffer only. The path name may contain ?: for the drive in order to open the file on the boot drive. The name may not include wildcards. ulOpenFlags (ULONG) - input Access and open mode flags for file access. The following access modes are valid (specify one): MMF_ACCESS_READONLY open file in readonly mode and deny write by others (default) MMF_ACCESS_WRITEONLY open file in writeonly mode and deny write by others MMF_ACCESS_READWRITE open file in readwrite mode and deny read and write by others The following open modes are valid (specify one): MMF_OPENMODE_OPENFILE open existing file or create new one MMF_OPENMODE_RESETFILE reset existing file or create new one ulMaxSize (ULONG) - input Maximum possible size of the dynamic memory in bytes. This maximum size cannot be changed later. ulrc (APIRET) - returns Return Code. WtkAllocMmf returns one of the following return codes: 0 NO_ERROR 4 ERROR_TOO_MANY_OPEN_FILES 6 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosOpen  DosAllocMem ═══ WtkAllocMmf Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkAllocMmf returns one of the following return codes: 0 NO_ERROR 4 ERROR_TOO_MANY_OPEN_FILES 6 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosOpen  DosAllocMem ═══ WtkAllocMmf - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file on the boot drive. The file is kept open until WtkFreeMmf is called to release the provided memory buffer again. Until that reading or writing to that file by others is denied according to the access flags specified for parameter ulOpenFlags. The memory requested my WtkAllocMmf is not committed by default. This means requestion large amounts of memory will not lead to requesting physical memory of that size, but only reserving the address space. Memory is then committed by the MMF exception handler only when accessed either for read or write. Nevertheless it is a good idea not to reserve more address space than needed, as only some hundred megabytes can be addressed per process. ═══ WtkAllocMmf - Related functions ═══ Related Functions none ═══ 8.4. WtkAppendEaValue ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkAppendEaValue - Syntax ═══ This function appends a value to an extended attribute in memory. #define INCL_WTKEAS #include HEA hea; /* Handle to the extended attribute. */ ULONG ulMultiType; /* Multitype of the value to be added to the extended attribute. */ ULONG ulEaType; /* Type of the value to be added to the extended attribute. */ PBYTE pbValue; /* The address of a buffer of the value to be written. */ ULONG ulValuelen; /* The length, in bytes, of the buffer described by pbValue. */ APIRET ulrc; /* Return Code. */ ulrc = WtkAppendEaValue( hea, ulMultiType, ulEaType, pbValue, ulValuelen); ═══ WtkAppendEaValue - Parameter hea ═══ hea (HEA) - input Handle to the extended attribute. ═══ WtkAppendEaValue - Parameter ulMultiType ═══ ulMultiType (ULONG) - input Multitype of the value to be added to the extended attribute. Specify EAT_MVST to add a value to a multi value, single type extended attribute. This only works, if this is the first value being appended or the existing extended attribute is already multi value, single type, and ulEaType is of the same type as the existing value(s). EAT_MVMT to add a value to a multi value, multi type extended attribute. This only works, if this is the first value being appended or the existing extended attribute is already multi value, multi type. Other EAT_* to add a value to a single value, single type extended attribute This only works, if this is the first value being appended, otherwise it would not be single value, single type ... ═══ WtkAppendEaValue - Parameter ulEaType ═══ ulEaType (ULONG) - input Type of the value to be added to the extended attribute. Specify EAT_ASCII to add a string value EAT_BINARY to add a binary value EAT_ICON to add an icon EAT_BITMAP to add a bitmap EAT_METAFILE to add a meta file EAT_EA to add the name of an embedded extended attribute as an ASCII string ═══ WtkAppendEaValue - Parameter pbValue ═══ pbValue (PBYTE) - input The address of a buffer of the value to be written. ═══ WtkAppendEaValue - Parameter ulValuelen ═══ ulValuelen (ULONG) - input The length, in bytes, of the buffer described by pbValue. ═══ WtkAppendEaValue - Parameters ═══ hea (HEA) - input Handle to the extended attribute. ulMultiType (ULONG) - input Multitype of the value to be added to the extended attribute. Specify EAT_MVST to add a value to a multi value, single type extended attribute. This only works, if this is the first value being appended or the existing extended attribute is already multi value, single type, and ulEaType is of the same type as the existing value(s). EAT_MVMT to add a value to a multi value, multi type extended attribute. This only works, if this is the first value being appended or the existing extended attribute is already multi value, multi type. Other EAT_* to add a value to a single value, single type extended attribute This only works, if this is the first value being appended, otherwise it would not be single value, single type ... ulEaType (ULONG) - input Type of the value to be added to the extended attribute. Specify EAT_ASCII to add a string value EAT_BINARY to add a binary value EAT_ICON to add an icon EAT_BITMAP to add a bitmap EAT_METAFILE to add a meta file EAT_EA to add the name of an embedded extended attribute as an ASCII string pbValue (PBYTE) - input The address of a buffer of the value to be written. ulValuelen (ULONG) - input The length, in bytes, of the buffer described by pbValue. ulrc (APIRET) - returns Return Code. WtkAppendEaValue returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE 8 ERROR_NOT_ENOUGH_MEMORY 13 ERROR_INVALID_DATA 87 ERROR_INVALID_PARAMETER ═══ WtkAppendEaValue Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkAppendEaValue returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE 8 ERROR_NOT_ENOUGH_MEMORY 13 ERROR_INVALID_DATA 87 ERROR_INVALID_PARAMETER ═══ WtkAppendEaValue - Remarks ═══ This function allocates resources for handling the value of the given extended attribute, which must be freeed by calling WtkCloseEa, when not longer needed. ═══ WtkAppendEaValue - Related functions ═══ Related Functions none ═══ 8.5. WtkCDateTimeToTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCDateTimeToTime - Syntax ═══ This function converts the contents of a CDATE and a CTIME stucture to a time value used by the compiler runtime. #define INCL_WTKUTLTIME #include PCDATE pcdate; /* Address of the CDATE structure. */ PCTIME pctime; /* Address of the CTIME structure. */ time_t *ptime; /* Address of the resulting time value. */ BOOL fResult; /* Success indicator. */ fResult = WtkCDateTimeToTime( pcdate, pctime, ptime); ═══ WtkCDateTimeToTime - Parameter pcdate ═══ pcdate (PCDATE) - input Address of the CDATE structure. ═══ WtkCDateTimeToTime - Parameter pctime ═══ pctime (PCTIME) - input Address of the CTIME structure. ═══ WtkCDateTimeToTime - Parameter ptime ═══ ptime (time_t*) - output Address of the resulting time value. ═══ WtkCDateTimeToTime - Parameters ═══ pcdate (PCDATE) - input Address of the CDATE structure. pctime (PCTIME) - input Address of the CTIME structure. ptime (time_t*) - output Address of the resulting time value. fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkCDateTimeToTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkCDateTimeToTime - Remarks ═══ This function does not check any of the values of the CDATE or CTIME structures before converting. ═══ WtkCDateTimeToTime - Related functions ═══ Related Functions none ═══ 8.6. WtkCalcFileCRC32 ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCalcFileCRC32 - Syntax ═══ This function calculates a 32-bit CRC for a given file. #define INCL_WTKUTLCRC #include PSZ pszFilename; /* Address of the ASCIIZ filename, for which the 32-bit CRC is to be calculated. */ PULONG pulCRC32; /* The address of a variable, into which the 32-bit CRC for the file is returned. */ APIRET ulrc; /* Return Code. */ ulrc = WtkCalcFileCRC32( pszFilename, pulCRC32); ═══ WtkCalcFileCRC32 - Parameter pszFilename ═══ pszFilename (PSZ) - input Address of the ASCIIZ filename, for which the 32-bit CRC is to be calculated. The path name may contain ?: for the drive in order to read the file from the boot drive. ═══ WtkCalcFileCRC32 - Parameter pulCRC32 ═══ pulCRC32 (PULONG) - output The address of a variable, into which the 32-bit CRC for the file is returned. ═══ WtkCalcFileCRC32 - Parameters ═══ pszFilename (PSZ) - input Address of the ASCIIZ filename, for which the 32-bit CRC is to be calculated. The path name may contain ?: for the drive in order to read the file from the boot drive. pulCRC32 (PULONG) - output The address of a variable, into which the 32-bit CRC for the file is returned. ulrc (APIRET) - returns Return Code. WtkCalcFileCRC32 returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosOpen ═══ WtkCalcFileCRC32 Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkCalcFileCRC32 returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosOpen ═══ WtkCalcFileCRC32 - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to read the file from the boot drive. ═══ WtkCalcFileCRC32 - Related functions ═══ Related Functions none ═══ 8.7. WtkCalcMemCRC32 ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCalcMemCRC32 - Syntax ═══ This function calculates a 32-bit CRC for a memory buffer. A CRC can also be calculated in multiple calls. This code has been adapted from Radim Kolars crc.c of CRC V0.1. #define INCL_WTKUTLCRC #include PVOID pvData; /* Address of the buffer, for which the 32-bit CRC is to be calculated. */ ULONG ulDatalen; /* The length, in bytes, of the buffer described by pvData. */ PULONG pulCRC32; /* The address of a variable for the starting value for the CRC calculation and storage for the resulting 32-bit CRC. */ APIRET ulrc; /* Return Code. */ ulrc = WtkCalcMemCRC32( pvData, ulDatalen, pulCRC32); ═══ WtkCalcMemCRC32 - Parameter pvData ═══ pvData (PVOID) - input Address of the buffer, for which the 32-bit CRC is to be calculated. ═══ WtkCalcMemCRC32 - Parameter ulDatalen ═══ ulDatalen (ULONG) - input The length, in bytes, of the buffer described by pvData. ═══ WtkCalcMemCRC32 - Parameter pulCRC32 ═══ pulCRC32 (PULONG) - input/output The address of a variable for the starting value for the CRC calculation and storage for the resulting 32-bit CRC. Input starting value for CRC calculation. On a first call, set this value to -1. On consecutive calls, leave the value as returned by the previous call to WtkCalcMemCRC32. Output resulting CRC value ═══ WtkCalcMemCRC32 - Parameters ═══ pvData (PVOID) - input Address of the buffer, for which the 32-bit CRC is to be calculated. ulDatalen (ULONG) - input The length, in bytes, of the buffer described by pvData. pulCRC32 (PULONG) - input/output The address of a variable for the starting value for the CRC calculation and storage for the resulting 32-bit CRC. Input starting value for CRC calculation. On a first call, set this value to -1. On consecutive calls, leave the value as returned by the previous call to WtkCalcMemCRC32. Output resulting CRC value ulrc (APIRET) - returns Return Code. WtkCalcMemCRC32 returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW 123 ERROR_INVALID_NAME or return codes of the following functions  DosOpen ═══ WtkCalcMemCRC32 Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkCalcMemCRC32 returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW 123 ERROR_INVALID_NAME or return codes of the following functions  DosOpen ═══ WtkCalcMemCRC32 - Remarks ═══ When WtkCalcMemCRC32 is called to calculate a 32-bit CRC for one memory buffer, the variable pointed to by pulCRC32 has to be set to -1. If the CRC is to be calculated for multiple memory buffers by calling WtkCalcMemCRC32 several times, the variable pointed to by pulCRC32 has to be set to -1 for the first call only. On consecutive calls, leave the value as returned by the previous call to WtkCalcMemCRC32. ═══ WtkCalcMemCRC32 - Related functions ═══ Related Functions none ═══ 8.8. WtkCloseClassSettingsTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCloseClassSettingsTable - Syntax ═══ This function closes the class settingstable, so that objects (instances) of the WPS class can use it. #define INCL_WTKSETTINGS #include HSETTINGTABLE hst; /* Settingstable handle. */ BOOL fResult; /* Success indicator. */ fResult = WtkCloseClassSettingsTable( hst); ═══ WtkCloseClassSettingsTable - Parameter hst ═══ hst (HSETTINGTABLE) - input Settingstable handle. ═══ WtkCloseClassSettingsTable - Parameters ═══ hst (HSETTINGTABLE) - input Settingstable handle. fResult (BOOL) - returns Success indicator. TRUE Class settingstable was closed successfully. FALSE An error occurred. ═══ WtkCloseClassSettingsTable Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Class settingstable was closed successfully. FALSE An error occurred. ═══ WtkCloseClassSettingsTable - Remarks ═══ This function is to be called during _wpclsInitData, right after having created the class settingstable with WtkCreateClassSettingsTable and added all settings and details with  WtkAddClassSetting  WtkAddClassDetail If the WPS class does not close the settingstable using WtkCloseClassSettingsTable, it cannot be used by objects (instances() of the WPS class. ═══ WtkCloseClassSettingsTable - Related functions ═══ Related Functions none ═══ 8.9. WtkCloseEa ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCloseEa - Syntax ═══ This function releases the reosurces for handling an extended attribute. #define INCL_WTKEAS #include HEA hea; /* Handle to the extended attribute. */ APIRET ulrc; /* Return Code. */ ulrc = WtkCloseEa( hea); ═══ WtkCloseEa - Parameter hea ═══ hea (HEA) - input Handle to the extended attribute. ═══ WtkCloseEa - Parameters ═══ hea (HEA) - input Handle to the extended attribute. ulrc (APIRET) - returns Return Code. WtkCloseEa returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE ═══ WtkCloseEa Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkCloseEa returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE ═══ WtkCloseEa - Remarks ═══ This function does not write the extended attribute to disk. Use WtkSaveEa before to write changes to disk, if necessary. ═══ WtkCloseEa - Related functions ═══ Related Functions none ═══ 8.10. WtkCreateClassSettingsTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCreateClassSettingsTable - Syntax ═══ This function creates a settings table for a meta class. #define INCL_WTKSETTINGS #include PVOID pvObjectClass; /* somSelf of the meta class. */ PFNCB pfnCallbackValue; /* Adress of the callback procedure. */ HSETTINGTABLE hsettingtable; /* Settingstable handle. */ hsettingtable = WtkCreateClassSettingsTable( pvObjectClass, pfnCallbackValue); ═══ WtkCreateClassSettingsTable - Parameter pvObjectClass ═══ pvObjectClass (PVOID) - input somSelf of the meta class. ═══ WtkCreateClassSettingsTable - Parameter pfnCallbackValue ═══ pfnCallbackValue (PFNCB) - input Adress of the callback procedure. ═══ WtkCreateClassSettingsTable - Parameters ═══ pvObjectClass (PVOID) - input somSelf of the meta class. pfnCallbackValue (PFNCB) - input Adress of the callback procedure. hsettingtable (HSETTINGTABLE) - returns Settingstable handle. NULLHANDLE Settingstable could not be created. other handle to the new settingstable ═══ WtkCreateClassSettingsTable Return Value - hsettingtable ═══ hsettingtable (HSETTINGTABLE) - returns Settingstable handle. NULLHANDLE Settingstable could not be created. other handle to the new settingstable ═══ WtkCreateClassSettingsTable - Remarks ═══ This function is to be called during _wpsclsInitData. After having created the settingstable, still within _wpsclsInitData settings and details are to be added to the table by invoking  WtkAddClassSetting  WtkAddClassDetail and the table is to be closed for usage by instances of the WPS class by calling  WtkCloseClassSettingsTable ═══ WtkCreateClassSettingsTable - Related functions ═══ Related Functions none ═══ 8.11. WtkCreateEa ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCreateEa - Syntax ═══ This function creates an extended attribute with no values in memory. #define INCL_WTKEAS #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory, that the extended attribute shall belong to. */ PSZ pszEaName; /* Address of the ASCIIZ name of the extended attribute. */ PHEA phea; /* The address of a variable containing the handle to the extended attribute */ APIRET ulrc; /* Return Code. */ ulrc = WtkCreateEa( pszName, pszEaName, phea); ═══ WtkCreateEa - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory, that the extended attribute shall belong to. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. The name may not include wildcards. ═══ WtkCreateEa - Parameter pszEaName ═══ pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. ═══ WtkCreateEa - Parameter phea ═══ phea (PHEA) - output The address of a variable containing the handle to the extended attribute ═══ WtkCreateEa - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory, that the extended attribute shall belong to. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. The name may not include wildcards. pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. phea (PHEA) - output The address of a variable containing the handle to the extended attribute ulrc (APIRET) - returns Return Code. WtkCreateEa returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 87 ERROR_INVALID_PARAMETER ═══ WtkCreateEa Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkCreateEa returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 87 ERROR_INVALID_PARAMETER ═══ WtkCreateEa - Remarks ═══ This function allocates resources for handling the value of the given extended attribute, which must be freeed by calling WtkCloseEa, when not longer needed. This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkCreateEa - Related functions ═══ Related Functions none ═══ 8.12. WtkCreateObjectValueTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCreateObjectValueTable - Syntax ═══ This function creates a valuetable for an object (instance) of a WPS class. #define INCL_WTKSETTINGS #include HSETTINGTABLE hst; /* Settingstable handle. */ PVOID pvObjectInstance; /* somSelf of the object. */ PVOID pvObjectData; /* somThis of the object. */ HVALUETABLE hvaluetable; /* Valuetable handle. */ hvaluetable = WtkCreateObjectValueTable( hst, pvObjectInstance, pvObjectData); ═══ WtkCreateObjectValueTable - Parameter hst ═══ hst (HSETTINGTABLE) - input Settingstable handle. Note: The settingstable being specified must have been closed before by calling WtkCloseClassSettingsTable. ═══ WtkCreateObjectValueTable - Parameter pvObjectInstance ═══ pvObjectInstance (PVOID) - input somSelf of the object. ═══ WtkCreateObjectValueTable - Parameter pvObjectData ═══ pvObjectData (PVOID) - input somThis of the object. ═══ WtkCreateObjectValueTable - Parameters ═══ hst (HSETTINGTABLE) - input Settingstable handle. Note: The settingstable being specified must have been closed before by calling WtkCloseClassSettingsTable. pvObjectInstance (PVOID) - input somSelf of the object. pvObjectData (PVOID) - input somThis of the object. hvaluetable (HVALUETABLE) - returns Valuetable handle. NULLHANDLE Valuetable could not be created. other handle to the new settingstable ═══ WtkCreateObjectValueTable Return Value - hvaluetable ═══ hvaluetable (HVALUETABLE) - returns Valuetable handle. NULLHANDLE Valuetable could not be created. other handle to the new settingstable ═══ WtkCreateObjectValueTable - Remarks ═══ This function is to be called during _wpInitData. This way it creates a table for settingsvalues for each object (instance) of the WPS class. ═══ WtkCreateObjectValueTable - Related functions ═══ Related Functions none ═══ 8.13. WtkCreatePath ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCreatePath - Syntax ═══ This function creates a complete path. An error is returned only, if the last subdirectory in the pathname could not be created. #define INCL_WTKUTLFILE #include PSZ pszPath; /* Address of the ASCIIZ path name of the path to be created. */ APIRET ulrc; /* Return Code. */ ulrc = WtkCreatePath( pszPath); ═══ WtkCreatePath - Parameter pszPath ═══ pszPath (PSZ) - input Address of the ASCIIZ path name of the path to be created. The path name may contain ?: for the drive in order to create the path on the boot drive. ═══ WtkCreatePath - Parameters ═══ pszPath (PSZ) - input Address of the ASCIIZ path name of the path to be created. The path name may contain ?: for the drive in order to create the path on the boot drive. ulrc (APIRET) - returns Return Code. WtkCreatePath returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosCreateDir ═══ WtkCreatePath Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkCreatePath returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosCreateDir ═══ WtkCreatePath - Remarks ═══ WtkCreatePath tries to create all directories within the path. An error is returned only, if the last subdirectory in the pathname could not be created. This function supports boot drive recognition. Specify ?: for the drive in order to create the path on the boot drive. ═══ WtkCreatePath - Related functions ═══ Related Functions none ═══ 8.14. WtkCreateTmpFile ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkCreateTmpFile - Syntax ═══ This function creates a temporary file of zero byte size with a generic name. Specify a filemask without drive and path in order to create the file in the %TMP% directory. #define INCL_WTKUTLFILE #include PSZ pszFileMask; /* Address of the ASCIIZ filemask, which is to be used to create a temporary file. */ PSZ pszBuffer; /* The address of a buffer, into which the full name of the newly created temporary file is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. */ APIRET ulrc; /* Return Code. */ ulrc = WtkCreateTmpFile( pszFileMask, pszBuffer, ulBuflen); ═══ WtkCreateTmpFile - Parameter pszFileMask ═══ pszFileMask (PSZ) - input Address of the ASCIIZ filemask, which is to be used to create a temporary file. The filename must contain one or more ?, which are being replaced by random digits. If the file mask specified with pszFileMask does neither contain a drive or a path specification, the temporary file is being created in the %TMP% directory. In order to create a temporary file in the current directory, you may specify a ".\" as the path component. The path name may contain ?: for the drive in order to create the temporary file on the boot drive. ═══ WtkCreateTmpFile - Parameter pszBuffer ═══ pszBuffer (PSZ) - output The address of a buffer, into which the full name of the newly created temporary file is returned. ═══ WtkCreateTmpFile - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ═══ WtkCreateTmpFile - Parameters ═══ pszFileMask (PSZ) - input Address of the ASCIIZ filemask, which is to be used to create a temporary file. The filename must contain one or more ?, which are being replaced by random digits. If the file mask specified with pszFileMask does neither contain a drive or a path specification, the temporary file is being created in the %TMP% directory. In order to create a temporary file in the current directory, you may specify a ".\" as the path component. The path name may contain ?: for the drive in order to create the temporary file on the boot drive. pszBuffer (PSZ) - output The address of a buffer, into which the full name of the newly created temporary file is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ulrc (APIRET) - returns Return Code. WtkCreateTmpFile returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW 123 ERROR_INVALID_NAME or return codes of the following functions  DosOpen ═══ WtkCreateTmpFile Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkCreateTmpFile returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW 123 ERROR_INVALID_NAME or return codes of the following functions  DosOpen ═══ WtkCreateTmpFile - Remarks ═══ If the file mask specified with pszFileMask does neither contain a drive or a path specification, the temporary file is being created in the %TMP% directory. In order to create a temporary file in the current directory, you may specify a ".\" as the path component. This function supports boot drive recognition. Specify ?: for the drive in order to create the temporary file on the boot drive. ═══ WtkCreateTmpFile - Related functions ═══ Related Functions none ═══ 8.15. WtkDateTimeToTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkDateTimeToTime - Syntax ═══ This function converts the contents of a DATETIME stucture to a time value used by the compiler runtime. #define INCL_WTKUTLTIME #include PDATETIME pdt; /* Address of the DATETIME structure. */ time_t *ptime; /* Address of the resulting time value. */ BOOL fResult; /* Success indicator. */ fResult = WtkDateTimeToTime( pdt, ptime); ═══ WtkDateTimeToTime - Parameter pdt ═══ pdt (PDATETIME) - input Address of the DATETIME structure. ═══ WtkDateTimeToTime - Parameter ptime ═══ ptime (time_t*) - output Address of the resulting time value. ═══ WtkDateTimeToTime - Parameters ═══ pdt (PDATETIME) - input Address of the DATETIME structure. ptime (time_t*) - output Address of the resulting time value. fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkDateTimeToTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkDateTimeToTime - Remarks ═══ This function does not check any of the values of the DATETIME structure before converting. ═══ WtkDateTimeToTime - Related functions ═══ Related Functions none ═══ 8.16. WtkDeletePath ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkDeletePath - Syntax ═══ This function deletes a complete path. An error is returned only, if the last subdirectory in the pathname could not be deleted. #define INCL_WTKUTLFILE #include PSZ pszPath; /* Address of the ASCIIZ path name of the path to be deleted. */ APIRET ulrc; /* Return Code. */ ulrc = WtkDeletePath( pszPath); ═══ WtkDeletePath - Parameter pszPath ═══ pszPath (PSZ) - input Address of the ASCIIZ path name of the path to be deleted. The path name may contain ?: for the drive in order to delete the path on the boot drive. ═══ WtkDeletePath - Parameters ═══ pszPath (PSZ) - input Address of the ASCIIZ path name of the path to be deleted. The path name may contain ?: for the drive in order to delete the path on the boot drive. ulrc (APIRET) - returns Return Code. WtkDeletePath returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosDeleteDir ═══ WtkDeletePath Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkDeletePath returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosDeleteDir ═══ WtkDeletePath - Remarks ═══ WtkDeletePath tries to delete all directories within the path. An error is returned only, if the last subdirectory in the pathname could not be deleted. This function supports boot drive recognition. Specify ?: for the drive in order to delete the file on the boot drive. ═══ WtkDeletePath - Related functions ═══ Related Functions none ═══ 8.17. WtkDeregisterSettingsDialog ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkDeregisterSettingsDialog - Syntax ═══ This function dereqisters a dialog of a settings notebookpage. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ HWND hwndDialog; /* Dialog handle of the settings notebook page. */ BOOL fResult; /* Success indicator. */ fResult = WtkDeregisterSettingsDialog( hvt, hwndDialog); ═══ WtkDeregisterSettingsDialog - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkDeregisterSettingsDialog - Parameter hwndDialog ═══ hwndDialog (HWND) - input Dialog handle of the settings notebook page. ═══ WtkDeregisterSettingsDialog - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. hwndDialog (HWND) - input Dialog handle of the settings notebook page. fResult (BOOL) - returns Success indicator. TRUE Dialog could be deregistered. FALSE An error occurred. ═══ WtkDeregisterSettingsDialog Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Dialog could be deregistered. FALSE An error occurred. ═══ WtkDeregisterSettingsDialog - Remarks ═══ This function is to be called in the WM_DESTROY message handling of the window procedure being used for the settings notebookpages. ═══ WtkDeregisterSettingsDialog - Related functions ═══ Related Functions none ═══ 8.18. WtkDestroyClassSettingsTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkDestroyClassSettingsTable - Syntax ═══ This function destroys a settings table for a meta class. #define INCL_WTKSETTINGS #include HSETTINGTABLE hst; /* Settingstable handle. */ BOOL fResult; /* Success indicator. */ fResult = WtkDestroyClassSettingsTable( hst); ═══ WtkDestroyClassSettingsTable - Parameter hst ═══ hst (HSETTINGTABLE) - input Settingstable handle. ═══ WtkDestroyClassSettingsTable - Parameters ═══ hst (HSETTINGTABLE) - input Settingstable handle. fResult (BOOL) - returns Success indicator. TRUE Settingstable could be destroyed. FALSE An error occurred. ═══ WtkDestroyClassSettingsTable Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Settingstable could be destroyed. FALSE An error occurred. ═══ WtkDestroyClassSettingsTable - Remarks ═══ This function is to be called during _wpclsUnInitData. ═══ WtkDestroyClassSettingsTable - Related functions ═══ Related Functions none ═══ 8.19. WtkDestroyObjectValueTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkDestroyObjectValueTable - Syntax ═══ This function detroys a valuetable for an object (instance) of a WPS class. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ BOOL fResult; /* Success indicator. */ fResult = WtkDestroyObjectValueTable( hvt); ═══ WtkDestroyObjectValueTable - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkDestroyObjectValueTable - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. fResult (BOOL) - returns Success indicator. TRUE Valuetable could be destroyed. FALSE An error occurred. ═══ WtkDestroyObjectValueTable Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Valuetable could be destroyed. FALSE An error occurred. ═══ WtkDestroyObjectValueTable - Remarks ═══ This function is to be called during _wpUnInitData. ═══ WtkDestroyObjectValueTable - Related functions ═══ Related Functions none ═══ 8.20. WtkDevIOCtl ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkDevIOCtl - Syntax ═══ This function performs an I/O control call transaction using DosDevIOCtl. The devices is opened, the I/O control call is made and the device is immediately closed again. #define INCL_WTKUTLIOCTRL #include PSZ pszName; /* Address of the ASCIIZ name of the device. */ ULONG ulOpenMode; /* The mode, in which the device has to be opened. */ ULONG ulCategory; /* Device category. */ ULONG ulFunction; /* Device-specific function code. */ PVOID pvParams; /* Address of the command-specific argument list. */ PULONG pcbParmLen; /* Pointer to the length of parameters. */ PVOID pvData; /* Address of the data area. */ PULONG pcbDataLen; /* Pointer to the length of data. */ APIRET ulrc; /* Return Code. */ ulrc = WtkDevIOCtl( pszName, ulOpenMode, ulCategory, ulFunction, pvParams, pcbParmLen, pvData, pcbDataLen); ═══ WtkDevIOCtl - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ name of the device. If the last character is a colon, the device is opened in block mode. ═══ WtkDevIOCtl - Parameter ulOpenMode ═══ ulOpenMode (ULONG) - input The mode, in which the device has to be opened. WTK_OPENDEVICE_SHARED opens the device in readonly and thus in shared mode WTK_OPENDEVICE_EXCLUSIVE opens the device in readwrite and thus in exlusive mode WTK_OPENDEVICE_NOCACHE bypasses the cache, if block devices are opened WTK_OPENDEVICE_BLOCKDEVICE explicitely states, that the specified device is a block device. Note: If the last character is a colon, the device is opened in block mode, even when WTK_OPENDEVICE_BLOCKDEVICE is not specified. ═══ WtkDevIOCtl - Parameter ulCategory ═══ ulCategory (ULONG) - input Device category. The valid range is 0 to 255. ═══ WtkDevIOCtl - Parameter ulFunction ═══ ulFunction (ULONG) - input Device-specific function code. The valid range is 0 to 255. ═══ WtkDevIOCtl - Parameter pvParams ═══ pvParams (PVOID) - input Address of the command-specific argument list. ═══ WtkDevIOCtl - Parameter pcbParmLen ═══ pcbParmLen (PULONG) - input/output Pointer to the length of parameters. Input Pointer to the length, in bytes, of the parameters passed in pParams by the application. Output Pointer to the length, in bytes, of the parameters returned. If this function returns ERROR_BUFFER_OVERFLOW, then pcbParmLen points to the size of the buffer required to hold the parameters returned. No other data is returned in this case. Note: Compared to DosDevIOCtl, this function is missing the parameter cbParmLenMax. On calling DosDevIOCtl this function sets cbParmLenMax to the value pointed to by pcbParmLen. If this is not applicable to your code, use DosDevIOCtl instead. ═══ WtkDevIOCtl - Parameter pvData ═══ pvData (PVOID) - input Address of the data area. ═══ WtkDevIOCtl - Parameter pcbDataLen ═══ pcbDataLen (PULONG) - input/output Pointer to the length of data. Input Pointer to the length, in bytes, of the data passed by the application in pData. Output Pointer to the length, in bytes, of the data returned. If this function returns ERROR_BUFFER_OVERFLOW, then pcbDataLen points to the size of the buffer required to hold the data returned. Note: Compared to DosDevIOCtl, this function is missing the parameter cbDataLenMax. On calling DosDevIOCtl this function sets cbDataLenMax to the value pointed to by pcbDataLen. If this is not applicable to your code, use DosDevIOCtl instead. ═══ WtkDevIOCtl - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ name of the device. If the last character is a colon, the device is opened in block mode. ulOpenMode (ULONG) - input The mode, in which the device has to be opened. WTK_OPENDEVICE_SHARED opens the device in readonly and thus in shared mode WTK_OPENDEVICE_EXCLUSIVE opens the device in readwrite and thus in exlusive mode WTK_OPENDEVICE_NOCACHE bypasses the cache, if block devices are opened WTK_OPENDEVICE_BLOCKDEVICE explicitely states, that the specified device is a block device. Note: If the last character is a colon, the device is opened in block mode, even when WTK_OPENDEVICE_BLOCKDEVICE is not specified. ulCategory (ULONG) - input Device category. The valid range is 0 to 255. ulFunction (ULONG) - input Device-specific function code. The valid range is 0 to 255. pvParams (PVOID) - input Address of the command-specific argument list. pcbParmLen (PULONG) - input/output Pointer to the length of parameters. Input Pointer to the length, in bytes, of the parameters passed in pParams by the application. Output Pointer to the length, in bytes, of the parameters returned. If this function returns ERROR_BUFFER_OVERFLOW, then pcbParmLen points to the size of the buffer required to hold the parameters returned. No other data is returned in this case. Note: Compared to DosDevIOCtl, this function is missing the parameter cbParmLenMax. On calling DosDevIOCtl this function sets cbParmLenMax to the value pointed to by pcbParmLen. If this is not applicable to your code, use DosDevIOCtl instead. pvData (PVOID) - input Address of the data area. pcbDataLen (PULONG) - input/output Pointer to the length of data. Input Pointer to the length, in bytes, of the data passed by the application in pData. Output Pointer to the length, in bytes, of the data returned. If this function returns ERROR_BUFFER_OVERFLOW, then pcbDataLen points to the size of the buffer required to hold the data returned. Note: Compared to DosDevIOCtl, this function is missing the parameter cbDataLenMax. On calling DosDevIOCtl this function sets cbDataLenMax to the value pointed to by pcbDataLen. If this is not applicable to your code, use DosDevIOCtl instead. ulrc (APIRET) - returns Return Code. WtkDevIOCtl returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosDevIOCtl ═══ WtkDevIOCtl Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkDevIOCtl returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosDevIOCtl ═══ WtkDevIOCtl - Remarks ═══ In order to simplify coding a littlebit, this function does not provide the parameters cbParmLenMax and cbDataLenMax, but instead implicitely sets them to the values pointed by the parameters pcbParmLen and pcbDataLen. This is done as in most cases this is sufficient. If this is not applicable to your code, use DosDevIOCtl instead. ═══ WtkDevIOCtl - Related functions ═══ Related Functions none ═══ 8.21. WtkDirExists ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkDirExists - Syntax ═══ This function checks, if a given directory exists. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ path name of the directory to be searched. */ BOOL fResult; /* Success indicator. */ fResult = WtkDirExists( pszName); ═══ WtkDirExists - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the directory to be searched. The path name may contain ?: for the drive in order to open the directory on the boot drive. The name may not include wildcards. ═══ WtkDirExists - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the directory to be searched. The path name may contain ?: for the drive in order to open the directory on the boot drive. The name may not include wildcards. fResult (BOOL) - returns Success indicator. TRUE Directory exists. FALSE Directory not found. ═══ WtkDirExists Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Directory exists. FALSE Directory not found. ═══ WtkDirExists - Remarks ═══ This function is identical to WtkIsDirectory. This function supports boot drive recognition. Specify ?: for the drive in order to open the directory on the boot drive. ═══ WtkDirExists - Related functions ═══ Related Functions none ═══ 8.22. WtkDumpClassSettingsTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkDumpClassSettingsTable - Syntax ═══ This function dumps a settings table to the console. #define INCL_WTKSETTINGS #include HSETTINGTABLE hst; /* Settingstable handle. */ BOOL fResult; /* Success indicator. */ fResult = WtkDumpClassSettingsTable( hst); ═══ WtkDumpClassSettingsTable - Parameter hst ═══ hst (HSETTINGTABLE) - input Settingstable handle. ═══ WtkDumpClassSettingsTable - Parameters ═══ hst (HSETTINGTABLE) - input Settingstable handle. fResult (BOOL) - returns Success indicator. TRUE Settingstable could be dumped. FALSE An error occurred. ═══ WtkDumpClassSettingsTable Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Settingstable could be dumped. FALSE An error occurred. ═══ WtkDumpClassSettingsTable - Remarks ═══ This function is for debug purposes only. It uses printf to display the current status of the class settingstable, so that you can catch the output by linking printf.obj of the PM Printf package to your WPS class while testing. ═══ WtkDumpClassSettingsTable - Related functions ═══ Related Functions none ═══ 8.23. WtkEvaluateObjectSettings ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkEvaluateObjectSettings - Syntax ═══ This function evaluates a settingsstring for a WPS class. This includes validation of the values and the update of both the object valuetable and object details, and, if desired, the update of controls of open settings notebook dialog being associated to certain settings (sub)values. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ PSZ pszSetup; /* Setup string from _wpSetup. */ BOOL fResult; /* Success indicator. */ fResult = WtkEvaluateObjectSettings( hvt, pszSetup); ═══ WtkEvaluateObjectSettings - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkEvaluateObjectSettings - Parameter pszSetup ═══ pszSetup (PSZ) - input Setup string from _wpSetup. ═══ WtkEvaluateObjectSettings - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. pszSetup (PSZ) - input Setup string from _wpSetup. fResult (BOOL) - returns Success indicator. TRUE String could be evaluated. FALSE An error occurred. ═══ WtkEvaluateObjectSettings Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE String could be evaluated. FALSE An error occurred. ═══ WtkEvaluateObjectSettings - Remarks ═══ This function is to be called during _wpSetup in order to handle the given setup string. Note: You still must pass pszSetup to the parent class, because WtkEvaluateObjectSettings will only handle the settings being implemented by your WPS class ! If a settings notebook of the object is open, and you asked the settings manager for automatic update of GUI controls, the appropriate GUI controls are automatically updated. ═══ WtkEvaluateObjectSettings - Related functions ═══ Related Functions none ═══ 8.24. WtkFDateTimeToTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkFDateTimeToTime - Syntax ═══ This function converts the contents of a FDATE and a FTIME stucture to a time value used by the compiler runtime. #define INCL_WTKUTLTIME #include PFDATE pfdate; /* Address of the FDATE structure. */ PFTIME pftime; /* Address of the FTIME structure. */ time_t *ptime; /* Address of the resulting time value. */ BOOL fResult; /* Success indicator. */ fResult = WtkFDateTimeToTime( pfdate, pftime, ptime); ═══ WtkFDateTimeToTime - Parameter pfdate ═══ pfdate (PFDATE) - input Address of the FDATE structure. ═══ WtkFDateTimeToTime - Parameter pftime ═══ pftime (PFTIME) - input Address of the FTIME structure. ═══ WtkFDateTimeToTime - Parameter ptime ═══ ptime (time_t*) - output Address of the resulting time value. ═══ WtkFDateTimeToTime - Parameters ═══ pfdate (PFDATE) - input Address of the FDATE structure. pftime (PFTIME) - input Address of the FTIME structure. ptime (time_t*) - output Address of the resulting time value. fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkFDateTimeToTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkFDateTimeToTime - Remarks ═══ This function does not check any of the values of the FDATE or FTIME structures before converting. ═══ WtkFDateTimeToTime - Related functions ═══ Related Functions none ═══ 8.25. WtkFileExists ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkFileExists - Syntax ═══ This function checks, if a given file exists. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ path name of the file to be searched. */ BOOL fResult; /* Success indicator. */ fResult = WtkFileExists( pszName); ═══ WtkFileExists - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file to be searched. The path name may contain ?: for the drive in order to open the file on the boot drive. The name may not include wildcards. In order to search with wildcards, use WtkFileMaskExists. ═══ WtkFileExists - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file to be searched. The path name may contain ?: for the drive in order to open the file on the boot drive. The name may not include wildcards. In order to search with wildcards, use WtkFileMaskExists. fResult (BOOL) - returns Success indicator. TRUE File exists. FALSE File not found. ═══ WtkFileExists Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE File exists. FALSE File not found. ═══ WtkFileExists - Remarks ═══ This function is identical to WtkIsFile. This function supports boot drive recognition. Specify ?: for the drive in order to open the file on the boot drive. ═══ WtkFileExists - Related functions ═══ Related Functions none ═══ 8.26. WtkFileMaskExists ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkFileMaskExists - Syntax ═══ This function checks, if a set of files exist, and returns the first file being found. #define INCL_WTKUTLFILE #include PSZ pszFileMask; /* Address of the ASCIIZ path name of the fileset to search. */ PSZ pszFirstFile; /* The address of a buffer in into which the name of the first file being found is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszFirstFile. */ BOOL fResult; /* Success indicator. */ fResult = WtkFileMaskExists( pszFileMask, pszFirstFile, ulBuflen); ═══ WtkFileMaskExists - Parameter pszFileMask ═══ pszFileMask (PSZ) - input Address of the ASCIIZ path name of the fileset to search. The path name may contain wildcard characters. The path name may contain ?: for the drive in order to search files on the boot drive. ═══ WtkFileMaskExists - Parameter pszFirstFile ═══ pszFirstFile (PSZ) - output The address of a buffer in into which the name of the first file being found is returned. ═══ WtkFileMaskExists - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszFirstFile. ═══ WtkFileMaskExists - Parameters ═══ pszFileMask (PSZ) - input Address of the ASCIIZ path name of the fileset to search. The path name may contain wildcard characters. The path name may contain ?: for the drive in order to search files on the boot drive. pszFirstFile (PSZ) - output The address of a buffer in into which the name of the first file being found is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszFirstFile. fResult (BOOL) - returns Success indicator. TRUE File(s) exist(s). FALSE File(s) not found. ═══ WtkFileMaskExists Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE File(s) exist(s). FALSE File(s) not found. ═══ WtkFileMaskExists - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to search the files on the boot drive. ═══ WtkFileMaskExists - Related functions ═══ Related Functions none ═══ 8.27. WtkFileModified ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkFileModified - Syntax ═══ This function detects modifications of a file or directory. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory, which is to be checked for modifications. */ PFILESTATUS3 pfs3; /* Address of a FILESTATUS3 structure previously being filled by DosQueryPathInfo or WtkFileModified for the same file. Every call to WtkFileModified will update that structure, if the file has modified. */ BOOL fResult; /* Modification indicator. */ fResult = WtkFileModified( pszName, pfs3); ═══ WtkFileModified - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory, which is to be checked for modifications. The path name may contain ?: for the drive in order to search the file or directory on the boot drive. ═══ WtkFileModified - Parameter pfs3 ═══ pfs3 (PFILESTATUS3) - input Address of a FILESTATUS3 structure previously being filled by DosQueryPathInfo or WtkFileModified for the same file. Every call to WtkFileModified will update that structure, if the file has modified. ═══ WtkFileModified - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory, which is to be checked for modifications. The path name may contain ?: for the drive in order to search the file or directory on the boot drive. pfs3 (PFILESTATUS3) - input Address of a FILESTATUS3 structure previously being filled by DosQueryPathInfo or WtkFileModified for the same file. Every call to WtkFileModified will update that structure, if the file has modified. fResult (BOOL) - returns Modification indicator. TRUE File has been modified FALSE  File has not been modified or could not be found  An invalid parameter has been specified. ═══ WtkFileModified Return Value - fResult ═══ fResult (BOOL) - returns Modification indicator. TRUE File has been modified FALSE  File has not been modified or could not be found  An invalid parameter has been specified. ═══ WtkFileModified - Remarks ═══ Before calling WtkFileModified, the caller must get the FIL_STANDARD information from DosQueryPathInfo for the file or directory in order to be able to determine, wether the file has been modified or not. Also the file status data may have been updated by a previous call to WtkFileModified. Note, that all modifications in the FILESTATUS3 structure are being monitored, thus also the date and time of last access and last read. This function supports boot drive recognition. Specify ?: for the drive in order to search the file or directory on the boot drive. ═══ WtkFileModified - Related functions ═══ Related Functions none ═══ 8.28. WtkFilespec ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkFilespec - Syntax ═══ This function searches for certain pathname components in a given pathname. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ filename, of which a part ist to be returned. */ ULONG ulPart; /* The type of information to be returned. */ PSZ pszResult; /* Pointer to the requested pathname component. */ pszResult = WtkFilespec( pszName, ulPart); ═══ WtkFilespec - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ filename, of which a part ist to be returned. ═══ WtkFilespec - Parameter ulPart ═══ ulPart (ULONG) - input The type of information to be returned. WTK_FILESPEC_PATHNAME returns a pointer to the begin of the path, not icluding a possibly specified drive WTK_FILESPEC_NAME returns a pointer to the filename WTK_FILESPEC_EXTENSION returns a pointer to the last file extension ═══ WtkFilespec - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ filename, of which a part ist to be returned. ulPart (ULONG) - input The type of information to be returned. WTK_FILESPEC_PATHNAME returns a pointer to the begin of the path, not icluding a possibly specified drive WTK_FILESPEC_NAME returns a pointer to the filename WTK_FILESPEC_EXTENSION returns a pointer to the last file extension pszResult (PSZ) - returns Pointer to the requested pathname component. If the requested component could not be found, NULL is returned. ═══ WtkFilespec Return Value - pszResult ═══ pszResult (PSZ) - returns Pointer to the requested pathname component. If the requested component could not be found, NULL is returned. ═══ WtkFilespec - Remarks ═══ WtkFilespec returns a pointer to a part fo the string, that is being passed with pszName. ═══ WtkFilespec - Related functions ═══ Related Functions none ═══ 8.29. WtkFindFirstEaValue ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkFindFirstEaValue - Syntax ═══ This function scans a extended attribute previously read by WtkReadEa for the first value of a given type. #define INCL_WTKEAS #include HEA hea; /* Handle to the extended attribute. */ PULONG pulEaType; /* The address of a variable containing the type of the searched/found extended attribute. */ PSZ pszValue; /* The address of a buffer in into which the found value is returned. */ PULONG pulBuflen; /* The address of a variable containing the length, in bytes, of the buffer described by pszValue. */ APIRET ulrc; /* Return Code. */ ulrc = WtkFindFirstEaValue( hea, pulEaType, pszValue, pulBuflen); ═══ WtkFindFirstEaValue - Parameter hea ═══ hea (HEA) - input Handle to the extended attribute. ═══ WtkFindFirstEaValue - Parameter pulEaType ═══ pulEaType (PULONG) - input/output The address of a variable containing the type of the searched/found extended attribute. All subsequent searches with WtkFindNextEaValue will use this type value. Specify WTK_EAT_ANY on input to search for values of any type. ═══ WtkFindFirstEaValue - Parameter pszValue ═══ pszValue (PSZ) - output The address of a buffer in into which the found value is returned. ═══ WtkFindFirstEaValue - Parameter pulBuflen ═══ pulBuflen (PULONG) - input/output The address of a variable containing the length, in bytes, of the buffer described by pszValue. On return, this variable contains the length of the returned value. ═══ WtkFindFirstEaValue - Parameters ═══ hea (HEA) - input Handle to the extended attribute. pulEaType (PULONG) - input/output The address of a variable containing the type of the searched/found extended attribute. All subsequent searches with WtkFindNextEaValue will use this type value. Specify WTK_EAT_ANY on input to search for values of any type. pszValue (PSZ) - output The address of a buffer in into which the found value is returned. pulBuflen (PULONG) - input/output The address of a variable containing the length, in bytes, of the buffer described by pszValue. On return, this variable contains the length of the returned value. ulrc (APIRET) - returns Return Code. WtkFindFirstEaValue returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE 18 ERROR_NO_MORE_FILES 111 ERROR_BUFFER_OVERFLOW ═══ WtkFindFirstEaValue Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkFindFirstEaValue returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE 18 ERROR_NO_MORE_FILES 111 ERROR_BUFFER_OVERFLOW ═══ WtkFindFirstEaValue - Remarks ═══ Unlike DosFindFirst, this API does not allocate resources, that must be freed. The resources for handling the value of the extended attribute are rather allocated by WtkReadEa, which must be freeed by calling WtkCloseEa, when not longer needed. You can start searches with WtkFindFirstEaValue on a given extended attribute as often, as you like. The search will then always just start at the first value again. ═══ WtkFindFirstEaValue - Related functions ═══ Related Functions none ═══ 8.30. WtkFindNextEaValue ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkFindNextEaValue - Syntax ═══ This function scans a extended attribute previously scanned by WtkFindFirstEaValue for the next value(s) of a given type. #define INCL_WTKEAS #include HEA hea; /* Handle to the extended attribute. */ PULONG pulEaType; /* The address of a variable containing the type of the found extended attribute. */ PSZ pszValue; /* The address of a buffer in into which the found value is returned. */ PULONG pulBuflen; /* The address of a variable containing the length, in bytes, of the buffer described by pszValue. */ APIRET ulrc; /* Return Code. */ ulrc = WtkFindNextEaValue( hea, pulEaType, pszValue, pulBuflen); ═══ WtkFindNextEaValue - Parameter hea ═══ hea (HEA) - input Handle to the extended attribute. ═══ WtkFindNextEaValue - Parameter pulEaType ═══ pulEaType (PULONG) - output The address of a variable containing the type of the found extended attribute. All searches with WtkFindNextEaValue use the type being specified with pulEaType on WtkFindFirstEaValue, ═══ WtkFindNextEaValue - Parameter pszValue ═══ pszValue (PSZ) - output The address of a buffer in into which the found value is returned. ═══ WtkFindNextEaValue - Parameter pulBuflen ═══ pulBuflen (PULONG) - input/output The address of a variable containing the length, in bytes, of the buffer described by pszValue. On return, this variable contains the length of the returned value. ═══ WtkFindNextEaValue - Parameters ═══ hea (HEA) - input Handle to the extended attribute. pulEaType (PULONG) - output The address of a variable containing the type of the found extended attribute. All searches with WtkFindNextEaValue use the type being specified with pulEaType on WtkFindFirstEaValue, pszValue (PSZ) - output The address of a buffer in into which the found value is returned. pulBuflen (PULONG) - input/output The address of a variable containing the length, in bytes, of the buffer described by pszValue. On return, this variable contains the length of the returned value. ulrc (APIRET) - returns Return Code. WtkFindNextEaValue returns one of the following return codes: 0 NO_ERROR 1 ERROR_INVALID_FUNCTION 6 ERROR_INVALID_HANDLE 18 ERROR_NO_MORE_FILES 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW ═══ WtkFindNextEaValue Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkFindNextEaValue returns one of the following return codes: 0 NO_ERROR 1 ERROR_INVALID_FUNCTION 6 ERROR_INVALID_HANDLE 18 ERROR_NO_MORE_FILES 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW ═══ WtkFindNextEaValue - Remarks ═══ If the extended attribute was not scanned with WtkFindFirstEaValue before using WtkFindNextEaValue, ERROR_INVALID_FUNCTION is returned. If no more value according to the type specified on WtkFindFirstEaValue can be found, ERROR_NO_MORE_FILES is returned. ═══ WtkFindNextEaValue - Related functions ═══ Related Functions none ═══ 8.31. WtkFreeMmf ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkFreeMmf - Syntax ═══ This function frees a dynamic memory buffer. #define INCL_WTKMMF #include HMMF hmmf; /* Handle to the MMF manager. */ PVOID pvData; /* Pointer to the allocated address space to be freed. */ APIRET ulrc; /* Return Code. */ ulrc = WtkFreeMmf( hmmf, pvData); ═══ WtkFreeMmf - Parameter hmmf ═══ hmmf (HMMF) - input Handle to the MMF manager. ═══ WtkFreeMmf - Parameter pvData ═══ pvData (PVOID) - input Pointer to the allocated address space to be freed. ═══ WtkFreeMmf - Parameters ═══ hmmf (HMMF) - input Handle to the MMF manager. pvData (PVOID) - input Pointer to the allocated address space to be freed. ulrc (APIRET) - returns Return Code. WtkFreeMmf returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosFreeMem ═══ WtkFreeMmf Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkFreeMmf returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosFreeMem ═══ WtkFreeMmf - Remarks ═══ Calling WtkFreeMmf will not save unsaved data. For that WtkFreeMmf. must be called. ═══ WtkFreeMmf - Related functions ═══ Related Functions none ═══ 8.32. WtkGetModuleHandle ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkGetModuleHandle - Syntax ═══ This function returns the handle of the module containing a given function. #define INCL_WTKUTLMODULE #include PFN pfn; /* Address of the function. */ HMODULE hmodule; /* Handle of the module containing the function or NULLHANDLE, if the handle could not be obtained. */ hmodule = WtkGetModuleHandle( pfn); ═══ WtkGetModuleHandle - Parameter pfn ═══ pfn (PFN) - input Address of the function. ═══ WtkGetModuleHandle - Parameters ═══ pfn (PFN) - input Address of the function. hmodule (HMODULE) - returns Handle of the module containing the function or NULLHANDLE, if the handle could not be obtained. ═══ WtkGetModuleHandle Return Value - hmodule ═══ hmodule (HMODULE) - returns Handle of the module containing the function or NULLHANDLE, if the handle could not be obtained. ═══ WtkGetModuleHandle - Remarks ═══ This function calls WtkGetModuleInfo in order to obtain the module handle. ═══ WtkGetModuleHandle - Related functions ═══ Related Functions none ═══ 8.33. WtkGetModuleInfo ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkGetModuleInfo - Syntax ═══ This function returns information about the module containing a given function. #define INCL_WTKUTLMODULE #include PFN pfn; /* Address of the function. */ PHMODULE phmod; /* Address of the module handle, or NULL, if this infortation is not required. */ PSZ pszBuffer; /* Address of a buffer, where the full qualified name of the module is being returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. */ APIRET ulrc; /* Return Code. */ ulrc = WtkGetModuleInfo( pfn, phmod, pszBuffer, ulBuflen); ═══ WtkGetModuleInfo - Parameter pfn ═══ pfn (PFN) - input Address of the function. ═══ WtkGetModuleInfo - Parameter phmod ═══ phmod (PHMODULE) - output Address of the module handle, or NULL, if this infortation is not required. ═══ WtkGetModuleInfo - Parameter pszBuffer ═══ pszBuffer (PSZ) - output Address of a buffer, where the full qualified name of the module is being returned. ═══ WtkGetModuleInfo - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ═══ WtkGetModuleInfo - Parameters ═══ pfn (PFN) - input Address of the function. phmod (PHMODULE) - output Address of the module handle, or NULL, if this infortation is not required. pszBuffer (PSZ) - output Address of a buffer, where the full qualified name of the module is being returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ulrc (APIRET) - returns Return Code. WtkGetModuleInfo returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryModuleName ═══ WtkGetModuleInfo Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkGetModuleInfo returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryModuleName ═══ WtkGetModuleInfo - Remarks ═══ WtkGetModuleInfo uses the undocumented function DosQueryModFromEIP: APIRET APIENTRY DosQueryModFromEIP (HMODULE *phModule, ULONG *pulObjectNumber, ULONG ulBufferLength, PCHAR pchBuffer, ULONG *pulOffset, PVOID pvAddress); ═══ WtkGetModuleInfo - Related functions ═══ Related Functions none ═══ 8.34. WtkGetNextDirectory ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkGetNextDirectory - Syntax ═══ This function provides a simple way to search directories with one API call instead of using DosFindFirst / DosFindNext / DosFindClose. #define INCL_WTKUTLFILE #include PSZ pszFileMask; /* Address of the ASCIIZ file mask of the files to be searched. */ PHDIR phdir; /* Address of the directory handle associated with this request. */ PSZ pszNextDirectory; /* The address of a buffer, into which the name of the recently found file is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszNextDirectory. */ APIRET ulrc; /* Return Code. */ ulrc = WtkGetNextDirectory( pszFileMask, phdir, pszNextDirectory, ulBuflen); ═══ WtkGetNextDirectory - Parameter pszFileMask ═══ pszFileMask (PSZ) - input Address of the ASCIIZ file mask of the files to be searched. ═══ WtkGetNextDirectory - Parameter phdir ═══ phdir (PHDIR) - input/output Address of the directory handle associated with this request. Before calling WtkGetNextDirectory for the first time to search a given file mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, the directory handle must not be modified. IMPORTANT:  The directory handle will be automatically closed, when WtkGetNextDirectory is being called, until it returns ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use DosFindClose to close the directory handle. ═══ WtkGetNextDirectory - Parameter pszNextDirectory ═══ pszNextDirectory (PSZ) - output The address of a buffer, into which the name of the recently found file is returned. ═══ WtkGetNextDirectory - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszNextDirectory. ═══ WtkGetNextDirectory - Parameters ═══ pszFileMask (PSZ) - input Address of the ASCIIZ file mask of the files to be searched. phdir (PHDIR) - input/output Address of the directory handle associated with this request. Before calling WtkGetNextDirectory for the first time to search a given file mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, the directory handle must not be modified. IMPORTANT:  The directory handle will be automatically closed, when WtkGetNextDirectory is being called, until it returns ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use DosFindClose to close the directory handle. pszNextDirectory (PSZ) - output The address of a buffer, into which the name of the recently found file is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszNextDirectory. ulrc (APIRET) - returns Return Code. WtkGetNextDirectory returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosFindFirst  DosFindNext ═══ WtkGetNextDirectory Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkGetNextDirectory returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosFindFirst  DosFindNext ═══ WtkGetNextDirectory - Remarks ═══ Before calling WtkGetNextDirectory for the first time to search a given file mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, the directory handle must not be modified. IMPORTANT:  The directory handle will be automatically closed, when WtkGetNextDirectory is being called, until it returns ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use DosFindClose to close the directory handle. ═══ WtkGetNextDirectory - Related functions ═══ Related Functions none ═══ 8.35. WtkGetNextEaValue ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkGetNextEaValue - Syntax ═══ This function reads the value of an extended attribute of a given file or directory. It provides the use of WtkReadEa / WtkFind*EaValue / WtkCloseEa in one API by calling it several times, until ERROR_NO_MORE_FILES is returned. #define INCL_WTKEAS #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory. */ PSZ pszEaName; /* Address of the ASCIIZ name of the extended attribute. */ PULONG pulEaType; /* The address of a variable containing the type of the searched/found extended attribute. */ PHEA phea; /* The address of a variable containing the handle to the extended attribute. */ PSZ pszValue; /* The address of a buffer in into which the found value is returned. */ PULONG pulBuflen; /* The address of a variable containing the length, in bytes, of the buffer described by pszValue. */ APIRET ulrc; /* Return Code. */ ulrc = WtkGetNextEaValue( pszName, pszEaName, pulEaType, phea, pszValue, pulBuflen); ═══ WtkGetNextEaValue - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. The name may not include wildcards. ═══ WtkGetNextEaValue - Parameter pszEaName ═══ pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. ═══ WtkGetNextEaValue - Parameter pulEaType ═══ pulEaType (PULONG) - input/output The address of a variable containing the type of the searched/found extended attribute. Specify WTK_EAT_ANY on input to search for values of any type. ═══ WtkGetNextEaValue - Parameter phea ═══ phea (PHEA) - input/output The address of a variable containing the handle to the extended attribute. On the first call to WtkGetNextEaValue, set this variable to HEA_CREATE. On return, *phea will contain the correct handle value for subsequent calls. ═══ WtkGetNextEaValue - Parameter pszValue ═══ pszValue (PSZ) - output The address of a buffer in into which the found value is returned. ═══ WtkGetNextEaValue - Parameter pulBuflen ═══ pulBuflen (PULONG) - input/output The address of a variable containing the length, in bytes, of the buffer described by pszValue. On return, this variable contains the length of the returned value. ═══ WtkGetNextEaValue - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. The name may not include wildcards. pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. pulEaType (PULONG) - input/output The address of a variable containing the type of the searched/found extended attribute. Specify WTK_EAT_ANY on input to search for values of any type. phea (PHEA) - input/output The address of a variable containing the handle to the extended attribute. On the first call to WtkGetNextEaValue, set this variable to HEA_CREATE. On return, *phea will contain the correct handle value for subsequent calls. pszValue (PSZ) - output The address of a buffer in into which the found value is returned. pulBuflen (PULONG) - input/output The address of a variable containing the length, in bytes, of the buffer described by pszValue. On return, this variable contains the length of the returned value. ulrc (APIRET) - returns Return Code. WtkGetNextEaValue returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 18 ERROR_NO_MORE_FILES 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkGetNextEaValue Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkGetNextEaValue returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 18 ERROR_NO_MORE_FILES 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkGetNextEaValue - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. This function is meant to provide you with easy handling of extended attributes. Instead of calling WtkReadEa / WtkFind*EaValue / WtkCloseEa, you can retrieve all values of an extended attribute by just calling WtkGetNextEaValue, until it returns ERROR_NO_MORE_FILES. This function allocates resources for handling the value of the given extended attribute by callig WtkReadEa. They must either be freed by  calling WtkGetNextEaValue, until it is returning ERROR_NO_MORE_FILES. This will call WtkCloseEa implicitely.  calling WtkClose ═══ WtkGetNextEaValue - Related functions ═══ Related Functions none ═══ 8.36. WtkGetNextFile ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkGetNextFile - Syntax ═══ This function provides a simple way to search files with one API call instead of using DosFindFirst / DosFindNext / DosFindClose. #define INCL_WTKUTLFILE #include PSZ pszFileMask; /* Address of the ASCIIZ file mask of the files to be searched. */ PHDIR phdir; /* Address of the directory handle associated with this request. */ PSZ pszNextFile; /* The address of a buffer, into which the name of the recently found file is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszNextFile. */ APIRET ulrc; /* Return Code. */ ulrc = WtkGetNextFile( pszFileMask, phdir, pszNextFile, ulBuflen); ═══ WtkGetNextFile - Parameter pszFileMask ═══ pszFileMask (PSZ) - input Address of the ASCIIZ file mask of the files to be searched. ═══ WtkGetNextFile - Parameter phdir ═══ phdir (PHDIR) - input/output Address of the directory handle associated with this request. Before calling WtkGetNextFile for the first time to search a given file mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, the directory handle must not be modified. IMPORTANT:  The directory handle will be automatically closed, when WtkGetNextFile is being called, until it returns ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use DosFindClose to close the directory handle. ═══ WtkGetNextFile - Parameter pszNextFile ═══ pszNextFile (PSZ) - output The address of a buffer, into which the name of the recently found file is returned. ═══ WtkGetNextFile - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszNextFile. ═══ WtkGetNextFile - Parameters ═══ pszFileMask (PSZ) - input Address of the ASCIIZ file mask of the files to be searched. phdir (PHDIR) - input/output Address of the directory handle associated with this request. Before calling WtkGetNextFile for the first time to search a given file mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, the directory handle must not be modified. IMPORTANT:  The directory handle will be automatically closed, when WtkGetNextFile is being called, until it returns ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use DosFindClose to close the directory handle. pszNextFile (PSZ) - output The address of a buffer, into which the name of the recently found file is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszNextFile. ulrc (APIRET) - returns Return Code. WtkGetNextFile returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosFindFirst  DosFindNext ═══ WtkGetNextFile Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkGetNextFile returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosFindFirst  DosFindNext ═══ WtkGetNextFile - Remarks ═══ Before calling WtkGetNextFile for the first time to search a given file mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, the directory handle must not be modified. IMPORTANT:  The directory handle will be automatically closed, when WtkGetNextFile is being called, until it returns ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use DosFindClose to close the directory handle. ═══ WtkGetNextFile - Related functions ═══ Related Functions none ═══ 8.37. WtkGetPackageFilename ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkGetPackageFilename - Syntax ═══ This function determines a fully qualified pathname for a given filename or file extension corresponding to the name of the module / application executable containing a given function. #define INCL_WTKUTLMODULE #include PFN pfn; /* Address of the function. */ PSZ pszSubdir; /* Address of the ASCIIZ subdirectory name. */ PSZ pszFilename; /* Address of the ASCIIZ file name. */ PSZ pszFileext; /* Address of the ASCIIZ file extension without leading dot. */ PSZ pszBuffer; /* Address of a buffer, where the full qualified filename is being returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. */ APIRET ulrc; /* Return Code. */ ulrc = WtkGetPackageFilename( pfn, pszSubdir, pszFilename, pszFileext, pszBuffer, ulBuflen); ═══ WtkGetPackageFilename - Parameter pfn ═══ pfn (PFN) - input Address of the function. ═══ WtkGetPackageFilename - Parameter pszSubdir ═══ pszSubdir (PSZ) - input Address of the ASCIIZ subdirectory name. If the required filename should point to a subdirectory, of where the executable resides, specify it here. Otherwise, leave this parameter NULL. ═══ WtkGetPackageFilename - Parameter pszFilename ═══ pszFilename (PSZ) - input Address of the ASCIIZ file name. If the filename should have a different name than the executable, specify it here. Otherwise, leave this parameter NULL. You can specify an extension either here or in pszFileExt. ═══ WtkGetPackageFilename - Parameter pszFileext ═══ pszFileext (PSZ) - input Address of the ASCIIZ file extension without leading dot. If the filename should have a different extension than the executable, specify it here. Otherwise, leave this parameter NULL. ═══ WtkGetPackageFilename - Parameter pszBuffer ═══ pszBuffer (PSZ) - output Address of a buffer, where the full qualified filename is being returned. ═══ WtkGetPackageFilename - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ═══ WtkGetPackageFilename - Parameters ═══ pfn (PFN) - input Address of the function. pszSubdir (PSZ) - input Address of the ASCIIZ subdirectory name. If the required filename should point to a subdirectory, of where the executable resides, specify it here. Otherwise, leave this parameter NULL. pszFilename (PSZ) - input Address of the ASCIIZ file name. If the filename should have a different name than the executable, specify it here. Otherwise, leave this parameter NULL. You can specify an extension either here or in pszFileExt. pszFileext (PSZ) - input Address of the ASCIIZ file extension without leading dot. If the filename should have a different extension than the executable, specify it here. Otherwise, leave this parameter NULL. pszBuffer (PSZ) - output Address of a buffer, where the full qualified filename is being returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ulrc (APIRET) - returns Return Code. WtkGetPackageFilename returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryModuleName ═══ WtkGetPackageFilename Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkGetPackageFilename returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryModuleName ═══ WtkGetPackageFilename - Remarks ═══ This function is mostly used to determine names of INI files etc. residing e.g. in the same directory as the executable or in a subdirectory, of where the executable resides. ═══ WtkGetPackageFilename - Related functions ═══ Related Functions none ═══ 8.38. WtkGetTextMessage ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkGetTextMessage - Syntax ═══ This function retrieves a message fro a text message file. It is quite similar to the DosGetMessage control program function, but with some important differences #define INCL_WTKTMF #include PCHAR *pTable; /* Pointer table. */ ULONG cTable; /* Number of variable insertion text strings. */ PBYTE pbBuffer; /* The address of the caller's buffer area where the system returns the requested message. */ ULONG cbBuffer; /* The length, in bytes, of the caller's buffer area. */ PSZ pszMessageName; /* Address of the ASCIIZ name of the message */ PSZ pszFile; /* Address of the ASCIIZ name of the text message file. */ PULONG pcbMsg; /* The address of a variable containing the length, in bytes, of the returned message. */ APIRET ulrc; /* Return Code. */ ulrc = WtkGetTextMessage( pTable, cTable, pbBuffer, cbBuffer, pszMessageName, pszFile, pcbMsg); ═══ WtkGetTextMessage - Parameter pTable ═══ pTable (PCHAR*) - input Pointer table. Each doubleword pointer points to an ASCIIZ string or a double-byte character-set (DBCS) string ending in nulls. A maximum of nine strings can be present. ═══ WtkGetTextMessage - Parameter cTable ═══ cTable (ULONG) - input Number of variable insertion text strings. Possible values range from 0 to 9. If cTable is 0, pTable is ignored ═══ WtkGetTextMessage - Parameter pbBuffer ═══ pbBuffer (PBYTE) - output The address of the caller's buffer area where the system returns the requested message. If the message is too long to fit in the caller's buffer, then as much of the message text as possible is returned, with the appropriate error return code. ═══ WtkGetTextMessage - Parameter cbBuffer ═══ cbBuffer (ULONG) - input The length, in bytes, of the caller's buffer area. ═══ WtkGetTextMessage - Parameter pszMessageName ═══ pszMessageName (PSZ) - input Address of the ASCIIZ name of the message ═══ WtkGetTextMessage - Parameter pszFile ═══ pszFile (PSZ) - input Address of the ASCIIZ name of the text message file. The path name may contain ?: for the drive in order to open the text message file on the boot drive. The name may not include wildcards. It is recommended, but not enforced to use filenames with the extension tmf to indicate that this is a text message file. ═══ WtkGetTextMessage - Parameter pcbMsg ═══ pcbMsg (PULONG) - output The address of a variable containing the length, in bytes, of the returned message. ═══ WtkGetTextMessage - Parameters ═══ pTable (PCHAR*) - input Pointer table. Each doubleword pointer points to an ASCIIZ string or a double-byte character-set (DBCS) string ending in nulls. A maximum of nine strings can be present. cTable (ULONG) - input Number of variable insertion text strings. Possible values range from 0 to 9. If cTable is 0, pTable is ignored pbBuffer (PBYTE) - output The address of the caller's buffer area where the system returns the requested message. If the message is too long to fit in the caller's buffer, then as much of the message text as possible is returned, with the appropriate error return code. cbBuffer (ULONG) - input The length, in bytes, of the caller's buffer area. pszMessageName (PSZ) - input Address of the ASCIIZ name of the message pszFile (PSZ) - input Address of the ASCIIZ name of the text message file. The path name may contain ?: for the drive in order to open the text message file on the boot drive. The name may not include wildcards. It is recommended, but not enforced to use filenames with the extension tmf to indicate that this is a text message file. pcbMsg (PULONG) - output The address of a variable containing the length, in bytes, of the returned message. ulrc (APIRET) - returns Return Code. WtkGetTextMessage returns one of the following return codes: 0 NO_ERROR 5 ERROR_ACCESS_DENIED 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSearchPath  DosOpen  DosQueryPathInfo ═══ WtkGetTextMessage Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkGetTextMessage returns one of the following return codes: 0 NO_ERROR 5 ERROR_ACCESS_DENIED 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSearchPath  DosOpen  DosQueryPathInfo ═══ WtkGetTextMessage - Remarks ═══ The WtkGetTextMessage is different to DosGetMessage in the following concerns:  the message is not taken from a compiled OS/2 message file, but from an editable text file.  a zero byte is appended to the message returned, so that it can be used right away with standard C/C++ APIs  placeholders from %1 to %1 in the message text are replaced if values for those are handed over to WtkGetTextMessage in the pointer table referred to by the pTable parameter. In opposite to the DosGetMessage call text replacement is performed even if not enough parameters are supplied - where values are missing, the placeholder remains unmodified within the message text. ═══ WtkGetTextMessage - Related functions ═══ Related Functions none ═══ 8.39. WtkInitializeMmf ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkInitializeMmf - Syntax ═══ This function initializes MMF support for the current thread. #define INCL_WTKMMF #include PHMMF phmmf; /* The address of a variable containing the handle to the MMF manager. */ ULONG ulMaxBuffer; /* Number of memory mapped files to support for this thread. */ APIRET ulrc; /* Return Code. */ ulrc = WtkInitializeMmf( phmmf, ulMaxBuffer); ═══ WtkInitializeMmf - Parameter phmmf ═══ phmmf (PHMMF) - output The address of a variable containing the handle to the MMF manager. ═══ WtkInitializeMmf - Parameter ulMaxBuffer ═══ ulMaxBuffer (ULONG) - input Number of memory mapped files to support for this thread. ═══ WtkInitializeMmf - Parameters ═══ phmmf (PHMMF) - output The address of a variable containing the handle to the MMF manager. ulMaxBuffer (ULONG) - input Number of memory mapped files to support for this thread. ulrc (APIRET) - returns Return Code. WtkInitializeMmf returns one of the following return codes: 0 NO_ERROR 5 ERROR_ACCESS_DENIED 87 ERROR_INVALID_PARAMETER ═══ WtkInitializeMmf Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkInitializeMmf returns one of the following return codes: 0 NO_ERROR 5 ERROR_ACCESS_DENIED 87 ERROR_INVALID_PARAMETER ═══ WtkInitializeMmf - Remarks ═══ This function registers the MMF exception handler for to support memory mapped files. When leaving the function that called WtkInitializeMmf, WtkTerminateMmf must be called to deregister the exception handler again, especially if other exception handler are used beside the one for MMF support. Otherwise unpredictable results (most often simply protection violations may occurr). ═══ WtkInitializeMmf - Related functions ═══ Related Functions none ═══ 8.40. WtkInitializeNumSpinbuttonArray ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkInitializeNumSpinbuttonArray - Syntax ═══ This function initializes a spinbutton, which is to hold a range of numeric values with steps in between. #define INCL_WTKUTLCONTROL #include HWND hwndSpinbutton; /* Handle of the spinbutton window. */ ULONG ulMinValue; /* The minimum value of the spinbutton. */ ULONG ulMaxValue; /* The maximum value of the spinbutton. */ ULONG ulStep; /* The step between the values in the range. */ BOOL fResult; /* Success indicator. */ fResult = WtkInitializeNumSpinbuttonArray( hwndSpinbutton, ulMinValue, ulMaxValue, ulStep); ═══ WtkInitializeNumSpinbuttonArray - Parameter hwndSpinbutton ═══ hwndSpinbutton (HWND) - input Handle of the spinbutton window. ═══ WtkInitializeNumSpinbuttonArray - Parameter ulMinValue ═══ ulMinValue (ULONG) - input The minimum value of the spinbutton. ═══ WtkInitializeNumSpinbuttonArray - Parameter ulMaxValue ═══ ulMaxValue (ULONG) - input The maximum value of the spinbutton. ═══ WtkInitializeNumSpinbuttonArray - Parameter ulStep ═══ ulStep (ULONG) - input The step between the values in the range. ═══ WtkInitializeNumSpinbuttonArray - Parameters ═══ hwndSpinbutton (HWND) - input Handle of the spinbutton window. ulMinValue (ULONG) - input The minimum value of the spinbutton. ulMaxValue (ULONG) - input The maximum value of the spinbutton. ulStep (ULONG) - input The step between the values in the range. fResult (BOOL) - returns Success indicator. TRUE Successful. FALSE Not successful. Extended error information can be obtained using WinGetLastError/WinGetErrorInfo. ═══ WtkInitializeNumSpinbuttonArray Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Successful. FALSE Not successful. Extended error information can be obtained using WinGetLastError/WinGetErrorInfo. ═══ WtkInitializeNumSpinbuttonArray - Remarks ═══ Unfortunately the OS/2 Presentation Manager provides numeric spinbuttons does not provide a parameter for steps in a numeric range, when setting up a spinbutton with numeric values. This forces you to either  to have a spinbutton, which gives access to all the values between the minimum and maximum value, resulting in a very ineffective control when using large ranges  to setup a temporary array of strings for initializing the spinbutton, resulting in a numeric spinbutton having only as much as elements between the minimum and maximum value, as useful. WtkInitializeNumSpinbuttonArray aids you in the latter case. Use also WtkQueryNumSpinbuttonIndex for an easy conversion from a numeric value of a such initialized numeric spinbutton to an array index. You will need this one to set the spinbutton to a desired value. ═══ WtkInitializeNumSpinbuttonArray - Related functions ═══ Related Functions none ═══ 8.41. WtkIsDirectory ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkIsDirectory - Syntax ═══ This function checks, if a given name is the name of a directory. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ path name of the directory to be searched. */ BOOL fResult; /* Success indicator. */ fResult = WtkIsDirectory( pszName); ═══ WtkIsDirectory - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the directory to be searched. The path name may contain ?: for the drive in order to search the directory on the boot drive. The name may not include wildcards. ═══ WtkIsDirectory - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the directory to be searched. The path name may contain ?: for the drive in order to search the directory on the boot drive. The name may not include wildcards. fResult (BOOL) - returns Success indicator. TRUE Given name is an existing directory. FALSE Directory not found or given name is not a directory. ═══ WtkIsDirectory Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Given name is an existing directory. FALSE Directory not found or given name is not a directory. ═══ WtkIsDirectory - Remarks ═══ This function is identical to WtkDirExists. This function supports boot drive recognition. Specify ?: for the drive in order to search the directory on the boot drive. ═══ WtkIsDirectory - Related functions ═══ Related Functions none ═══ 8.42. WtkIsFile ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkIsFile - Syntax ═══ This function checks, if a given name is the name of a file. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ path name of the file to be searched. */ BOOL fResult; /* Success indicator. */ fResult = WtkIsFile( pszName); ═══ WtkIsFile - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file to be searched. The path name may contain ?: for the drive in order to search the file on the boot drive. The name may not include wildcards. In order to search with wildcards, use WtkFileMaskExists. ═══ WtkIsFile - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file to be searched. The path name may contain ?: for the drive in order to search the file on the boot drive. The name may not include wildcards. In order to search with wildcards, use WtkFileMaskExists. fResult (BOOL) - returns Success indicator. TRUE Given name is an existing file. FALSE File not found or given name is not a file. ═══ WtkIsFile Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Given name is an existing file. FALSE File not found or given name is not a file. ═══ WtkIsFile - Remarks ═══ This function is identical to WtkFileExists. This function supports boot drive recognition. Specify ?: for the drive in order to search the file on the boot drive. ═══ WtkIsFile - Related functions ═══ Related Functions none ═══ 8.43. WtkIsOfPublicPmClass ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkIsOfPublicPmClass - Syntax ═══ This function determines wether a given window is of a specific PM class and has the given primary style, thus is a specific kind of this class. #define INCL_WTKUTLCONTROL #include HWND hwnd; /* Handle of the window to be examined. */ PSZ pszClassIndex; /* Class index (like WC_*) */ ULONG ulPrimaryWindowStyle; /* Primary window style. */ BOOL fResult; /* Class member indicator. */ fResult = WtkIsOfPublicPmClass( hwnd, pszClassIndex, ulPrimaryWindowStyle); ═══ WtkIsOfPublicPmClass - Parameter hwnd ═══ hwnd (HWND) - input Handle of the window to be examined. ═══ WtkIsOfPublicPmClass - Parameter pszClassIndex ═══ pszClassIndex (PSZ) - input Class index (like WC_*) This value specifies, of what public PM class the window should be. Some possible values are:  WC_FRAME  WC_COMBOBOX  WC_BUTTON  WC_MENU  WC_STATIC  WC_ENTRYFIELD  WC_LISTBOX  WC_SCROLLBAR  WC_TITLEBAR These classes return "#n" as the PM class name, where n is a number. This is a requirement for WtkIsOfPublicPmClass to identify a PM Class as public. Your application may register PM classes compliant to that name scheme with a high number, so that this function can be used anyway. ═══ WtkIsOfPublicPmClass - Parameter ulPrimaryWindowStyle ═══ ulPrimaryWindowStyle (ULONG) - input Primary window style. This style is specified to further specify, what characteristic the PM class of the examined window should have. If that further specification is not required, leave this parameter zero. Before examining the window style of the given window, it is first masked with BS_PRIMARYSTYLES (0x000fL). Here are some examples of window styles, that make sense in conjunction with their respective public PM class: public PM class primary window styles WC_BUTTON BS_PUSHBUTTON, BS_CHECKBOX, BS_AUTOCHECKBOX, BS_RADIOBUTTON, BS_AUTORADIOBUTTON, BS_3STATE, BS_3STATE WC_STATIC SS_TEXT, SS_GROUPBOX, SS_ICON, SS_BITMAP, SS_HALFTONERECT, SS_BKGNDRECT, SS_FGNDFRAME, SS_BKGNDFRAME, SS_SYSICON ═══ WtkIsOfPublicPmClass - Parameters ═══ hwnd (HWND) - input Handle of the window to be examined. pszClassIndex (PSZ) - input Class index (like WC_*) This value specifies, of what public PM class the window should be. Some possible values are:  WC_FRAME  WC_COMBOBOX  WC_BUTTON  WC_MENU  WC_STATIC  WC_ENTRYFIELD  WC_LISTBOX  WC_SCROLLBAR  WC_TITLEBAR These classes return "#n" as the PM class name, where n is a number. This is a requirement for WtkIsOfPublicPmClass to identify a PM Class as public. Your application may register PM classes compliant to that name scheme with a high number, so that this function can be used anyway. ulPrimaryWindowStyle (ULONG) - input Primary window style. This style is specified to further specify, what characteristic the PM class of the examined window should have. If that further specification is not required, leave this parameter zero. Before examining the window style of the given window, it is first masked with BS_PRIMARYSTYLES (0x000fL). Here are some examples of window styles, that make sense in conjunction with their respective public PM class: public PM class primary window styles WC_BUTTON BS_PUSHBUTTON, BS_CHECKBOX, BS_AUTOCHECKBOX, BS_RADIOBUTTON, BS_AUTORADIOBUTTON, BS_3STATE, BS_3STATE WC_STATIC SS_TEXT, SS_GROUPBOX, SS_ICON, SS_BITMAP, SS_HALFTONERECT, SS_BKGNDRECT, SS_FGNDFRAME, SS_BKGNDFRAME, SS_SYSICON fResult (BOOL) - returns Class member indicator. TRUE the class is of the given class and has the given primary window style. FALSE the class is not of the given class or does not have the given primary window style. Extended error information can be obtained using WinGetLastError/WinGetErrorInfo. ═══ WtkIsOfPublicPmClass Return Value - fResult ═══ fResult (BOOL) - returns Class member indicator. TRUE the class is of the given class and has the given primary window style. FALSE the class is not of the given class or does not have the given primary window style. Extended error information can be obtained using WinGetLastError/WinGetErrorInfo. ═══ WtkIsOfPublicPmClass - Remarks ═══ Ths function can only handle windows of classes, that are public PM classes, that is, classes, that return "#n" as the PM class, where n is a number. Your application may register private PM classes compliant to that name scheme with an unused number, so that this function can be used anyway. ═══ WtkIsOfPublicPmClass - Related functions ═══ Related Functions none ═══ 8.44. WtkIsWarp4 ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkIsWarp4 - Syntax ═══ This function tests, if the calling program is running under WARP 4 or greater. #define INCL_WTKUTLSYSTEM #include BOOL fResult; /* OS/2 WARP 4 indicator. */ fResult = WtkIsWarp4(); ═══ WtkIsWarp4 - Parameters ═══ fResult (BOOL) - returns OS/2 WARP 4 indicator. TRUE Program is running under OS/2 WARP 4 or greater. FALSE Program is running under OS/2 below WARP 4 ═══ WtkIsWarp4 Return Value - fResult ═══ fResult (BOOL) - returns OS/2 WARP 4 indicator. TRUE Program is running under OS/2 WARP 4 or greater. FALSE Program is running under OS/2 below WARP 4 ═══ WtkIsWarp4 - Remarks ═══ This function is mostly needed to distinct between OS/2 WARP 3 and WARP 4 because of the differences in  the layout of settings notebook pages of WPS objects, especially the notebook buttons. See also WtkRelocateNotebookpageControls  font names and sizes being used in dialogs ═══ WtkIsWarp4 - Related functions ═══ Related Functions none ═══ 8.45. WtkOpenDevice ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkOpenDevice - Syntax ═══ This function opens a device. #define INCL_WTKUTLIOCTRL #include PSZ pszName; /* Address of the ASCIIZ name of the device. */ PHFILE phdevice; /* The address of a variable where the handle of the opened device is returned. */ ULONG ulOpenMode; /* The mode, in which the device has to be opened. */ APIRET ulrc; /* Return Code. */ ulrc = WtkOpenDevice( pszName, phdevice, ulOpenMode); ═══ WtkOpenDevice - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ name of the device. If the last character is a colon, the device is opened in block mode. ═══ WtkOpenDevice - Parameter phdevice ═══ phdevice (PHFILE) - output The address of a variable where the handle of the opened device is returned. ═══ WtkOpenDevice - Parameter ulOpenMode ═══ ulOpenMode (ULONG) - input The mode, in which the device has to be opened. WTK_OPENDEVICE_SHARED opens the device in readonly and thus in shared mode WTK_OPENDEVICE_EXCLUSIVE opens the device in readwrite and thus in exlusive mode (overrides WTK_OPENDEVICE_SHARED) WTK_OPENDEVICE_NOCACHE bypasses the cache, if block devices are opened WTK_OPENDEVICE_BLOCKDEVICE explicitely states, that the specified device is a block device. Note: If the last character is a colon, the device is opened in block mode, even if WTK_OPENDEVICE_BLOCKDEVICE is not specified. ═══ WtkOpenDevice - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ name of the device. If the last character is a colon, the device is opened in block mode. phdevice (PHFILE) - output The address of a variable where the handle of the opened device is returned. ulOpenMode (ULONG) - input The mode, in which the device has to be opened. WTK_OPENDEVICE_SHARED opens the device in readonly and thus in shared mode WTK_OPENDEVICE_EXCLUSIVE opens the device in readwrite and thus in exlusive mode (overrides WTK_OPENDEVICE_SHARED) WTK_OPENDEVICE_NOCACHE bypasses the cache, if block devices are opened WTK_OPENDEVICE_BLOCKDEVICE explicitely states, that the specified device is a block device. Note: If the last character is a colon, the device is opened in block mode, even if WTK_OPENDEVICE_BLOCKDEVICE is not specified. ulrc (APIRET) - returns Return Code. WtkOpenDevice returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosOpen ═══ WtkOpenDevice Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkOpenDevice returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosOpen ═══ WtkOpenDevice - Remarks ═══ A device opened with WtkOpenDevice must be closed by a call to DosClose. If the last character specified with pszName is a colon, the device is opened in block mode, even when WTK_OPENDEVICE_BLOCKDEVICE is not specified within ulOpenMode. ═══ WtkOpenDevice - Related functions ═══ Related Functions none ═══ 8.46. WtkPutEaValue ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkPutEaValue - Syntax ═══ This function appends a value to an extended attribute directly on disk. #define INCL_WTKEAS #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory. */ PSZ pszEaName; /* Address of the ASCIIZ name of the extended attribute. */ ULONG ulMultiType; /* Multitype of the value to be added to the extended attribute. */ ULONG ulEaType; /* Type of the value to be added to the extended attribute. */ PBYTE pbValue; /* The address of a buffer of the value to be written. */ ULONG ulValuelen; /* The length, in bytes, of the buffer described by pbValue. */ BOOL fWriteThru; /* A flag to bypass the cache and write the extended attribute directly to disk. */ BYTE fEA; /* The flags to be set for this extended attribute flags. */ APIRET ulrc; /* Return Code. */ ulrc = WtkPutEaValue( pszName, pszEaName, ulMultiType, ulEaType, pbValue, ulValuelen, fWriteThru, fEA); ═══ WtkPutEaValue - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to search the file or directory on the boot drive. The name may not include wildcards. ═══ WtkPutEaValue - Parameter pszEaName ═══ pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. ═══ WtkPutEaValue - Parameter ulMultiType ═══ ulMultiType (ULONG) - input Multitype of the value to be added to the extended attribute. Specify EAT_MVST to add a value to a multi value, single type extended attribute. This only works, if this is the first value being appended or the existing extended attribute is already multi value, single type, and ulEaType is of the same type as the existing value(s). EAT_MVMT to add a value to a multi value, multi type extended attribute. This only works, if this is the first value being appended or the existing extended attribute is already multi value, multi type. Other EAT_* to add a value to a single value, single type extended attribute This only works, if this is the first value being appended, otherwise it would not be single value, single type ... ═══ WtkPutEaValue - Parameter ulEaType ═══ ulEaType (ULONG) - input Type of the value to be added to the extended attribute. Specify EAT_ASCII to add a string value EAT_BINARY to add a binary value EAT_ICON to add an icon EAT_BITMAP to add a bitmap EAT_METAFILE to add a meta file EAT_EA to add the name of an embedded extended attribute as an ASCII string ═══ WtkPutEaValue - Parameter pbValue ═══ pbValue (PBYTE) - input The address of a buffer of the value to be written. ═══ WtkPutEaValue - Parameter ulValuelen ═══ ulValuelen (ULONG) - input The length, in bytes, of the buffer described by pbValue. ═══ WtkPutEaValue - Parameter fWriteThru ═══ fWriteThru (BOOL) - input A flag to bypass the cache and write the extended attribute directly to disk. ═══ WtkPutEaValue - Parameter fEA ═══ fEA (BYTE) - input The flags to be set for this extended attribute flags. Specify FEA_NEEDEDEA in order to mark the extended attribute as critical. Otherwise set this parameter to zero. ═══ WtkPutEaValue - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to search the file or directory on the boot drive. The name may not include wildcards. pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. ulMultiType (ULONG) - input Multitype of the value to be added to the extended attribute. Specify EAT_MVST to add a value to a multi value, single type extended attribute. This only works, if this is the first value being appended or the existing extended attribute is already multi value, single type, and ulEaType is of the same type as the existing value(s). EAT_MVMT to add a value to a multi value, multi type extended attribute. This only works, if this is the first value being appended or the existing extended attribute is already multi value, multi type. Other EAT_* to add a value to a single value, single type extended attribute This only works, if this is the first value being appended, otherwise it would not be single value, single type ... ulEaType (ULONG) - input Type of the value to be added to the extended attribute. Specify EAT_ASCII to add a string value EAT_BINARY to add a binary value EAT_ICON to add an icon EAT_BITMAP to add a bitmap EAT_METAFILE to add a meta file EAT_EA to add the name of an embedded extended attribute as an ASCII string pbValue (PBYTE) - input The address of a buffer of the value to be written. ulValuelen (ULONG) - input The length, in bytes, of the buffer described by pbValue. fWriteThru (BOOL) - input A flag to bypass the cache and write the extended attribute directly to disk. fEA (BYTE) - input The flags to be set for this extended attribute flags. Specify FEA_NEEDEDEA in order to mark the extended attribute as critical. Otherwise set this parameter to zero. ulrc (APIRET) - returns Return Code. WtkPutEaValue returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 13 ERROR_INVALID_DATA 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSetPathInfo ═══ WtkPutEaValue Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkPutEaValue returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 13 ERROR_INVALID_DATA 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSetPathInfo ═══ WtkPutEaValue - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. This function is meant to provide you with easy handling of extended attributes. Instead of calling WtkCreateEa / WtkReadEa / WtkAppendEaValue / WtkSaveEa / WtkCloseEa, you can directly append a value to an extended attribute by just calling WtkPutEaValue. The drawback is, that if you are required to append several values, each call needs to read the existing values for the given extended attribute again from disk in order to he list of values. This is not that important, if you do not query a lot of extended attributes of a lot of files at one time, as extended attributes can of course be cached, provided that you did not set fWriteThru to TRUE. In that case, from the second call of WtkPutEaValue this is most likely a in-memory operation. Nevertheless, if you handle very large lists of values for a given extended attribute, or you want to bypass the cache, it is faster to use the WtkCreateEa / WtkReadEa / WtkAppendEaValue / WtkSaveEa / WtkCloseEa functions and thus write to the disk only once. ═══ WtkPutEaValue - Related functions ═══ Related Functions none ═══ 8.47. WtkQueryBootDrive ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryBootDrive - Syntax ═══ This function returns the ASCII value of the drive, where the operating system was started from. #define INCL_WTKUTLSYSTEM #include CHAR chResult; /* ASCII value of the letter from the drive, where the operating system was started from. */ chResult = WtkQueryBootDrive(); ═══ WtkQueryBootDrive - Parameters ═══ chResult (CHAR) - returns ASCII value of the letter from the drive, where the operating system was started from. ═══ WtkQueryBootDrive Return Value - chResult ═══ chResult (CHAR) - returns ASCII value of the letter from the drive, where the operating system was started from. ═══ WtkQueryBootDrive - Remarks ═══ This function is intended as an easier way to query the boot drive compared to the conventiuonal method using DosQuerySysValue Using WtkQueryBootDrive instead allows to embedd the query for a boot drive in another function call, like for example: sprintf( szSyslevelFilename, "?:\\OS2\\SYSTEM\\SYSLEVEL.OS2", WtkQueryBootDrive()); Note however that when using file related functions of the Workplace Shell Toolkit this is not required, as all of these allow to specify ?: as a placeholder for the boot drive within file- and/or pathname specifications. ═══ WtkQueryBootDrive - Related functions ═══ Related Functions none ═══ 8.48. WtkQueryCDateTimeStamp ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryCDateTimeStamp - Syntax ═══ This function determines a timestamp according to the values of a CDATE and CTIME structure. #define INCL_WTKUTLTIME #include PCDATE pcdate; /* Address of the CDATE structure. */ PCTIME pctime; /* Address of the CTIME structure. */ ULONG ulStampType; /* Type of timestamp. */ PSZ pszBuffer; /* The address of a buffer, into which the timestamp is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryCDateTimeStamp( pcdate, pctime, ulStampType, pszBuffer, ulBuflen); ═══ WtkQueryCDateTimeStamp - Parameter pcdate ═══ pcdate (PCDATE) - input Address of the CDATE structure. ═══ WtkQueryCDateTimeStamp - Parameter pctime ═══ pctime (PCTIME) - input Address of the CTIME structure. ═══ WtkQueryCDateTimeStamp - Parameter ulStampType ═══ ulStampType (ULONG) - input Type of timestamp. WTK_TIMESTAMP_SORTEDDATETIME returns a sorted date and timestamp in yyyymmddhhmmss WTK_TIMESTAMP_SORTEDDATE returns a sorted datestamp in yyyymmdd WTK_TIMESTAMP_SORTEDTIME returns a sorted timestamp in hhmmss WTK_TIMESTAMP_NLSDATETIME returns a NLS compliant date and timestamp WTK_TIMESTAMP_NLSDATE returns a NLS compliant datestamp WTK_TIMESTAMP_NLSTIME returns a NLS compliant timestamp ═══ WtkQueryCDateTimeStamp - Parameter pszBuffer ═══ pszBuffer (PSZ) - output The address of a buffer, into which the timestamp is returned. ═══ WtkQueryCDateTimeStamp - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. ═══ WtkQueryCDateTimeStamp - Parameters ═══ pcdate (PCDATE) - input Address of the CDATE structure. pctime (PCTIME) - input Address of the CTIME structure. ulStampType (ULONG) - input Type of timestamp. WTK_TIMESTAMP_SORTEDDATETIME returns a sorted date and timestamp in yyyymmddhhmmss WTK_TIMESTAMP_SORTEDDATE returns a sorted datestamp in yyyymmdd WTK_TIMESTAMP_SORTEDTIME returns a sorted timestamp in hhmmss WTK_TIMESTAMP_NLSDATETIME returns a NLS compliant date and timestamp WTK_TIMESTAMP_NLSDATE returns a NLS compliant datestamp WTK_TIMESTAMP_NLSTIME returns a NLS compliant timestamp pszBuffer (PSZ) - output The address of a buffer, into which the timestamp is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. ulrc (APIRET) - returns Return Code. WtkQueryCDateTimeStamp returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryCtryInfo ═══ WtkQueryCDateTimeStamp Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryCDateTimeStamp returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryCtryInfo ═══ WtkQueryCDateTimeStamp - Remarks ═══ none ═══ WtkQueryCDateTimeStamp - Related functions ═══ Related Functions none ═══ 8.49. WtkQueryClassDetailsInfo ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryClassDetailsInfo - Syntax ═══ This function is to be called by the override of the method _wpclsQueryDetailsInfo. #define INCL_WTKSETTINGS #include HSETTINGTABLE hst; /* Settingstable handle. */ PVOID *ppClassFieldInfo; /* Adress of the pointer variable to the details info. */ PULONG pSize; /* Adress of the size variable of details data. */ ULONG ulParentColumns; /* Number of parent columns being already inserted by the parent class. */ ULONG ulResult; /* Number of total columns including the own ones. */ ulResult = WtkQueryClassDetailsInfo( hst, ppClassFieldInfo, pSize, ulParentColumns); ═══ WtkQueryClassDetailsInfo - Parameter hst ═══ hst (HSETTINGTABLE) - input Settingstable handle. ═══ WtkQueryClassDetailsInfo - Parameter ppClassFieldInfo ═══ ppClassFieldInfo (PVOID*) - input Adress of the pointer variable to the details info. ═══ WtkQueryClassDetailsInfo - Parameter pSize ═══ pSize (PULONG) - input Adress of the size variable of details data. ═══ WtkQueryClassDetailsInfo - Parameter ulParentColumns ═══ ulParentColumns (ULONG) - input Number of parent columns being already inserted by the parent class. ═══ WtkQueryClassDetailsInfo - Parameters ═══ hst (HSETTINGTABLE) - input Settingstable handle. ppClassFieldInfo (PVOID*) - input Adress of the pointer variable to the details info. pSize (PULONG) - input Adress of the size variable of details data. ulParentColumns (ULONG) - input Number of parent columns being already inserted by the parent class. ulResult (ULONG) - returns Number of total columns including the own ones. ═══ WtkQueryClassDetailsInfo Return Value - ulResult ═══ ulResult (ULONG) - returns Number of total columns including the own ones. ═══ WtkQueryClassDetailsInfo - Remarks ═══ This function can be called as follows during _wpclsQueryDetailsInfo to automatically setup the details info: return WtkQueryClassDetailsInfo( _hst, (PVOID) ppClassFieldInfo, pSize, M__parent_M__wpclsQueryDetailsInfo( somSelf, ppClassFieldInfo, pSize)); ═══ WtkQueryClassDetailsInfo - Related functions ═══ Related Functions none ═══ 8.50. WtkQueryClassIndex ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryClassIndex - Syntax ═══ This function determines the class index (like WC_*) for public PM classes. #define INCL_WTKUTLCONTROL #include HWND hwnd; /* Handle of the window to be examined. */ PSZ pszResult; /* Class index (like WC_*). */ pszResult = WtkQueryClassIndex( hwnd); ═══ WtkQueryClassIndex - Parameter hwnd ═══ hwnd (HWND) - input Handle of the window to be examined. ═══ WtkQueryClassIndex - Parameters ═══ hwnd (HWND) - input Handle of the window to be examined. pszResult (PSZ) - returns Class index (like WC_*). NULLHANDLE the class index could not be obtained or the class is not a public PM class. other class index (like WC_*) Extended error information can be obtained using WinGetLastError/WinGetErrorInfo. ═══ WtkQueryClassIndex Return Value - pszResult ═══ pszResult (PSZ) - returns Class index (like WC_*). NULLHANDLE the class index could not be obtained or the class is not a public PM class. other class index (like WC_*) Extended error information can be obtained using WinGetLastError/WinGetErrorInfo. ═══ WtkQueryClassIndex - Remarks ═══ The class index can only be queried for public PM classes, that is, classes, that return "#n" as the PM class name, where n is a number. Your application may register private PM classes compliant to that name scheme with an unused number, so that this function can be used anyway. In order to use the resulting PSZ value in a switch statement, precede both the switch variable and the case values with (const). ═══ WtkQueryClassIndex - Related functions ═══ Related Functions none ═══ 8.51. WtkQueryCurrentDir ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryCurrentDir - Syntax ═══ This function queries the current drive and directory for a given drive. #define INCL_WTKUTLFILE #include ULONG ulDiskNum; /* The drive number. */ PSZ pszBuffer; /* Address of a buffer, where the given drive and the current directory of that drive is being returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryCurrentDir( ulDiskNum, pszBuffer, ulBuflen); ═══ WtkQueryCurrentDir - Parameter ulDiskNum ═══ ulDiskNum (ULONG) - input The drive number. The value 0 means the current drive, 1 means drive A, 2 means drive B, 3 means drive C, and so on. The maximum possible value is 26, which corresponds to drive Z. ═══ WtkQueryCurrentDir - Parameter pszBuffer ═══ pszBuffer (PSZ) - output Address of a buffer, where the given drive and the current directory of that drive is being returned. ═══ WtkQueryCurrentDir - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ═══ WtkQueryCurrentDir - Parameters ═══ ulDiskNum (ULONG) - input The drive number. The value 0 means the current drive, 1 means drive A, 2 means drive B, 3 means drive C, and so on. The maximum possible value is 26, which corresponds to drive Z. pszBuffer (PSZ) - output Address of a buffer, where the given drive and the current directory of that drive is being returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ulrc (APIRET) - returns Return Code. WtkQueryCurrentDir returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryCurrentDisk  DosQueryCurrentDir ═══ WtkQueryCurrentDir Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryCurrentDir returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryCurrentDisk  DosQueryCurrentDir ═══ WtkQueryCurrentDir - Remarks ═══ In opposite to DosQueryCurrentDir, this function returns both the drive and directory, thus providing a full pathname. ═══ WtkQueryCurrentDir - Related functions ═══ Related Functions none ═══ 8.52. WtkQueryDateTimeStamp ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryDateTimeStamp - Syntax ═══ This function determines a timestamp according to the values of a DATETIME structure. #define INCL_WTKUTLTIME #include PDATETIME pdt; /* Address of the DATETIME structure. */ ULONG ulStampType; /* Type of timestamp. */ PSZ pszBuffer; /* The address of a buffer, into which the timestamp is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryDateTimeStamp( pdt, ulStampType, pszBuffer, ulBuflen); ═══ WtkQueryDateTimeStamp - Parameter pdt ═══ pdt (PDATETIME) - input Address of the DATETIME structure. ═══ WtkQueryDateTimeStamp - Parameter ulStampType ═══ ulStampType (ULONG) - input Type of timestamp. WTK_TIMESTAMP_SORTEDDATETIME returns a sorted date and timestamp in yyyymmddhhmmss WTK_TIMESTAMP_SORTEDDATE returns a sorted datestamp in yyyymmdd WTK_TIMESTAMP_SORTEDTIME returns a sorted timestamp in hhmmss WTK_TIMESTAMP_NLSDATETIME returns a NLS compliant date and timestamp WTK_TIMESTAMP_NLSDATE returns a NLS compliant datestamp WTK_TIMESTAMP_NLSTIME returns a NLS compliant timestamp ═══ WtkQueryDateTimeStamp - Parameter pszBuffer ═══ pszBuffer (PSZ) - output The address of a buffer, into which the timestamp is returned. ═══ WtkQueryDateTimeStamp - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. ═══ WtkQueryDateTimeStamp - Parameters ═══ pdt (PDATETIME) - input Address of the DATETIME structure. ulStampType (ULONG) - input Type of timestamp. WTK_TIMESTAMP_SORTEDDATETIME returns a sorted date and timestamp in yyyymmddhhmmss WTK_TIMESTAMP_SORTEDDATE returns a sorted datestamp in yyyymmdd WTK_TIMESTAMP_SORTEDTIME returns a sorted timestamp in hhmmss WTK_TIMESTAMP_NLSDATETIME returns a NLS compliant date and timestamp WTK_TIMESTAMP_NLSDATE returns a NLS compliant datestamp WTK_TIMESTAMP_NLSTIME returns a NLS compliant timestamp pszBuffer (PSZ) - output The address of a buffer, into which the timestamp is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. ulrc (APIRET) - returns Return Code. WtkQueryDateTimeStamp returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryCtryInfo ═══ WtkQueryDateTimeStamp Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryDateTimeStamp returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryCtryInfo ═══ WtkQueryDateTimeStamp - Remarks ═══ none ═══ WtkQueryDateTimeStamp - Related functions ═══ Related Functions none ═══ 8.53. WtkQueryEaSize ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryEaSize - Syntax ═══ This function determines the size of a given extended attribute of a file or directory. #define INCL_WTKEAS #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory. */ PSZ pszEaName; /* Address of the ASCIIZ name of the extended attribute. */ PULONG pulSize; /* The address of a variable containing the length of the extended attribute. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryEaSize( pszName, pszEaName, pulSize); ═══ WtkQueryEaSize - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. The name may not include wildcards. ═══ WtkQueryEaSize - Parameter pszEaName ═══ pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. ═══ WtkQueryEaSize - Parameter pulSize ═══ pulSize (PULONG) - output The address of a variable containing the length of the extended attribute. ═══ WtkQueryEaSize - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. The name may not include wildcards. pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. pulSize (PULONG) - output The address of a variable containing the length of the extended attribute. ulrc (APIRET) - returns Return Code. WtkQueryEaSize returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryEaSize Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryEaSize returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryEaSize - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkQueryEaSize - Related functions ═══ Related Functions none ═══ 8.54. WtkQueryFDateTimeStamp ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryFDateTimeStamp - Syntax ═══ This function determines a timestamp according to the values of a FDATE and FTIME structure. #define INCL_WTKUTLTIME #include PFDATE pfdate; /* Address of the FDATE structure. */ PFTIME pftime; /* Address of the FTIME structure. */ ULONG ulStampType; /* Type of timestamp. */ PSZ pszBuffer; /* The address of a buffer, into which the timestamp is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryFDateTimeStamp( pfdate, pftime, ulStampType, pszBuffer, ulBuflen); ═══ WtkQueryFDateTimeStamp - Parameter pfdate ═══ pfdate (PFDATE) - input Address of the FDATE structure. ═══ WtkQueryFDateTimeStamp - Parameter pftime ═══ pftime (PFTIME) - input Address of the FTIME structure. ═══ WtkQueryFDateTimeStamp - Parameter ulStampType ═══ ulStampType (ULONG) - input Type of timestamp. WTK_TIMESTAMP_SORTEDDATETIME returns a sorted date and timestamp in yyyymmddhhmmss WTK_TIMESTAMP_SORTEDDATE returns a sorted datestamp in yyyymmdd WTK_TIMESTAMP_SORTEDTIME returns a sorted timestamp in hhmmss WTK_TIMESTAMP_NLSDATETIME returns a NLS compliant date and timestamp WTK_TIMESTAMP_NLSDATE returns a NLS compliant datestamp WTK_TIMESTAMP_NLSTIME returns a NLS compliant timestamp ═══ WtkQueryFDateTimeStamp - Parameter pszBuffer ═══ pszBuffer (PSZ) - output The address of a buffer, into which the timestamp is returned. ═══ WtkQueryFDateTimeStamp - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. ═══ WtkQueryFDateTimeStamp - Parameters ═══ pfdate (PFDATE) - input Address of the FDATE structure. pftime (PFTIME) - input Address of the FTIME structure. ulStampType (ULONG) - input Type of timestamp. WTK_TIMESTAMP_SORTEDDATETIME returns a sorted date and timestamp in yyyymmddhhmmss WTK_TIMESTAMP_SORTEDDATE returns a sorted datestamp in yyyymmdd WTK_TIMESTAMP_SORTEDTIME returns a sorted timestamp in hhmmss WTK_TIMESTAMP_NLSDATETIME returns a NLS compliant date and timestamp WTK_TIMESTAMP_NLSDATE returns a NLS compliant datestamp WTK_TIMESTAMP_NLSTIME returns a NLS compliant timestamp pszBuffer (PSZ) - output The address of a buffer, into which the timestamp is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes. ulrc (APIRET) - returns Return Code. WtkQueryFDateTimeStamp returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryCtryInfo ═══ WtkQueryFDateTimeStamp Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryFDateTimeStamp returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryCtryInfo ═══ WtkQueryFDateTimeStamp - Remarks ═══ none ═══ WtkQueryFDateTimeStamp - Related functions ═══ Related Functions none ═══ 8.55. WtkQueryFileCDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryFileCDateTime - Syntax ═══ This function stores the last write date and time info of a file or directory in a CDATE and CTIME structure. #define INCL_WTKUTLTIME #include PCDATE pcdate; /* Address of the CDATE structure to setup. */ PCTIME pctime; /* Address of the CTIME structure to setup. */ PSZ pszName; /* Address of the ASCIIZ path name of the file to be examined. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryFileCDateTime( pcdate, pctime, pszName); ═══ WtkQueryFileCDateTime - Parameter pcdate ═══ pcdate (PCDATE) - output Address of the CDATE structure to setup. ═══ WtkQueryFileCDateTime - Parameter pctime ═══ pctime (PCTIME) - output Address of the CTIME structure to setup. ═══ WtkQueryFileCDateTime - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file to be examined. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkQueryFileCDateTime - Parameters ═══ pcdate (PCDATE) - output Address of the CDATE structure to setup. pctime (PCTIME) - output Address of the CTIME structure to setup. pszName (PSZ) - input Address of the ASCIIZ path name of the file to be examined. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. ulrc (APIRET) - returns Return Code. WtkQueryFileCDateTime returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryFileCDateTime Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryFileCDateTime returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryFileCDateTime - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkQueryFileCDateTime - Related functions ═══ Related Functions none ═══ 8.56. WtkQueryFileDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryFileDateTime - Syntax ═══ This function stores the last write date and time info of a file or directory in a DATETIME structure. #define INCL_WTKUTLTIME #include PDATETIME pdt; /* Address of the DATETIME structure to setup. */ PSZ pszName; /* Address of the ASCIIZ path name of the file to be examined. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryFileDateTime( pdt, pszName); ═══ WtkQueryFileDateTime - Parameter pdt ═══ pdt (PDATETIME) - output Address of the DATETIME structure to setup. ═══ WtkQueryFileDateTime - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file to be examined. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkQueryFileDateTime - Parameters ═══ pdt (PDATETIME) - output Address of the DATETIME structure to setup. pszName (PSZ) - input Address of the ASCIIZ path name of the file to be examined. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. ulrc (APIRET) - returns Return Code. WtkQueryFileDateTime returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryFileDateTime Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryFileDateTime returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryFileDateTime - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkQueryFileDateTime - Related functions ═══ Related Functions none ═══ 8.57. WtkQueryFileFDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryFileFDateTime - Syntax ═══ This function stores the last write date and time info of a file or directory in a FDATE and FTIME structure. #define INCL_WTKUTLTIME #include PFDATE pfdate; /* Address of the FDATE structure to setup. */ PFTIME pftime; /* Address of the FTIME structure to setup. */ PSZ pszName; /* Address of the ASCIIZ path name of the file to be examined. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryFileFDateTime( pfdate, pftime, pszName); ═══ WtkQueryFileFDateTime - Parameter pfdate ═══ pfdate (PFDATE) - output Address of the FDATE structure to setup. ═══ WtkQueryFileFDateTime - Parameter pftime ═══ pftime (PFTIME) - output Address of the FTIME structure to setup. ═══ WtkQueryFileFDateTime - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file to be examined. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkQueryFileFDateTime - Parameters ═══ pfdate (PFDATE) - output Address of the FDATE structure to setup. pftime (PFTIME) - output Address of the FTIME structure to setup. pszName (PSZ) - input Address of the ASCIIZ path name of the file to be examined. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. ulrc (APIRET) - returns Return Code. WtkQueryFileFDateTime returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryFileFDateTime Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryFileFDateTime returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryFileFDateTime - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkQueryFileFDateTime - Related functions ═══ Related Functions none ═══ 8.58. WtkQueryFileSize ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryFileSize - Syntax ═══ This function returns the size of a given file. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory, which size is to be returned. */ ULONG ulResult; /* Length of file. */ ulResult = WtkQueryFileSize( pszName); ═══ WtkQueryFileSize - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory, which size is to be returned. The path name may contain ?: for the drive in order to search the file on the boot drive. ═══ WtkQueryFileSize - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory, which size is to be returned. The path name may contain ?: for the drive in order to search the file on the boot drive. ulResult (ULONG) - returns Length of file. Zero File is of zero length or does not exist. Other Size of the file. ═══ WtkQueryFileSize Return Value - ulResult ═══ ulResult (ULONG) - returns Length of file. Zero File is of zero length or does not exist. Other Size of the file. ═══ WtkQueryFileSize - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to search the file on the boot drive. ═══ WtkQueryFileSize - Related functions ═══ Related Functions none ═══ 8.59. WtkQueryFullname ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryFullname - Syntax ═══ This function queries the full name of a file or directory. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ path name of the file or direcory. */ PSZ pszBuffer; /* The address of a buffer in into which the full name of the given file or directory is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryFullname( pszName, pszBuffer, ulBuflen); ═══ WtkQueryFullname - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or direcory. The path name may contain ?: for the drive in order to search the file on the boot drive. The name may include wildcards. ═══ WtkQueryFullname - Parameter pszBuffer ═══ pszBuffer (PSZ) - output The address of a buffer in into which the full name of the given file or directory is returned. ═══ WtkQueryFullname - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ═══ WtkQueryFullname - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or direcory. The path name may contain ?: for the drive in order to search the file on the boot drive. The name may include wildcards. pszBuffer (PSZ) - output The address of a buffer in into which the full name of the given file or directory is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ulrc (APIRET) - returns Return Code. WtkQueryFullname returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryFullname Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryFullname returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW or return codes of the following functions  DosQueryPathInfo ═══ WtkQueryFullname - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to search the file on the boot drive. ═══ WtkQueryFullname - Related functions ═══ Related Functions none ═══ 8.60. WtkQueryGUIControlsChanged ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryGUIControlsChanged - Syntax ═══ This function checks a GUI controls of a dialog for changes by examining the parameters of WM_CONTROL messages. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ HWND hwnd; /* Dialog handle of the settings notebook page. */ MPARAM mp1; /* The message parameter 1 of the WM_CONTROL message. */ MPARAM mp2; /* The message parameter 2 of the WM_CONTROL message. */ PBOOL pfOrgValue; /* Adress of a flag variable indicating if all controls of the dialog have the undo value. */ BOOL fResult; /* Change indicator. */ fResult = WtkQueryGUIControlsChanged( hvt, hwnd, mp1, mp2, pfOrgValue); ═══ WtkQueryGUIControlsChanged - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkQueryGUIControlsChanged - Parameter hwnd ═══ hwnd (HWND) - input Dialog handle of the settings notebook page. ═══ WtkQueryGUIControlsChanged - Parameter mp1 ═══ mp1 (MPARAM) - input The message parameter 1 of the WM_CONTROL message. ═══ WtkQueryGUIControlsChanged - Parameter mp2 ═══ mp2 (MPARAM) - input The message parameter 2 of the WM_CONTROL message. ═══ WtkQueryGUIControlsChanged - Parameter pfOrgValue ═══ pfOrgValue (PBOOL) - output Adress of a flag variable indicating if all controls of the dialog have the undo value. ═══ WtkQueryGUIControlsChanged - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. hwnd (HWND) - input Dialog handle of the settings notebook page. mp1 (MPARAM) - input The message parameter 1 of the WM_CONTROL message. mp2 (MPARAM) - input The message parameter 2 of the WM_CONTROL message. pfOrgValue (PBOOL) - output Adress of a flag variable indicating if all controls of the dialog have the undo value. fResult (BOOL) - returns Change indicator. TRUE Value has changed FALSE Value has not changed ═══ WtkQueryGUIControlsChanged Return Value - fResult ═══ fResult (BOOL) - returns Change indicator. TRUE Value has changed FALSE Value has not changed ═══ WtkQueryGUIControlsChanged - Remarks ═══ This function is to be called during WM_CONTROL handling in order to determine wether a GUI control registered with the Settings Manager has changed. ═══ WtkQueryGUIControlsChanged - Related functions ═══ Related Functions none ═══ 8.61. WtkQueryMmfSize ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryMmfSize - Syntax ═══ This function queries the current size of a dynamic memory buffer. #define INCL_WTKMMF #include HMMF hmmf; /* Handle to the MMF manager. */ PVOID pvData; /* Pointer to the allocated address space to be queried. */ PULONG pulSize; /* Address of a variable to receive the current size of the dynamic memory buffer. */ APIRET ulrc; /* Return Code. */ ulrc = WtkQueryMmfSize( hmmf, pvData, pulSize); ═══ WtkQueryMmfSize - Parameter hmmf ═══ hmmf (HMMF) - input Handle to the MMF manager. ═══ WtkQueryMmfSize - Parameter pvData ═══ pvData (PVOID) - input Pointer to the allocated address space to be queried. ═══ WtkQueryMmfSize - Parameter pulSize ═══ pulSize (PULONG) - output Address of a variable to receive the current size of the dynamic memory buffer. ═══ WtkQueryMmfSize - Parameters ═══ hmmf (HMMF) - input Handle to the MMF manager. pvData (PVOID) - input Pointer to the allocated address space to be queried. pulSize (PULONG) - output Address of a variable to receive the current size of the dynamic memory buffer. ulrc (APIRET) - returns Return Code. WtkQueryMmfSize returns one of the following return codes: 0 NO_ERROR 5 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER ═══ WtkQueryMmfSize Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkQueryMmfSize returns one of the following return codes: 0 NO_ERROR 5 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER ═══ WtkQueryMmfSize - Remarks ═══ This function will return the size of the memory buffer including the last read or written byte. ═══ WtkQueryMmfSize - Related functions ═══ Related Functions none ═══ 8.62. WtkQueryNumSpinbuttonIndex ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryNumSpinbuttonIndex - Syntax ═══ This function calculates the array index for a given value for a numeric spinbutton being initialized with WtkInitializeNumSpinbuttonArray. #define INCL_WTKUTLCONTROL #include HWND hwndSpinbutton; /* Handle of the spinbutton window. */ ULONG ulMinValue; /* The minimum value of the spinbutton. */ ULONG ulMaxValue; /* The maximum value of the spinbutton. */ ULONG ulStep; /* The step between the values in the range. */ ULONG ulValue; /* The value, for which the index shall be calculated. */ LONG lResult; /* Array Index. */ lResult = WtkQueryNumSpinbuttonIndex( hwndSpinbutton, ulMinValue, ulMaxValue, ulStep, ulValue); ═══ WtkQueryNumSpinbuttonIndex - Parameter hwndSpinbutton ═══ hwndSpinbutton (HWND) - input Handle of the spinbutton window. ═══ WtkQueryNumSpinbuttonIndex - Parameter ulMinValue ═══ ulMinValue (ULONG) - input The minimum value of the spinbutton. It is required, that the same minimum value is specified here, as it was when initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, otherwise the array value will be incorrect. ═══ WtkQueryNumSpinbuttonIndex - Parameter ulMaxValue ═══ ulMaxValue (ULONG) - input The maximum value of the spinbutton. It is required, that the same maximum value is specified here, as it was when initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, otherwise the array value will be incorrect. ═══ WtkQueryNumSpinbuttonIndex - Parameter ulStep ═══ ulStep (ULONG) - input The step between the values in the range. It is required, that the same step value is specified here, as it was when initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, otherwise the array value will be incorrect. ═══ WtkQueryNumSpinbuttonIndex - Parameter ulValue ═══ ulValue (ULONG) - input The value, for which the index shall be calculated. It is required, that the same maximum value is specified here, as it was when initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, otherwise the array value will be incorrect. ═══ WtkQueryNumSpinbuttonIndex - Parameters ═══ hwndSpinbutton (HWND) - input Handle of the spinbutton window. ulMinValue (ULONG) - input The minimum value of the spinbutton. It is required, that the same minimum value is specified here, as it was when initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, otherwise the array value will be incorrect. ulMaxValue (ULONG) - input The maximum value of the spinbutton. It is required, that the same maximum value is specified here, as it was when initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, otherwise the array value will be incorrect. ulStep (ULONG) - input The step between the values in the range. It is required, that the same step value is specified here, as it was when initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, otherwise the array value will be incorrect. ulValue (ULONG) - input The value, for which the index shall be calculated. It is required, that the same maximum value is specified here, as it was when initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, otherwise the array value will be incorrect. lResult (LONG) - returns Array Index. -1 Array Index could not be calculated or the window is not an array spinbutton control. Other Array index corresponding to the given value. Extended error information can be obtained using WinGetLastError/WinGetErrorInfo. ═══ WtkQueryNumSpinbuttonIndex Return Value - lResult ═══ lResult (LONG) - returns Array Index. -1 Array Index could not be calculated or the window is not an array spinbutton control. Other Array index corresponding to the given value. Extended error information can be obtained using WinGetLastError/WinGetErrorInfo. ═══ WtkQueryNumSpinbuttonIndex - Remarks ═══ This function checks the given window and calculates the index with the following formula: lResult = (ulValue - ulMinValue ) / ulStep; If calculation of the index is performed frequently (whic is mostly not the case), you might want not to use WtkQueryNumSpinbuttonIndex because of performance reasons, but skip the validation and calculate the index yourself. ═══ WtkQueryNumSpinbuttonIndex - Related functions ═══ Related Functions none ═══ 8.63. WtkQueryObjectDetailsData ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryObjectDetailsData - Syntax ═══ This function is to be called by the override of the method _wpQueryDetailsData to automatically setup the details data. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ PVOID *ppDetailsData; /* Adress of the pointer variable to the details data. */ PULONG pcp; /* Adress of the size variable of details data. */ ULONG ulResult; /* Success indicator. */ ulResult = WtkQueryObjectDetailsData( hvt, ppDetailsData, pcp); ═══ WtkQueryObjectDetailsData - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkQueryObjectDetailsData - Parameter ppDetailsData ═══ ppDetailsData (PVOID*) - input Adress of the pointer variable to the details data. ═══ WtkQueryObjectDetailsData - Parameter pcp ═══ pcp (PULONG) - input Adress of the size variable of details data. ═══ WtkQueryObjectDetailsData - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. ppDetailsData (PVOID*) - input Adress of the pointer variable to the details data. pcp (PULONG) - input Adress of the size variable of details data. ulResult (ULONG) - returns Success indicator. TRUE Successful completion. FALSE An error occurred. ═══ WtkQueryObjectDetailsData Return Value - ulResult ═══ ulResult (ULONG) - returns Success indicator. TRUE Successful completion. FALSE An error occurred. ═══ WtkQueryObjectDetailsData - Remarks ═══ This function can be called as follows during _wpQueryDetailsData to automatically setup the details data: _parent__wpQueryDetailsData(somSelf, ppDetailsData, pcp); return WtkQueryObjectDetailsData( _hvt, ppDetailsData, pcp); ═══ WtkQueryObjectDetailsData - Related functions ═══ Related Functions none ═══ 8.64. WtkQueryObjectSettings ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryObjectSettings - Syntax ═══ This function queries the current settings of an object being implented by the WPS class. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ PSZ pszBuffer; /* The address of a buffer in into which the resulting settings string is returned. */ PULONG pulMaxlen; /* The address of a variable for the length, in bytes, of the buffer described by pszBuffer. */ BOOL fResult; /* Success indicator. */ fResult = WtkQueryObjectSettings( hvt, pszBuffer, pulMaxlen); ═══ WtkQueryObjectSettings - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkQueryObjectSettings - Parameter pszBuffer ═══ pszBuffer (PSZ) - output The address of a buffer in into which the resulting settings string is returned. In order to only query the length of this string, leave this parameter NULL. ═══ WtkQueryObjectSettings - Parameter pulMaxlen ═══ pulMaxlen (PULONG) - input/output The address of a variable for the length, in bytes, of the buffer described by pszBuffer. ═══ WtkQueryObjectSettings - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. pszBuffer (PSZ) - output The address of a buffer in into which the resulting settings string is returned. In order to only query the length of this string, leave this parameter NULL. pulMaxlen (PULONG) - input/output The address of a variable for the length, in bytes, of the buffer described by pszBuffer. fResult (BOOL) - returns Success indicator. TRUE String could be queried FALSE An error occurred. ═══ WtkQueryObjectSettings Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE String could be queried FALSE An error occurred. ═══ WtkQueryObjectSettings - Remarks ═══ This function is to be called during _wpSaveState in order to save the current settings implemented by the WPS class. Note: Doing this, you still must call _wpSaveState of the parent class, as WtkQueryObjectSettings will only return and thus you can only save the settings being implemented by your WPS class ! ═══ WtkQueryObjectSettings - Related functions ═══ Related Functions none ═══ 8.65. WtkQuerySysLanguage ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQuerySysLanguage - Syntax ═══ This function returns a pointer to the ASSICZ three letter ISO language identifier according to the language of your operation system. For this the OS/2 syslevel file is uses, whereas the COUNTRY or locale settings are not used (as they may certainly differ from the language of the operation system). #define INCL_WTKUTLSYSTEM #include PSZ pszResult; /* Pointer to the ASSICZ three letter ISO language identifier according to the language of your operation system. */ pszResult = WtkQuerySysLanguage(); ═══ WtkQuerySysLanguage - Parameters ═══ pszResult (PSZ) - returns Pointer to the ASSICZ three letter ISO language identifier according to the language of your operation system. When for any reason the language cannot be determined properly, eng is returned for the english language as default. ═══ WtkQuerySysLanguage Return Value - pszResult ═══ pszResult (PSZ) - returns Pointer to the ASSICZ three letter ISO language identifier according to the language of your operation system. When for any reason the language cannot be determined properly, eng is returned for the english language as default. ═══ WtkQuerySysLanguage - Remarks ═══ This function determines the language from the OS/2 syslevel file of your operating system by reading the language character of the CSD identifier. As the language is coded in one character only within CSD ids and this character must not necessarily be unique to one language, this function in some cases also checks the OS/2 system message file in order to uniquely identify the language of the operating system. The following language identifiers are currently supported: eng us/uk english dan danish deu german esp spanish fin finnish fra french frc canadian french ita italian jpn japanese kor korean ndl dutch nor norwegian pol polish ptb brazilian portugese ptg portugese swe swedish twn taiwanese Note that neither the COUNTRY setting nor the variable LANG is used, as they may differ from the language of the operation system. Moreover, if the user applied a fixpak of another language, the syslevel file may well reflect the language of the fixpak instead of the base operating system. In such a case of course the identifier for this language is returned, but the system will then use this language for many dialogs anyway, so this won't hurt much. ═══ WtkQuerySysLanguage - Related functions ═══ Related Functions none ═══ 8.66. WtkQueryVersion ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkQueryVersion - Syntax ═══ This function creates a settings table for a meta class. #define INCL_WTKVERSION #include PSZ pszBuffer; /* The address of a buffer in into which the version string is returned. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. */ ULONG ulResult; /* Return Code. */ ulResult = WtkQueryVersion( pszBuffer, ulBuflen); ═══ WtkQueryVersion - Parameter pszBuffer ═══ pszBuffer (PSZ) - output The address of a buffer in into which the version string is returned. ═══ WtkQueryVersion - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ═══ WtkQueryVersion - Parameters ═══ pszBuffer (PSZ) - output The address of a buffer in into which the version string is returned. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ulResult (ULONG) - returns Return Code. WtkQueryVersion returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW ═══ WtkQueryVersion Return Value - ulResult ═══ ulResult (ULONG) - returns Return Code. WtkQueryVersion returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW ═══ WtkQueryVersion - Remarks ═══ This function enables to ensure, that the WPS class is using the same version of the WPS toolkit API, that it was compiled with. This is normally not required for WPS class DLLs or applications, where the WPS toolkit functions are statically linked to, but may be important, where they are linked as a DLL. (Note, that the WPS toolkit is not yet available as a DLL). In order to ensure, that your WPS DLL is using the same WPS Toolkit API, as it was compiled with, compare the resulting string with the value WPSTK_VERSION. ═══ WtkQueryVersion - Related functions ═══ Related Functions none ═══ 8.67. WtkReadEa ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkReadEa - Syntax ═══ This function reads an extended attribute of a given file or directory. #define INCL_WTKEAS #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory. */ PSZ pszEaName; /* Address of the ASCIIZ name of the extended attribute. */ PHEA phea; /* The address of a variable containing the handle to the extended attribute */ APIRET ulrc; /* Return Code. */ ulrc = WtkReadEa( pszName, pszEaName, phea); ═══ WtkReadEa - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. The name may not include wildcards. ═══ WtkReadEa - Parameter pszEaName ═══ pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. ═══ WtkReadEa - Parameter phea ═══ phea (PHEA) - output The address of a variable containing the handle to the extended attribute ═══ WtkReadEa - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to open the file or directory on the boot drive. The name may not include wildcards. pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. phea (PHEA) - output The address of a variable containing the handle to the extended attribute ulrc (APIRET) - returns Return Code. WtkReadEa returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkReadEa Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkReadEa returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosQueryPathInfo ═══ WtkReadEa - Remarks ═══ This function allocates resources for handling the value of the given extended attribute, which must be freeed by calling WtkCloseEa, when not longer needed. This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. ═══ WtkReadEa - Related functions ═══ Related Functions none ═══ 8.68. WtkReadFile ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkReadFile - Syntax ═══ This function reads a file completely into memory. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ pathname, which is to be read into memory. */ PSZ *ppszBuffer; /* The address of a pointer variable to a buffer, into which the full file is being read into. The memory allocated by WtkReadFile must be freed by the caller using free(). */ PULONG pulBuflen; /* The address of a variable containing the length of the file, and thus the buffer. */ APIRET ulrc; /* Return Code. */ ulrc = WtkReadFile( pszName, ppszBuffer, pulBuflen); ═══ WtkReadFile - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ pathname, which is to be read into memory. The path name may contain ?: for the drive in order to read the file from the boot drive. ═══ WtkReadFile - Parameter ppszBuffer ═══ ppszBuffer (PSZ*) - output The address of a pointer variable to a buffer, into which the full file is being read into. The memory allocated by WtkReadFile must be freed by the caller using free(). ═══ WtkReadFile - Parameter pulBuflen ═══ pulBuflen (PULONG) - output The address of a variable containing the length of the file, and thus the buffer. ═══ WtkReadFile - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ pathname, which is to be read into memory. The path name may contain ?: for the drive in order to read the file from the boot drive. ppszBuffer (PSZ*) - output The address of a pointer variable to a buffer, into which the full file is being read into. The memory allocated by WtkReadFile must be freed by the caller using free(). pulBuflen (PULONG) - output The address of a variable containing the length of the file, and thus the buffer. ulrc (APIRET) - returns Return Code. WtkReadFile returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosOpen  DosRead ═══ WtkReadFile Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkReadFile returns one of the following return codes: 0 NO_ERROR 8 ERROR_NOT_ENOUGH_MEMORY 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosOpen  DosRead ═══ WtkReadFile - Remarks ═══ The memory allocated by WtkReadFile must be freed by the caller using free(). This function supports boot drive recognition. Specify ?: for the drive in order to read the file from the boot drive. ═══ WtkReadFile - Related functions ═══ Related Functions none ═══ 8.69. WtkReadObjectValueTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkReadObjectValueTable - Syntax ═══ This function reads the object valuetable and transfers them to the GUI controls of a given settings notebookpage. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ HWND hwndDialog; /* Dialog handle of the settings notebook page. */ BOOL fResult; /* Success indicator. */ fResult = WtkReadObjectValueTable( hvt, hwndDialog); ═══ WtkReadObjectValueTable - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkReadObjectValueTable - Parameter hwndDialog ═══ hwndDialog (HWND) - input Dialog handle of the settings notebook page. ═══ WtkReadObjectValueTable - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. hwndDialog (HWND) - input Dialog handle of the settings notebook page. fResult (BOOL) - returns Success indicator. TRUE Values could be transferred to the notebook page dialog. FALSE An error occurred. ═══ WtkReadObjectValueTable Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Values could be transferred to the notebook page dialog. FALSE An error occurred. ═══ WtkReadObjectValueTable - Remarks ═══ This function is to be called in the message handling of the window procedure being used for the settings notebookpages. It should be called when handling the WM_INITDLG message and the WM_COMMAND message for the undo button in order to transfer the current object settings values to the notebook settings page. ═══ WtkReadObjectValueTable - Related functions ═══ Related Functions none ═══ 8.70. WtkReadStringEa ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkReadStringEa - Syntax ═══ This function queries a string extended attribute of a file or directory. #define INCL_WTKEAS #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory. */ PSZ pszEaName; /* Address of the ASCIIZ name of the extended attribute. */ PSZ pszEaValue; /* The address of a buffer in into which the value of the given extended attribute is returned. */ PULONG pulBuflen; /* The address of a variable containing the length, in bytes, of the buffer described by pszEaValue. */ APIRET ulrc; /* Return Code. */ ulrc = WtkReadStringEa( pszName, pszEaName, pszEaValue, pulBuflen); ═══ WtkReadStringEa - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to search the file or directory on the boot drive. The name may not include wildcards. ═══ WtkReadStringEa - Parameter pszEaName ═══ pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. If multiple values and/or types for the specified extended attribute are attached to the file or directory, the first string attribute is returned. ═══ WtkReadStringEa - Parameter pszEaValue ═══ pszEaValue (PSZ) - output The address of a buffer in into which the value of the given extended attribute is returned. ═══ WtkReadStringEa - Parameter pulBuflen ═══ pulBuflen (PULONG) - input/output The address of a variable containing the length, in bytes, of the buffer described by pszEaValue. ═══ WtkReadStringEa - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to search the file or directory on the boot drive. The name may not include wildcards. pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. If multiple values and/or types for the specified extended attribute are attached to the file or directory, the first string attribute is returned. pszEaValue (PSZ) - output The address of a buffer in into which the value of the given extended attribute is returned. pulBuflen (PULONG) - input/output The address of a variable containing the length, in bytes, of the buffer described by pszEaValue. ulrc (APIRET) - returns Return Code. WtkReadStringEa returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE 8 ERROR_NOT_ENOUGH_MEMORY 13 ERROR_INVALID_DATA 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSetPathInfo ═══ WtkReadStringEa Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkReadStringEa returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE 8 ERROR_NOT_ENOUGH_MEMORY 13 ERROR_INVALID_DATA 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSetPathInfo ═══ WtkReadStringEa - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. This function is meant to provide you with easy handling of string extended attributes. The drawback is that for simplicity you cannot  read more than one value from the string extended attribute (but that is what is needed for most cases anyway) If these limitations does not meet your requirements, use the move flexible call WtkPutEaValue instead. ═══ WtkReadStringEa - Related functions ═══ Related Functions none ═══ 8.71. WtkRegisterSettingsDialog ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkRegisterSettingsDialog - Syntax ═══ This function reqisters a dialog of a settings notebookpage for automatic update and restore of the GUI dialog to and from the valuetable of the WPS object. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ HWND hwndDialog; /* Dialog handle of the settings notebook page. */ BOOL fResult; /* Success indicator. */ fResult = WtkRegisterSettingsDialog( hvt, hwndDialog); ═══ WtkRegisterSettingsDialog - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkRegisterSettingsDialog - Parameter hwndDialog ═══ hwndDialog (HWND) - input Dialog handle of the settings notebook page. ═══ WtkRegisterSettingsDialog - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. hwndDialog (HWND) - input Dialog handle of the settings notebook page. fResult (BOOL) - returns Success indicator. TRUE Dialog could be registered. FALSE An error occurred. ═══ WtkRegisterSettingsDialog Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Dialog could be registered. FALSE An error occurred. ═══ WtkRegisterSettingsDialog - Remarks ═══ This function is to be called in the WM_INITDLG message handling of the window procedure being used for the settings notebookpages. ═══ WtkRegisterSettingsDialog - Related functions ═══ Related Functions none ═══ 8.72. WtkRegisterSettingsNotebook ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkRegisterSettingsNotebook - Syntax ═══ This function reqisters the notebook for automatic validation of all registered settings notebookpages, when the notebook is closed. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ HWND hwndNotebook; /* Notebook handle. */ BOOL fResult; /* Success indicator. */ fResult = WtkRegisterSettingsNotebook( hvt, hwndNotebook); ═══ WtkRegisterSettingsNotebook - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkRegisterSettingsNotebook - Parameter hwndNotebook ═══ hwndNotebook (HWND) - input Notebook handle. ═══ WtkRegisterSettingsNotebook - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. hwndNotebook (HWND) - input Notebook handle. fResult (BOOL) - returns Success indicator. TRUE Notebook could be registered. FALSE An error occurred. ═══ WtkRegisterSettingsNotebook Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Notebook could be registered. FALSE An error occurred. ═══ WtkRegisterSettingsNotebook - Remarks ═══ This function is to be called in _wpAddSettingsPages, after the WPS class added all settings notebook pages. When the notebook is closed, all values of the objects valuetable are checked. If the settings notebookpage containing the GUI control for a value has been registerd (thus become active)  the value of this control is validated  if requested from the WPS class, on validation error - the notebook page of the errant GUI control is brought to top - the errant GUI receives focus - the WPS class is being notified of the error, so that it can take the appropriate action - the close request is ignored ═══ WtkRegisterSettingsNotebook - Related functions ═══ Related Functions none ═══ 8.73. WtkRelocateNotebookpageControls ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkRelocateNotebookpageControls - Syntax ═══ This function makes certain pushbuttons a notebook pushbutton and relocates all other controls of a settings notebook page, when the WPS class is being run under OS/2 WARP 4. This allows to use the same dialog template under OS/2 WARP 3 and WARP 4. #define INCL_WTKSETTINGS #include HWND hwndDialog; /* Dialog handle of the settings notebookpage. */ BOOL fResult; /* Success indicator. */ fResult = WtkRelocateNotebookpageControls( hwndDialog); ═══ WtkRelocateNotebookpageControls - Parameter hwndDialog ═══ hwndDialog (HWND) - input Dialog handle of the settings notebookpage. ═══ WtkRelocateNotebookpageControls - Parameters ═══ hwndDialog (HWND) - input Dialog handle of the settings notebookpage. fResult (BOOL) - returns Success indicator. TRUE Relocation successful or not OS/2 Warp 4 running. FALSE A validation error occurred. ═══ WtkRelocateNotebookpageControls Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Relocation successful or not OS/2 Warp 4 running. FALSE A validation error occurred. ═══ WtkRelocateNotebookpageControls - Remarks ═══ This function first of all determines, if OS/2 WARP 4 is running. If not, it aborts with no error. Otherwise  the layout of all groupboxes is examined and the lowest groupbox (nearest to y-coordinate 0) is determined.  all pushbuttons below the lowest groupbox are made notebook buttons, thus being moved out of the dialog.  all other controls are moved downwards, so that the gap of the now missing pusbuttons is closed. ═══ WtkRelocateNotebookpageControls - Related functions ═══ Related Functions none ═══ 8.74. WtkRestoreObjectSettings ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkRestoreObjectSettings - Syntax ═══ This function restores the settings being previously saved with WtkSaveObjectSettings.. Both the settings valuetable and currently active GUI controls corresponding to the restored values are updated. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ PSZ pszFilename; /* Address of the ASCIIZ filename of the INI file to read the settings from. */ PSZ pszApp; /* Name of the INI application name. */ PSZ pszKey; /* Name of the INI application key. */ BOOL fResult; /* Success indicator. */ fResult = WtkRestoreObjectSettings( hvt, pszFilename, pszApp, pszKey); ═══ WtkRestoreObjectSettings - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkRestoreObjectSettings - Parameter pszFilename ═══ pszFilename (PSZ) - input Address of the ASCIIZ filename of the INI file to read the settings from. The following names are reserved to read from the user or system ini: Name INI file USER write to the user ini file using HINI_USER(PROFILE) SYSTEM write to the systemr ini file using HINI_SYSTEM(PROFILE) ═══ WtkRestoreObjectSettings - Parameter pszApp ═══ pszApp (PSZ) - input Name of the INI application name. Note: This application name should identify the WPS class in order not to mix up with settings of other WPS classes using this function, if writing to the same INI file ! ═══ WtkRestoreObjectSettings - Parameter pszKey ═══ pszKey (PSZ) - input Name of the INI application key. This parameter can be left NULL, then the persistent WPS object handle is being used to generate a unique key id. Note: If the WPS class specifies a key, it is its responsability to make sure, that the key is unique in order to not mix up with settings of another object of the same class. ═══ WtkRestoreObjectSettings - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. pszFilename (PSZ) - input Address of the ASCIIZ filename of the INI file to read the settings from. The following names are reserved to read from the user or system ini: Name INI file USER write to the user ini file using HINI_USER(PROFILE) SYSTEM write to the systemr ini file using HINI_SYSTEM(PROFILE) pszApp (PSZ) - input Name of the INI application name. Note: This application name should identify the WPS class in order not to mix up with settings of other WPS classes using this function, if writing to the same INI file ! pszKey (PSZ) - input Name of the INI application key. This parameter can be left NULL, then the persistent WPS object handle is being used to generate a unique key id. Note: If the WPS class specifies a key, it is its responsability to make sure, that the key is unique in order to not mix up with settings of another object of the same class. fResult (BOOL) - returns Success indicator. TRUE Settings could be restored and updated. FALSE A validation error occurred. ═══ WtkRestoreObjectSettings Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Settings could be restored and updated. FALSE A validation error occurred. ═══ WtkRestoreObjectSettings - Remarks ═══ This function is to be called during _wpRestoreState, if the settings have been saved externally before as a settings string. This function restores the settings being previously saved with WtkSaveObjectSettings.. ═══ WtkRestoreObjectSettings - Related functions ═══ Related Functions none ═══ 8.75. WtkRestoreObjectState ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkRestoreObjectState - Syntax ═══ This function restores the settings of an object instance being previously saved with WtkSaveState. Both the settings valuetable and currently active GUI controls corresponding to the restored values are updated. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ PSZ pszClass; /* Address of a unique ASCIIZ string. */ BOOL fResult; /* Success indicator. */ fResult = WtkRestoreObjectState( hvt, pszClass); ═══ WtkRestoreObjectState - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkRestoreObjectState - Parameter pszClass ═══ pszClass (PSZ) - input Address of a unique ASCIIZ string. The class name is recommended, but not enforced. ═══ WtkRestoreObjectState - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. pszClass (PSZ) - input Address of a unique ASCIIZ string. The class name is recommended, but not enforced. fResult (BOOL) - returns Success indicator. TRUE Settings could be restored and updated. FALSE A validation error occurred. ═══ WtkRestoreObjectState Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Settings could be restored and updated. FALSE A validation error occurred. ═══ WtkRestoreObjectState - Remarks ═══ This function is to be called during _wpRestoreState to restore all current settings values handled by Settings and Details Manager. You need to specify unique settings ids in order to have settings values stored with this API. This function restores the settings being previously saved with WtkSaveObjectState. ═══ WtkRestoreObjectState - Related functions ═══ Related Functions none ═══ 8.76. WtkSaveEa ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSaveEa - Syntax ═══ This function writes an extended attribute from memory to disk. #define INCL_WTKEAS #include HEA hea; /* Handle to the extended attribute. */ BOOL fWriteThru; /* A flag to bypass the cache and write the extended attribute directly to disk. */ BYTE fEA; /* The flags to be set for this extended attribute flags. */ APIRET ulrc; /* Return Code. */ ulrc = WtkSaveEa( hea, fWriteThru, fEA); ═══ WtkSaveEa - Parameter hea ═══ hea (HEA) - input Handle to the extended attribute. ═══ WtkSaveEa - Parameter fWriteThru ═══ fWriteThru (BOOL) - input A flag to bypass the cache and write the extended attribute directly to disk. ═══ WtkSaveEa - Parameter fEA ═══ fEA (BYTE) - input The flags to be set for this extended attribute flags. Specify FEA_NEEDEDEA in order to mark the extended attribute as critical. Otherwise set this parameter to zero. ═══ WtkSaveEa - Parameters ═══ hea (HEA) - input Handle to the extended attribute. fWriteThru (BOOL) - input A flag to bypass the cache and write the extended attribute directly to disk. fEA (BYTE) - input The flags to be set for this extended attribute flags. Specify FEA_NEEDEDEA in order to mark the extended attribute as critical. Otherwise set this parameter to zero. ulrc (APIRET) - returns Return Code. WtkSaveEa returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE or return codes of the following functions  DosSetPathInfo ═══ WtkSaveEa Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkSaveEa returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE or return codes of the following functions  DosSetPathInfo ═══ WtkSaveEa - Remarks ═══ This function does not deallocate resources for handling the value of the given extended attribute. They must be freeed by calling WtkCloseEa, when not longer needed. ═══ WtkSaveEa - Related functions ═══ Related Functions none ═══ 8.77. WtkSaveObjectSettings ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSaveObjectSettings - Syntax ═══ This saves the current settings of an object instance values externally in an INI file of choice. Use WtkSaveState instead to save the settings within the WPS repository as usual. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ PSZ pszFilename; /* Address of the ASCIIZ filename of the INI file to write the settings to. */ PSZ pszApp; /* Name of the INI application name. */ PSZ pszKey; /* Name of the INI application key. */ BOOL fResult; /* Success indicator. */ fResult = WtkSaveObjectSettings( hvt, pszFilename, pszApp, pszKey); ═══ WtkSaveObjectSettings - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkSaveObjectSettings - Parameter pszFilename ═══ pszFilename (PSZ) - input Address of the ASCIIZ filename of the INI file to write the settings to. The following names are reserved to write to the user or system ini: Name INI file USER write to the user ini file using HINI_USER(PROFILE) SYSTEM write to the systemr ini file using HINI_SYSTEM(PROFILE) ═══ WtkSaveObjectSettings - Parameter pszApp ═══ pszApp (PSZ) - input Name of the INI application name. Note: This application name should identify the WPS class in order not to mix up with settings of other WPS classes using this function, if writing to the same INI file ! ═══ WtkSaveObjectSettings - Parameter pszKey ═══ pszKey (PSZ) - input Name of the INI application key. This parameter can be left NULL, then the persistent WPS object handle is being used to generate a unique key id. Note: If the WPS class specifies a key, it is its responsability to make sure, that the key is unique in order to not mix up with settings of another object of the same class. ═══ WtkSaveObjectSettings - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. pszFilename (PSZ) - input Address of the ASCIIZ filename of the INI file to write the settings to. The following names are reserved to write to the user or system ini: Name INI file USER write to the user ini file using HINI_USER(PROFILE) SYSTEM write to the systemr ini file using HINI_SYSTEM(PROFILE) pszApp (PSZ) - input Name of the INI application name. Note: This application name should identify the WPS class in order not to mix up with settings of other WPS classes using this function, if writing to the same INI file ! pszKey (PSZ) - input Name of the INI application key. This parameter can be left NULL, then the persistent WPS object handle is being used to generate a unique key id. Note: If the WPS class specifies a key, it is its responsability to make sure, that the key is unique in order to not mix up with settings of another object of the same class. fResult (BOOL) - returns Success indicator. TRUE Settings could be saved. FALSE A validation error occurred. ═══ WtkSaveObjectSettings Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Settings could be saved. FALSE A validation error occurred. ═══ WtkSaveObjectSettings - Remarks ═══ This function is to be called during _wpSaveState, if the settings are to be saved externally as a settings string. While the settings of general WPS classes can only be stored in the OS/2 INI file, this function saves the object settings being handled by this settings manager API in an INI file of choice. The settings can be restored by using WtkRestoreObjectSettings.. ═══ WtkSaveObjectSettings - Related functions ═══ Related Functions none ═══ 8.78. WtkSaveObjectState ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSaveObjectState - Syntax ═══ This saves the current settings values of an object instance within the WPS repository. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ PSZ pszClass; /* Address of a unique ASCIIZ string. */ BOOL fResult; /* Success indicator. */ fResult = WtkSaveObjectState( hvt, pszClass); ═══ WtkSaveObjectState - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkSaveObjectState - Parameter pszClass ═══ pszClass (PSZ) - input Address of a unique ASCIIZ string. The class name is recommended, but not enforced. ═══ WtkSaveObjectState - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. pszClass (PSZ) - input Address of a unique ASCIIZ string. The class name is recommended, but not enforced. fResult (BOOL) - returns Success indicator. TRUE Settings could be saved. FALSE A validation error occurred. ═══ WtkSaveObjectState Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Settings could be saved. FALSE A validation error occurred. ═══ WtkSaveObjectState - Remarks ═══ This function is to be called during _wpSaveState to save all current settings values handled by Settings and Details Manager. You need to specify unique settings ids in order to have settings values stored with this API. The settings can be restored by using WtkRestoreObjectState.. ═══ WtkSaveObjectState - Related functions ═══ Related Functions none ═══ 8.79. WtkSetCDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSetCDateTime - Syntax ═══ This function sets up a CDATE and/or CTIME structure in a single API call. #define INCL_WTKUTLTIME #include UCHAR uchDay; /* Day of the month, using values 1 through 31. */ UCHAR uchMonth; /* Month of the year, using values 1 through 12. */ USHORT usYear; /* Year, using values in a four digit format. */ UCHAR uchHours; /* Hour, using values 0 through 23. */ UCHAR uchMinutes; /* Minute, using values 0 through 59. */ UCHAR uchSeconds; /* Second, using values 0 through 59. */ PCDATE pcdate; /* Address of the CDATE structure to set up. */ PCTIME pctime; /* Address of the CTIME structure to set up. */ BOOL fResult; /* Success indicator. */ fResult = WtkSetCDateTime( uchDay, uchMonth, usYear, uchHours, uchMinutes, uchSeconds, pcdate, pctime); ═══ WtkSetCDateTime - Parameter uchDay ═══ uchDay (UCHAR) - input Day of the month, using values 1 through 31. ═══ WtkSetCDateTime - Parameter uchMonth ═══ uchMonth (UCHAR) - input Month of the year, using values 1 through 12. ═══ WtkSetCDateTime - Parameter usYear ═══ usYear (USHORT) - input Year, using values in a four digit format. ═══ WtkSetCDateTime - Parameter uchHours ═══ uchHours (UCHAR) - input Hour, using values 0 through 23. ═══ WtkSetCDateTime - Parameter uchMinutes ═══ uchMinutes (UCHAR) - input Minute, using values 0 through 59. ═══ WtkSetCDateTime - Parameter uchSeconds ═══ uchSeconds (UCHAR) - input Second, using values 0 through 59. ═══ WtkSetCDateTime - Parameter pcdate ═══ pcdate (PCDATE) - input Address of the CDATE structure to set up. If the setup of a CDATE structure is not required, leave this parameter NULL. ═══ WtkSetCDateTime - Parameter pctime ═══ pctime (PCTIME) - input Address of the CTIME structure to set up. If the setup of a CTIME structure is not required, leave this parameter NULL. ═══ WtkSetCDateTime - Parameters ═══ uchDay (UCHAR) - input Day of the month, using values 1 through 31. uchMonth (UCHAR) - input Month of the year, using values 1 through 12. usYear (USHORT) - input Year, using values in a four digit format. uchHours (UCHAR) - input Hour, using values 0 through 23. uchMinutes (UCHAR) - input Minute, using values 0 through 59. uchSeconds (UCHAR) - input Second, using values 0 through 59. pcdate (PCDATE) - input Address of the CDATE structure to set up. If the setup of a CDATE structure is not required, leave this parameter NULL. pctime (PCTIME) - input Address of the CTIME structure to set up. If the setup of a CTIME structure is not required, leave this parameter NULL. fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkSetCDateTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkSetCDateTime - Remarks ═══ This function does not check any of the date or time values. It only fails, if both pointers to the CDATE and CTIME structure are NULL. ═══ WtkSetCDateTime - Related functions ═══ Related Functions none ═══ 8.80. WtkSetCurrentDir ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSetCurrentDir - Syntax ═══ This function sets the current drive and the directory for a given drive. If a drive is not given, the current drive is being assumed. #define INCL_WTKUTLFILE #include PSZ pszDirectory; /* The drive and directory to be set current. */ APIRET ulrc; /* Return Code. */ ulrc = WtkSetCurrentDir( pszDirectory); ═══ WtkSetCurrentDir - Parameter pszDirectory ═══ pszDirectory (PSZ) - The drive and directory to be set current. If a drive is not given, the current drive is being assumed. The directory name may contain ?: for the drive in order to set the boot drive as the default drive. ═══ WtkSetCurrentDir - Parameters ═══ pszDirectory (PSZ) - The drive and directory to be set current. If a drive is not given, the current drive is being assumed. The directory name may contain ?: for the drive in order to set the boot drive as the default drive. ulrc (APIRET) - returns Return Code. WtkSetCurrentDir returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSetDefaultDisk  DosSetCurrentDir ═══ WtkSetCurrentDir Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkSetCurrentDir returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSetDefaultDisk  DosSetCurrentDir ═══ WtkSetCurrentDir - Remarks ═══ In opposite to DosSetCurrentDir, this function sets also a given drive as default disk. This function supports boot drive recognition. Specify ?: for the drive in order to set the boot drive as the default drive. ═══ WtkSetCurrentDir - Related functions ═══ Related Functions none ═══ 8.81. WtkSetDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSetDateTime - Syntax ═══ This function sets up a DATETIME structure in a single API call. #define INCL_WTKUTLTIME #include UCHAR uchDay; /* Day of the month, using values 1 through 31. */ UCHAR uchMonth; /* Month of the year, using values 1 through 12. */ USHORT usYear; /* Year, using values from 1900 up. */ UCHAR uchHours; /* Hour, using values 0 through 23. */ UCHAR uchMinutes; /* Minute, using values 0 through 59. */ UCHAR uchSeconds; /* Second, using values 0 through 59. */ PDATETIME pdt; /* Address of the DATETIME structure to set up. */ BOOL fResult; /* Success indicator. */ fResult = WtkSetDateTime( uchDay, uchMonth, usYear, uchHours, uchMinutes, uchSeconds, pdt); ═══ WtkSetDateTime - Parameter uchDay ═══ uchDay (UCHAR) - input Day of the month, using values 1 through 31. ═══ WtkSetDateTime - Parameter uchMonth ═══ uchMonth (UCHAR) - input Month of the year, using values 1 through 12. ═══ WtkSetDateTime - Parameter usYear ═══ usYear (USHORT) - input Year, using values from 1900 up. ═══ WtkSetDateTime - Parameter uchHours ═══ uchHours (UCHAR) - input Hour, using values 0 through 23. ═══ WtkSetDateTime - Parameter uchMinutes ═══ uchMinutes (UCHAR) - input Minute, using values 0 through 59. ═══ WtkSetDateTime - Parameter uchSeconds ═══ uchSeconds (UCHAR) - input Second, using values 0 through 59. ═══ WtkSetDateTime - Parameter pdt ═══ pdt (PDATETIME) - output Address of the DATETIME structure to set up. ═══ WtkSetDateTime - Parameters ═══ uchDay (UCHAR) - input Day of the month, using values 1 through 31. uchMonth (UCHAR) - input Month of the year, using values 1 through 12. usYear (USHORT) - input Year, using values from 1900 up. uchHours (UCHAR) - input Hour, using values 0 through 23. uchMinutes (UCHAR) - input Minute, using values 0 through 59. uchSeconds (UCHAR) - input Second, using values 0 through 59. pdt (PDATETIME) - output Address of the DATETIME structure to set up. fResult (BOOL) - returns Success indicator. TRUE Successful FALSE Not successful (due to invalid parameter). ═══ WtkSetDateTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Successful FALSE Not successful (due to invalid parameter). ═══ WtkSetDateTime - Remarks ═══ This function does not check any of the date or time values. It only fails, if the provided pointer to the DATETIME structure is NULL. ═══ WtkSetDateTime - Related functions ═══ Related Functions none ═══ 8.82. WtkSetErrorInfo ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSetErrorInfo - Syntax ═══ This function sets the error info, that can be obtained later by WinGetLastError and WinGetErrorInfo. #define INCL_WTKUTLERROR #include APIRET rc; /* Return code to be used when creating the error information. */ BOOL fResult; /* Error indicator. */ fResult = WtkSetErrorInfo( rc); ═══ WtkSetErrorInfo - Parameter rc ═══ rc (APIRET) - input Return code to be used when creating the error information. When rc is set to NO_ERROR (0) or PMHERR_USE_EXISTING_ERRORINFO (-1), WtkSetErrorInfo takes no action. ═══ WtkSetErrorInfo - Parameters ═══ rc (APIRET) - input Return code to be used when creating the error information. When rc is set to NO_ERROR (0) or PMHERR_USE_EXISTING_ERRORINFO (-1), WtkSetErrorInfo takes no action. fResult (BOOL) - returns Error indicator. TRUE rc was reporting NO_ERROR. FALSE rc was reporting an error. ═══ WtkSetErrorInfo Return Value - fResult ═══ fResult (BOOL) - returns Error indicator. TRUE rc was reporting NO_ERROR. FALSE rc was reporting an error. ═══ WtkSetErrorInfo - Remarks ═══ WtkSetErrorInfo distincts between OS/2 control program errors and errors of the presentation manager API, and sets the error info according to that distinction. When rc is set to NO_ERROR (0) or PMHERR_USE_EXISTING_ERRORINFO (-1), WtkSetErrorInfo takes no action. This enables the caller to invoke this function always without taking care, if an error occurred or not. More, PMHERR_USE_EXISTING_ERRORINFO can preserve the error info of a previous failed Win* API call, but still lets WtkSetErrorInfo return FALSE. When the callers function returns BOOL, the following line would automatically set the error info and return the appropriate value: return WtkSetErrorInfo( rc); ═══ WtkSetErrorInfo - Related functions ═══ Related Functions none ═══ 8.83. WtkSetFDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSetFDateTime - Syntax ═══ This function sets up a FDATE and/or FTIME structure in a single API call. #define INCL_WTKUTLTIME #include UCHAR uchDay; /* Day of the month, using values 1 through 31. */ UCHAR uchMonth; /* Month of the year, using values 1 through 12. */ USHORT usYear; /* Year, using values from 1980 up. */ UCHAR uchHours; /* Hour, using values 0 through 23. */ UCHAR uchMinutes; /* Minute, using values 0 through 59. */ UCHAR uchSeconds; /* Second, using values 0 through 59. */ PFDATE pfdate; /* Address of the FDATE structure to set up. */ PFTIME pftime; /* Address of the FTIME structure to set up. */ BOOL fResult; /* Success indicator. */ fResult = WtkSetFDateTime( uchDay, uchMonth, usYear, uchHours, uchMinutes, uchSeconds, pfdate, pftime); ═══ WtkSetFDateTime - Parameter uchDay ═══ uchDay (UCHAR) - input Day of the month, using values 1 through 31. ═══ WtkSetFDateTime - Parameter uchMonth ═══ uchMonth (UCHAR) - input Month of the year, using values 1 through 12. ═══ WtkSetFDateTime - Parameter usYear ═══ usYear (USHORT) - input Year, using values from 1980 up. ═══ WtkSetFDateTime - Parameter uchHours ═══ uchHours (UCHAR) - input Hour, using values 0 through 23. ═══ WtkSetFDateTime - Parameter uchMinutes ═══ uchMinutes (UCHAR) - input Minute, using values 0 through 59. ═══ WtkSetFDateTime - Parameter uchSeconds ═══ uchSeconds (UCHAR) - input Second, using values 0 through 59. ═══ WtkSetFDateTime - Parameter pfdate ═══ pfdate (PFDATE) - output Address of the FDATE structure to set up. If the setup of a FDATE structure is not required, leave this parameter NULL. ═══ WtkSetFDateTime - Parameter pftime ═══ pftime (PFTIME) - output Address of the FTIME structure to set up. If the setup of a FTIME structure is not required, leave this parameter NULL. ═══ WtkSetFDateTime - Parameters ═══ uchDay (UCHAR) - input Day of the month, using values 1 through 31. uchMonth (UCHAR) - input Month of the year, using values 1 through 12. usYear (USHORT) - input Year, using values from 1980 up. uchHours (UCHAR) - input Hour, using values 0 through 23. uchMinutes (UCHAR) - input Minute, using values 0 through 59. uchSeconds (UCHAR) - input Second, using values 0 through 59. pfdate (PFDATE) - output Address of the FDATE structure to set up. If the setup of a FDATE structure is not required, leave this parameter NULL. pftime (PFTIME) - output Address of the FTIME structure to set up. If the setup of a FTIME structure is not required, leave this parameter NULL. fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkSetFDateTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkSetFDateTime - Remarks ═══ This function does not check any of the date or time values. It only fails, if both pointers to the FDATE and FTIME structure are NULL. Due to limitations of the FAT filesystem  the FDATE structure can store and thus this function can handle only dates from 1980 up.  the FTIME structure can store and thus this function can handle only seconds in two seconds steps. As a result, the conversion via this function results in the loss of one second, if an odd number of seconds is specified. ═══ WtkSetFDateTime - Related functions ═══ Related Functions none ═══ 8.84. WtkSetMmfSize ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkSetMmfSize - Syntax ═══ This function adjusts the size of a dynamic memory buffer. #define INCL_WTKMMF #include HMMF hmmf; /* Handle to the MMF manager. */ PVOID pvData; /* Pointer to the allocated address space to be adjusted in size. */ ULONG ulNewSize; /* New size of the memory buffer. */ APIRET ulrc; /* Return Code. */ ulrc = WtkSetMmfSize( hmmf, pvData, ulNewSize); ═══ WtkSetMmfSize - Parameter hmmf ═══ hmmf (HMMF) - input Handle to the MMF manager. ═══ WtkSetMmfSize - Parameter pvData ═══ pvData (PVOID) - input Pointer to the allocated address space to be adjusted in size. ═══ WtkSetMmfSize - Parameter ulNewSize ═══ ulNewSize (ULONG) - input New size of the memory buffer. The new size cannot exceed the maximum size that was specified when allocating the dynamic memory buffer with WtkAllocMmf. ═══ WtkSetMmfSize - Parameters ═══ hmmf (HMMF) - input Handle to the MMF manager. pvData (PVOID) - input Pointer to the allocated address space to be adjusted in size. ulNewSize (ULONG) - input New size of the memory buffer. The new size cannot exceed the maximum size that was specified when allocating the dynamic memory buffer with WtkAllocMmf. ulrc (APIRET) - returns Return Code. WtkSetMmfSize returns one of the following return codes: 0 NO_ERROR 5 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW ═══ WtkSetMmfSize Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkSetMmfSize returns one of the following return codes: 0 NO_ERROR 5 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER 111 ERROR_BUFFER_OVERFLOW ═══ WtkSetMmfSize - Remarks ═══ The new size cannot exceed the maximum size that was specified when allocating the dynamic memory buffer with WtkAllocMmf. ═══ WtkSetMmfSize - Related functions ═══ Related Functions none ═══ 8.85. WtkTerminateMmf ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkTerminateMmf - Syntax ═══ This function deinitializes MMF support for the current thread. #define INCL_WTKMMF #include HMMF hmmf; /* Handle to the MMF manager. */ APIRET ulrc; /* Return Code. */ ulrc = WtkTerminateMmf( hmmf); ═══ WtkTerminateMmf - Parameter hmmf ═══ hmmf (HMMF) - input Handle to the MMF manager. ═══ WtkTerminateMmf - Parameters ═══ hmmf (HMMF) - input Handle to the MMF manager. ulrc (APIRET) - returns Return Code. WtkTerminateMmf returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER ═══ WtkTerminateMmf Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkTerminateMmf returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER ═══ WtkTerminateMmf - Remarks ═══ This function deregisters the exception handler for to support memory mapped files. Make sure that you always WtkTerminateMmf before exiting the function that has called WtkInitializeMmf, especially if other exception handler are used beside the one for MMF support. Otherwise unpredictable results (most often simply protection violations may occurr). ═══ WtkTerminateMmf - Related functions ═══ Related Functions none ═══ 8.86. WtkTimeToCDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkTimeToCDateTime - Syntax ═══ This function either converts a time value used by the compiler runtime to CDATE and CTIME stuctures or fills it with values of current date and time. #define INCL_WTKUTLTIME #include time_t *ptime; /* Address of the time value. */ PCDATE pcdate; /* Address of the CDATE structure. */ PCTIME pctime; /* Address of the CTIME structure. */ BOOL fResult; /* Success indicator. */ fResult = WtkTimeToCDateTime( ptime, pcdate, pctime); ═══ WtkTimeToCDateTime - Parameter ptime ═══ ptime (time_t*) - input Address of the time value. In order to use the current time, leave this parameter NULL. ═══ WtkTimeToCDateTime - Parameter pcdate ═══ pcdate (PCDATE) - output Address of the CDATE structure. If the setup of a CDATE structure is not required, leave this parameter NULL. ═══ WtkTimeToCDateTime - Parameter pctime ═══ pctime (PCTIME) - output Address of the CTIME structure. If the setup of a CTIME structure is not required, leave this parameter NULL. ═══ WtkTimeToCDateTime - Parameters ═══ ptime (time_t*) - input Address of the time value. In order to use the current time, leave this parameter NULL. pcdate (PCDATE) - output Address of the CDATE structure. If the setup of a CDATE structure is not required, leave this parameter NULL. pctime (PCTIME) - output Address of the CTIME structure. If the setup of a CTIME structure is not required, leave this parameter NULL. fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkTimeToCDateTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkTimeToCDateTime - Remarks ═══ This function uses the localtime function and thus modifies the runtime memory being used for reporting the result. ═══ WtkTimeToCDateTime - Related functions ═══ Related Functions none ═══ 8.87. WtkTimeToDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkTimeToDateTime - Syntax ═══ This function either converts a time value used by the compiler runtime to a DATETIME stucture or fills it with values of current date and time. #define INCL_WTKUTLTIME #include time_t *ptime; /* Address of the time value to be converted. */ PDATETIME pdt; /* Address of the DATETIME structure to set up. */ BOOL fResult; /* Success indicator. */ fResult = WtkTimeToDateTime( ptime, pdt); ═══ WtkTimeToDateTime - Parameter ptime ═══ ptime (time_t*) - input Address of the time value to be converted. In order to use the current time, leave this parameter NULL. ═══ WtkTimeToDateTime - Parameter pdt ═══ pdt (PDATETIME) - output Address of the DATETIME structure to set up. ═══ WtkTimeToDateTime - Parameters ═══ ptime (time_t*) - input Address of the time value to be converted. In order to use the current time, leave this parameter NULL. pdt (PDATETIME) - output Address of the DATETIME structure to set up. fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkTimeToDateTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkTimeToDateTime - Remarks ═══ When converting a given time value, this function uses the localtime function and thus modifies the runtime memory being used for reporting the result. ═══ WtkTimeToDateTime - Related functions ═══ Related Functions none ═══ 8.88. WtkTimeToFDateTime ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkTimeToFDateTime - Syntax ═══ This function either converts a time value used by the compiler runtime to FDATE and FTIME stuctures or fills it with values of current date and time. #define INCL_WTKUTLTIME #include time_t *ptime; /* Address of the time value. */ PFDATE pfdate; /* Address of the FDATE structure. */ PFTIME pftime; /* Address of the FTIME structure. */ BOOL fResult; /* Success indicator. */ fResult = WtkTimeToFDateTime( ptime, pfdate, pftime); ═══ WtkTimeToFDateTime - Parameter ptime ═══ ptime (time_t*) - input Address of the time value. In order to use the current time, leave this parameter NULL. ═══ WtkTimeToFDateTime - Parameter pfdate ═══ pfdate (PFDATE) - output Address of the FDATE structure. If the setup of a FDATE structure is not required, leave this parameter NULL. ═══ WtkTimeToFDateTime - Parameter pftime ═══ pftime (PFTIME) - output Address of the FTIME structure. If the setup of a FDATE structure is not required, leave this parameter NULL. ═══ WtkTimeToFDateTime - Parameters ═══ ptime (time_t*) - input Address of the time value. In order to use the current time, leave this parameter NULL. pfdate (PFDATE) - output Address of the FDATE structure. If the setup of a FDATE structure is not required, leave this parameter NULL. pftime (PFTIME) - output Address of the FTIME structure. If the setup of a FDATE structure is not required, leave this parameter NULL. fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkTimeToFDateTime Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Conversion successful. FALSE Conversion not successful or invalid parameters. ═══ WtkTimeToFDateTime - Remarks ═══ This function uses the localtime function and thus modifies the runtime memory being used for reporting the result. ═══ WtkTimeToFDateTime - Related functions ═══ Related Functions none ═══ 8.89. WtkUpdateMmf ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkUpdateMmf - Syntax ═══ This function updates the file attached to a dynamic memory buffer. #define INCL_WTKMMF #include HMMF hmmf; /* Handle to the MMF manager. */ PVOID pvData; /* Pointer to the allocated address space to be saved. */ APIRET ulrc; /* Return Code. */ ulrc = WtkUpdateMmf( hmmf, pvData); ═══ WtkUpdateMmf - Parameter hmmf ═══ hmmf (HMMF) - input Handle to the MMF manager. ═══ WtkUpdateMmf - Parameter pvData ═══ pvData (PVOID) - input Pointer to the allocated address space to be saved. ═══ WtkUpdateMmf - Parameters ═══ hmmf (HMMF) - input Handle to the MMF manager. pvData (PVOID) - input Pointer to the allocated address space to be saved. ulrc (APIRET) - returns Return Code. WtkUpdateMmf returns one of the following return codes: 0 NO_ERROR 5 ERROR_ACCESS_DENIED 87 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER ═══ WtkUpdateMmf Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkUpdateMmf returns one of the following return codes: 0 NO_ERROR 5 ERROR_ACCESS_DENIED 87 ERROR_INVALID_HANDLE 87 ERROR_INVALID_PARAMETER ═══ WtkUpdateMmf - Remarks ═══ Only truly modified memory pages of the dynamic memory buffer are stored (every memory page of 4KB in size that has been modified since the read from disk) and then marked as updated. Calling WtkUpdateMmf on memory buffers that hold data from a file opened in readonly mode will return ERROR_ACCESS_DENIED. ═══ WtkUpdateMmf - Related functions ═══ Related Functions none ═══ 8.90. WtkValidateObjectValueTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkValidateObjectValueTable - Syntax ═══ This function validates values of all active GUI controls registered for values in the objects valuetable and triggers the callback routine for validation and error report. On error, the notebook is switched to the page with the control having invalid content and the focus is set to that control. Note: It is recommended not to call this function by the code of your WPS class directly, when validation should take place only on closing the settings notebook (see remarks). #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ HWND hwndNotebook; /* Notebook handle. */ BOOL fResult; /* Success indicator. */ fResult = WtkValidateObjectValueTable( hvt, hwndNotebook); ═══ WtkValidateObjectValueTable - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkValidateObjectValueTable - Parameter hwndNotebook ═══ hwndNotebook (HWND) - input Notebook handle. ═══ WtkValidateObjectValueTable - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. hwndNotebook (HWND) - input Notebook handle. fResult (BOOL) - returns Success indicator. TRUE The values of all registered GUI controls are valid. FALSE A validation error occurred. ═══ WtkValidateObjectValueTable Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE The values of all registered GUI controls are valid. FALSE A validation error occurred. ═══ WtkValidateObjectValueTable - Remarks ═══ If validation should take place on close of the settings notebook, this function should not be called directly by the code of your WPS class directly. Instead, the notebook frame should be registered with WtkRegisterSettingsNotebook during the processing of _wpAddSettingsPages(). This will let Settings Manager subclass the notebook frame and call WtkValidateObjectValueTable automatically when the notebook is closed. If it is required to validate GUI controls also on other events, WtkValidateObjectValueTable can still be used for that. Note however that it is not possible to validate only for one dialog registered with Settings Manager. Instead, always the registered controls of all registered dialogs are validated - this may result in switching to another notebook page, if there a GUI control contains invalid contents! ═══ WtkValidateObjectValueTable - Related functions ═══ Related Functions none ═══ 8.91. WtkWriteFile ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkWriteFile - Syntax ═══ This function writes a data buffer to a file. The file can either be overwritten or the data can be appended to the file. #define INCL_WTKUTLFILE #include PSZ pszName; /* Address of the ASCIIZ pathname, which is to be overwritten by the given data. */ PSZ pszBuffer; /* The address of a buffer, which is to be written to a file. */ ULONG ulBuflen; /* The length, in bytes, of the buffer described by pszBuffer. */ BOOL fAppend; /* Flag for appending the data to a file rather than overwriting the contents of an existing file. */ APIRET ulrc; /* Return Code. */ ulrc = WtkWriteFile( pszName, pszBuffer, ulBuflen, fAppend); ═══ WtkWriteFile - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ pathname, which is to be overwritten by the given data. The path name may contain ?: for the drive in order to write the file on the boot drive. ═══ WtkWriteFile - Parameter pszBuffer ═══ pszBuffer (PSZ) - input The address of a buffer, which is to be written to a file. ═══ WtkWriteFile - Parameter ulBuflen ═══ ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. ═══ WtkWriteFile - Parameter fAppend ═══ fAppend (BOOL) - input Flag for appending the data to a file rather than overwriting the contents of an existing file. ═══ WtkWriteFile - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ pathname, which is to be overwritten by the given data. The path name may contain ?: for the drive in order to write the file on the boot drive. pszBuffer (PSZ) - input The address of a buffer, which is to be written to a file. ulBuflen (ULONG) - input The length, in bytes, of the buffer described by pszBuffer. fAppend (BOOL) - input Flag for appending the data to a file rather than overwriting the contents of an existing file. ulrc (APIRET) - returns Return Code. WtkWriteFile returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosOpen  DosWrite ═══ WtkWriteFile Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkWriteFile returns one of the following return codes: 0 NO_ERROR 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosOpen  DosWrite ═══ WtkWriteFile - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to write the file on the boot drive. ═══ WtkWriteFile - Related functions ═══ Related Functions none ═══ 8.92. WtkWriteObjectValueTable ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkWriteObjectValueTable - Syntax ═══ This function reads the GUI controls of the given settings notebookpage and updates the corresponding values in the object valuetable. #define INCL_WTKSETTINGS #include HVALUETABLE hvt; /* Valuetable handle. */ HWND hwndDialog; /* Dialog handle of the settings notebook page. */ BOOL fResult; /* Success indicator. */ fResult = WtkWriteObjectValueTable( hvt, hwndDialog); ═══ WtkWriteObjectValueTable - Parameter hvt ═══ hvt (HVALUETABLE) - input Valuetable handle. ═══ WtkWriteObjectValueTable - Parameter hwndDialog ═══ hwndDialog (HWND) - input Dialog handle of the settings notebook page. ═══ WtkWriteObjectValueTable - Parameters ═══ hvt (HVALUETABLE) - input Valuetable handle. hwndDialog (HWND) - input Dialog handle of the settings notebook page. fResult (BOOL) - returns Success indicator. TRUE Values could be transferred to the object valuetable. FALSE An error occurred. ═══ WtkWriteObjectValueTable Return Value - fResult ═══ fResult (BOOL) - returns Success indicator. TRUE Values could be transferred to the object valuetable. FALSE An error occurred. ═══ WtkWriteObjectValueTable - Remarks ═══ This function is to be called in the WM_DESTROY message handling of the window procedure being used for the settings notebookpages, so that the values of the GUI controls are written to the object valuetable, when the notebook is closed. ═══ WtkWriteObjectValueTable - Related functions ═══ Related Functions none ═══ 8.93. WtkWriteStringEa ═══ Select an item:  Syntax  Parameters  Returns  Remarks  Related Functions ═══ WtkWriteStringEa - Syntax ═══ This function attaches a string extended attribute to a file or directory. #define INCL_WTKEAS #include PSZ pszName; /* Address of the ASCIIZ path name of the file or directory. */ PSZ pszEaName; /* Address of the ASCIIZ name of the extended attribute. */ PSZ pszEaValue; /* The address of a string to be written. */ APIRET ulrc; /* Return Code. */ ulrc = WtkWriteStringEa( pszName, pszEaName, pszEaValue); ═══ WtkWriteStringEa - Parameter pszName ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to search the file or directory on the boot drive. The name may not include wildcards. ═══ WtkWriteStringEa - Parameter pszEaName ═══ pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. ═══ WtkWriteStringEa - Parameter pszEaValue ═══ pszEaValue (PSZ) - input The address of a string to be written. ═══ WtkWriteStringEa - Parameters ═══ pszName (PSZ) - input Address of the ASCIIZ path name of the file or directory. The path name may contain ?: for the drive in order to search the file or directory on the boot drive. The name may not include wildcards. pszEaName (PSZ) - input Address of the ASCIIZ name of the extended attribute. pszEaValue (PSZ) - input The address of a string to be written. ulrc (APIRET) - returns Return Code. WtkWriteStringEa returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE 8 ERROR_NOT_ENOUGH_MEMORY 13 ERROR_INVALID_DATA 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSetPathInfo ═══ WtkWriteStringEa Return Value - ulrc ═══ ulrc (APIRET) - returns Return Code. WtkWriteStringEa returns one of the following return codes: 0 NO_ERROR 6 ERROR_INVALID_HANDLE 8 ERROR_NOT_ENOUGH_MEMORY 13 ERROR_INVALID_DATA 87 ERROR_INVALID_PARAMETER or return codes of the following functions  DosSetPathInfo ═══ WtkWriteStringEa - Remarks ═══ This function supports boot drive recognition. Specify ?: for the drive in order to open the file or directory on the boot drive. This function is meant to provide you with easy handling of string extended attributes. The drawback is that for simplicity you cannot  attach more than one string to the specified extended attribute (but that is what is needed for most cases anyway)  write through (ommit the cache)  mark the extended attribute as critical If these limitations does not meet your requirements, use the move flexible call WtkPutEaValue instead. ═══ WtkWriteStringEa - Related functions ═══ Related Functions none ═══ 9. Data Types ═══ The following are all the data types used by the Workplace Shell Toolkit. Data types of the WPS Toolkit  CBINITCONTROL  CBQUERYINDEX  CBQUERYSTRING  CBQUERYTARGETBUF  CBQUERYVALUE  CBQUERYVALUEINFO  CBREPORTCHANGED  CBREPORTDESTROYED  CBREPORTERROR  CBREPORTINIT  CBREPORTSAVED  CBVALIDATE  FNCB  HEA  HMMF  HSETTINGTABLE  HVALUETABLE Data types from the Toolkit for OS/2 WARP or compiler runtime  APIRET  BOOL  BYTE  CDATE  CHAR  CTIME  DATETIME  FDATE  FILESTATUS3  FTIME  HDIR  HFILE  HMODULE  HWND  LONG  MPARAM  MRESULT  PFN  PFNWP  PSZ  PVOID  SHORT  UCHAR  ULONG  USHORT  VOID  time_t ═══ 9.1. APIRET ═══ Unsigned integer in the range 0 through 4 294 967 295. typedef unsigned long APIRET; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.2. BOOL ═══ Boolean. Valid values are:  FALSE, which is 0  TRUE, which is 1 typedef unsigned long BOOL; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.3. BYTE ═══ A byte. typedef unsigned char BYTE; ═══ 9.4. CBINITCONTROL ═══ Structure for callback request to initialize a GUI control of a settings notebookpage. typedef struct _CBINITCONTROL { USHORT usDialogid; /* out - id of dialog */ USHORT usControlid; /* out - id of control */ HWND hwndDialog; /* out - handle of dialog */ HWND hwndControl; /* out - handle of control */ } CBINITCONTROL, *PCBINITCONTROL; ═══ 9.5. CBQUERYINDEX ═══ Structure for callback request to translate strings to array indicees for a (sub)value of a setting. typedef struct _CBQUERYINDEX { PVOID pvObjectInstance; /* out - somSelf of object instance */ ULONG ulSettingId; /* out - id of setting */ PSZ pszName; /* out - name of setting */ PSZ pszValue; /* out - string value to be translated */ ULONG ulValueIndex; /* out - index of subvalue */ ULONG ulStringIndex; /* in - index to be used */ } CBQUERYINDEX, *PCBQUERYINDEX; /* return TRUE if processed, else FALSE */ ═══ 9.6. CBQUERYSTRING ═══ Structure for callback request to translate array indicees to strings for a (sub)value of a setting. typedef struct _CBQUERYSTRING { PVOID pvObjectInstance; /* out - somSelf of object instance */ ULONG ulSettingId; /* out - id of setting */ PSZ pszName; /* out - name of setting */ ULONG ulStringIndex; /* out - index to be translated */ ULONG ulValueIndex; /* out - index of subvalue */ CHAR szValue[ _STM_MAX_SETTINGSVALUE];/* in - string value to be used */ } CBQUERYSTRING, *PCBQUERYSTRING; /* return TRUE if processed, else FALSE */ ═══ 9.7. CBQUERYTARGETBUF ═══ Structure for callback request to query a target buffer for a (sub)value of a setting. typedef struct _CBQUERYTARGETBUF { PVOID pvObjectInstance; /* out - somSelf of object instance */ PSZ pszName; /* out - name of setting */ ULONG ulSettingId; /* out - id of setting */ ULONG ulValueIndex; /* out - index of subvalue */ /* (only > 0 for multivalue settings) */ ULONG ulBufMax; /* #in - len of target buffer */ PVOID pvTarget; /* #in - target buffer */ } CBQUERYTARGETBUF, *PCBQUERYTARGETBUF; /* return TRUE to use the returned data */ ═══ 9.8. CBQUERYVALUE ═══ Structure for callback request to let the WPS class update the target buffer(s) for a given setting, before it is read for determining the current settings. typedef struct _CBQUERYVALUE { PVOID pvObjectInstance; /* out - somSelf of object instance */ ULONG ulSettingId; /* out - id of setting */ PSZ pszName; /* out - name of setting */ ULONG ulQueryIndex; /* out - index of query */ } CBQUERYVALUE, *PCBQUERYVALUE; ═══ 9.9. CBQUERYVALUEINFO ═══ Structure for callback request to query infos about a given (sub)value of a setting. typedef struct _CBQUERYVALUEINFO { PSZ pszName; /* out - name of setting */ ULONG ulSettingId; /* out - id of setting */ ULONG ulValueIndex; /* out - index of subvalue */ ULONG ulValueType; /* #in - type of value - see VALUETYPE_* */ USHORT usDialogid; /* in - id of dialog containing control */ USHORT usControlid; /* in - id of control */ PFNWP pfnwpSubclass; /* in - subclass window proc for control */ PSZ pszDetailsTitle; /* in - title of folderdetails view */ } CBQUERYVALUEINFO, *PCBQUERYVALUEINFO; ═══ 9.10. CBREPORTCHANGED ═══ Structure for callback request to inform the WPS class that a given setting has changed. typedef struct _CBREPORTCHANGED { PVOID pvObjectInstance; /* out - somSelf of object instance */ ULONG ulSettingId; /* out - id of setting */ PSZ pszName; /* out - name of setting */ } CBREPORTCHANGED, *PCBREPORTCHANGED; ═══ 9.11. CBREPORTDESTROYED ═══ Structure for callback request to inform the WPS class that the settingstable has been destroyed. typedef struct _CBREPORTDESTROYED { BOOL fDestroyed; /* no data really required here yet */ } CBREPORTDESTROYED, *PCBREPORTDESTROYED; ═══ 9.12. CBREPORTERROR ═══ Structure for callback request to inform the WPS class that a given control of a settings notebookpage has failed the validation. typedef struct _CBREPORTERROR { PVOID pvObjectInstance; /* out - somSelf of object instance */ ULONG ulSettingId; /* out - id of setting */ PSZ pszName; /* out - name of setting */ USHORT usDialogid; /* out - id of dialog */ USHORT usControlid; /* out - id of control */ HWND hwndDialog; /* out - handle of dialog */ HWND hwndControl; /* out - handle of control */ } CBREPORTERROR, *PCBREPORTERROR; /* return TRUE to ignore error */ ═══ 9.13. CBREPORTINIT ═══ Structure for callback request to inform the WPS class that the settings table has been initialized. typedef struct _CBREPORTINIT { BOOL fInitialized; /* no data really required here yet */ } CBREPORTINIT, *PCBREPORTINIT; ═══ 9.14. CBREPORTSAVED ═══ Structure for callback request to inform the WPS class that the settings have been saved. typedef struct _CBREPORTSAVED { BOOL fSaved; /* no data really required here yet */ } CBREPORTSAVED, *PCBREPORTSAVED; ═══ 9.15. CBVALIDATE ═══ Structure for callback request to let the WPS class validate a settings (sub)value. typedef struct _CBVALIDATE { PVOID pvObjectInstance; /* out - somSelf of object instance */ ULONG ulSettingId; /* out - id of setting */ PSZ pszName; /* out - name of setting */ PSZ pszValue; /* out - name of value to be validated */ ULONG ulValueIndex; /* out - index of subvalue */ BOOL fResult; /* in - result of validation */ } CBVALIDATE, *PCBVALIDATE; /* return TRUE if your callback validates, */ ═══ 9.16. CDATE ═══ Structure that contains date information for a data element in the details view of a container control. typedef struct _CDATE { UCHAR day; /* Current day. */ UCHAR month; /* Current month. */ USHORT year; /* Current year. */ } CDATE; typedef CDATE *PCDATE; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.17. CHAR ═══ Single-byte character. #define CHAR char ═══ 9.18. CTIME ═══ Structure that contains time information for a data element in the details view of a container control. typedef struct _CTIME { UCHAR hours; /* Current hour. */ UCHAR minutes; /* Current minute. */ UCHAR seconds; /* Current second. */ UCHAR ucReserved; /* Reserved. */ } CTIME; typedef CTIME *PCTIME; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.19. DATETIME ═══ Date and time data structure. typedef struct _DATETIME { UCHAR hours; /* Current hour, using values 0 through 23. */ UCHAR minutes; /* Current minute, using values 0 through 59. */ UCHAR seconds; /* Current second, using values 0 through 59. */ UCHAR hundredths; /* Current hundredths of a second, using values 0 through 99. */ UCHAR day; /* Current day of the month, using values 1 through 31. */ UCHAR month; /* Current month of the year, using values 1 through 12. */ USHORT year; /* Current year. */ SHORT timezone; /* The difference in minutes between the current time zone and Greenwich Mean Time (GMT). */ UCHAR weekday; /* Current day of the week, using values 0 through 6. */ } DATETIME; typedef DATETIME *PDATETIME; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.20. FDATE ═══ Date data structure for file-system functions. typedef struct _FDATE { USHORT day:5; /* Binary day for directory entry. */ USHORT month:4; /* Binary month for directory entry. */ USHORT year:7; /* The number of years since 1980 for this directory entry. */ } FDATE; typedef FDATE *PFDATE; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.21. FILESTATUS3 ═══ Level 1 (32-bit) (FIL_STANDARD) information. typedef struct _FILESTATUS3 { FDATE fdateCreation; /* Date of file creation. */ FTIME ftimeCreation; /* Time of file creation. */ FDATE fdateLastAccess; /* Date of last access. */ FTIME ftimeLastAccess; /* Time of last access. */ FDATE fdateLastWrite; /* Date of last write. */ FTIME ftimeLastWrite; /* Time of last write. */ ULONG cbFile; /* File size (end of data). */ ULONG cbFileAlloc; /* File allocated size. */ ULONG attrFile; /* Attributes of the file. */ } FILESTATUS3; typedef FILESTATUS3 *PFILESTATUS3; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.22. FNCB ═══ Pointer to a callback procedure for the Settings Manager. typedef BOOL (FNCB)(ULONG ulAction, PVOID pvData, PVOID pvObjectInstance, PVOID pvObjectData); typedef FNCB *PFNCB; ═══ 9.23. FTIME ═══ Time data structure for file-system functions. typedef struct _FTIME { USHORT twosecs:5; /* Binary number of two-second increments. */ USHORT minutes:6; /* Binary number of minutes. */ USHORT hours:5; /* Binary number of hours. */ } FTIME; typedef FTIME *PFTIME; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.24. HDIR ═══ Value (32-bit) used as a directory handle. typedef LHANDLE HDIR; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.25. HEA ═══ Extended attibute handle. typedef LHANDLE HEA; ═══ 9.26. HFILE ═══ File handle. typedef LHANDLE HFILE; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.27. HMMF ═══ Memory mapped file handle typedef LHANDLE HMMF; ═══ 9.28. HMODULE ═══ Module handle. typedef LHANDLE HMODULE; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.29. HSETTINGTABLE ═══ Settingstable handle. typedef LHANDLE HSETTINGTABLE; ═══ 9.30. HVALUETABLE ═══ Valuetable handle. typedef LHANDLE HVALUETABLE; ═══ 9.31. HWND ═══ Window handle. typedef LHANDLE HWND; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.32. LONG ═══ Signed integer in the range -2 147 483 648 through 2 147 483 647. #define LONG long This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.33. MPARAM ═══ A 4-byte message-dependent parameter structure. typedef VOID *MPARAM; Certain elements of information, placed into the parameters of a message, have data types that do not use all four bytes of this data type. The rules governing these cases are: BOOL The value is contained in the low word and the high word is 0. SHORT The value is contained in the low word and its sign is extended into the high word. USHORT The value is contained in the low word and the high word is 0. NULL The entire four bytes are 0. The structure of this data type depends on the message. For details, see the description of the particular message. This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.34. MRESULT ═══ A 4-byte message-dependent reply parameter structure. typedef VOID *MRESULT; Certain elements of information, placed into the parameters of a message, have data types that do not use all four bytes of this data type. The rules governing these cases are: BOOL The value is contained in the low word and the high word is 0. SHORT The value is contained in the low word and its sign is extended into the high word. USHORT The value is contained in the low word and the high word is 0. NULL The entire four bytes are 0. The structure of this data type depends on the message. For details, see the description of the particular message. This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.35. PFN ═══ Pointer to a procedure. typedef _PFN *PFN; In the OS/2 toolkit header file, this is a two-part definition as shown below: typedef int (APIENTRY _PFN) (); typedef _PFN *PFN; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.36. PFNWP ═══ Pointer to a window procedure. This is the standard function definition for window procedures. typedef FNWP *PFNWP; The first argument (HWND) is the handle of the window receiving the message. The second argument (ULONG) is a message identifier. The third argument (MPARAM) is the first message parameter (mp1). The fourth argument (MPARAM) is the second message parameter (mp2). The function returns an MRESULT. Each message has a specific set of possible return codes. The window procedure must return a value that is appropriate for the message being processed. In the header file, this is a two-part definition as shown below: typedef MRESULT (EXPENTRY FNWP)(HWND, ULONG, MPARAM, MPARAM); typedef FNWP *PFNWP; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.37. PSZ ═══ Pointer to a null-terminated string. If you are using C++ **, you may need to use PCSZ. typedef unsigned char *PSZ; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.38. PVOID ═══ Pointer to a data type of undefined format. typedef VOID *PVOID; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.39. SHORT ═══ Signed integer in the range -32 768 through 32 767. #define SHORT short This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.40. UCHAR ═══ Single-byte unsigned character or unsigned integer in the range 0 through 255. typedef unsigned char UCHAR; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.41. ULONG ═══ 32-bit unsigned integer in the range 0 through 4 294 967 295. typedef unsigned long ULONG; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.42. USHORT ═══ Unsigned integer in the range 0 through 65 535. typedef unsigned short USHORT; This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.43. VOID ═══ A data area of undefined format. #define VOID void This data type is being introduced by the OS/2 Warp Toolkit. ═══ 9.44. time_t ═══ Current calendar time. typedef long time_t; This data type is being introduced by the compiler runtime. ═══ 10. Text Message Files (TMF) ═══ The Text Message File API of the Workplace Shell Toolkit provides an alternative to the OS/2 message files, which have several drawbacks:  they need to be compiled with the mkmsgf utility  testing is complicated  some APIs like the SysGetMessage of REXX call keep the file open until the shell closes, where the REXX script is running in For that reasons many programs use plain text files, but also this has a drawback, as the complete file has to be searched for every message again and again. Here the Text Message File (TMF) concept jumps in, combining the convenience of having editable text files while avoiding to search the whole file for every message request. Text message files complying to the TMF format can be used with the WtkGetTextMessage, call. When a message is requested by this, the following actions are performed:  the text message file is checked for being modified (compared with a previously saved timestamp)  if modified, - an internal message id table is compiled and saved as extended attribute - the current timestamp is saved as an extended attribute  the requested message is located by the internal message id table and returned to the caller So in most of the times the internal message id table is used to determine the location of a message within the text message file, which decreases the amount of required file handling drastically. Further releases of the Workplace Shell Toolkit will be extended by a similar API, either holding the file open and/or reading the file into memory, once more increasing the access to messages. ═══ 10.1. text message file format ═══ The Text Message Files (TMF) must comply to the following format in order to let WtkGetTextMessage retrieve messages out of it:  messages start with a message id in the first column of a line. The message id is assembled by : - the string <-- - the alphanumeric message id - the string --> A valid message id would be: <--MyString001-->  before the first message comments may be included within the file, started with a semikolon in the first column. Note: - After the first message id all comments are taken being part of messages !  messages may span several lines, where the carriage return and linefeed characters (except of the last line of a message) will become part of the message. So if you don't eant to have linefeeds in your message, make sure that they don't span lines, no matter how long the line will ever get  placeholders from %1 to %1 in the message text are replaced if values for those are handed over to WtkGetTextMessage in the pointer table referred to by the pTable parameter. In opposite to the DosGetMessage call text replacement is performed even if not enough parameters are supplied - where values are missing, the placeholder remains unmodified within the message text. ═══ 11. Settings and Details Manager ═══ The Settings and Details Manager API of the Workplace Shell Toolkit encapsulates the complexity of handling object settings and details by automating the following tasks of a Workplace Shell object class:  handling settings strings (like "NAME1=value1;NAME2=value21,value22;") per object class  handling values for all of the settings per object intance.  automatic transporting object instance setting values to the settings notebookpages of the object instance and vice versa.  providing an automatic translation of setup strings sent to _wpSetup into changes of the settings values of an object instance, with automatic update of open setting notebook pages, if desired.  querying the complete settings implemented by the WPS class for an object instance in a settings string, greatly simplifying the code for _wpSaveState and _wpRestoreState. While _wpSaveState can save the settings as one string, the _wpRestoreState just has to send the previously saved settings string to _wpSetup to initialize the object on next Workplace Shell startup. Select one of the following topics : Handling of object settings in general Handling of object settings with the Worplace Shell Toolkit  Callback function for the Settings Manager API  Supported value types Handling of object details in general Handling of object details with the Worplace Shell Toolkit ═══ 11.1. Handling of object settings in general ═══ The general handling of object settings is divided into several parts: creation/awakening of an object _wpclsInitData - Initializing the meta class data Here variables used by all object instances are being set up. _wpInitData - Initializing the object instance data Here the variables are initnalized, of which every object instance has its own copy. _wpRestoreState - restoring previously settings values get previously saved values for all settings and store them in the instance variables of the object. opening of the settings notebook / selecting a notebook page / performing undo _wpAddSettingsPages - add own setting notebook pages a WPS class adds setting notebook pages implementing GUI conrols for each value of the supported settings. When adding new notebook pages, a window message procedure has to be specified for each page. When using the Settings and Details Manager API of the Workplace Shell Toolkit, mostly one window message procedure is sufficient for all settings notebook pages that a WPS class implements. Note:  The Settings and Details Manager API of the Workplace Shell Toolkit does not provide a function for this. This part has to be coded conventionally and is enlisted here for clarity. WM_INITDLG in window message procedure - initialize dialog fill all GUI controls with the appropriate values that are stored in the instance variables of the object. WM_COMMAND for undo pushbutton in window message procedure - restore to current values fill all GUI controls with the appropriate values that are stored in the instance variables of the object. closing the settings notebook / saving the current values WM_DESTROY in window message procedure - destroy the dialog get values from all GUI controls, validate them and store them in the instance variables of the object. _wpSaveState - saving current settings values save all values of the instance variables of the object. external setup of an object _wpSetup (_wpSetupOnce) - modifying the setttings values via settings strings evaluate all settings strings. If they apply to the WPS class and contain valid values, store them in the instance variables of the object. deletion/making dormant of an object _wpUnInitData - Deinitializing the object instance data Free all resources being used by the object instance, e.g memory. _wpclsUnInitData - Initializing the meta class data Free all resources being used together by all object instance, e.g memory. ═══ 11.2. Handling of object settings with the Worplace Shell Toolkit ═══ Use the Workplace Shell Toolkit API as follows to automate the settings handling: creation/awakening of an object _wpclsInitData - Initializing the meta class data Create a settings table and fill it with definitions for all uspported settings  WtkCreateClassSettingsTable - create the class settings table and specify the address of a callback function.  WtkAddClassSetting - call this once for each setting that the WPS class should support.  WtkCloseClassSettingsTable - close the table for usage by object instances _wpInitData - Initializing the object instance data initialize all instance variables Create a value table for the object instance. This table contains pointers to the instance variables maintained by the WPS class.  WtkCreateObjectValueTable - create the object value table _wpRestoreState - restoring previously settings values get previously saved values for all settings and store them in the instance variables of the object by calling _wpSetup. opening of the settings notebook / selecting a notebook page / performing undo _wpAddSettingsPages - add own setting notebook pages a WPS class adds setting notebook pages implementing GUI conrols for each value of the supported settings. Specify a single window message procedure for all settings notebook pages that a WPS class implements. Also, pass the handle to the object value table as a parameter to the window procedure, so that it can be stored with WinSetWindowULong to position QWL_USER. This handle is required within the window procedure to call any of the Wtk APIs for object handling. if desired, call WtkRegisterSettingsNotebook to register the notbook for automatic validation of all notebookpages, when the when the notebook is closed. Of course onle these pages can be validated, which have been registered with WtkRegisterSettingsDialog during their creation. WM_INITDLG in window message procedure - initialize dialog prepare the dialog for automatic update by the setting smanager API and setup all GUI controls  WtkRegisterSettingsDialog - register the dialog for automatic update of GUI controls and object instance values  WtkReadObjectValueTable - fill all GUI controls in this dialog with the appropriate values that are stored in the instance variables of the object. You may also use WinSendMsg with WM_COMMAD for the undo button to accomplish this task, as this also calls WtkReadObjectValueTable, see below. WM_COMMAND for undo pushbutton in window message procedure - restore to current values refill all GUI controls in this dialog with the appropriate values that are stored in the instance variables of the object.  WtkReadObjectValueTable - fill all GUI controls with the appropriate values that are stored in the instance variables of the object. closing the settings notebook / saving the current values WM_DESTROY in window message procedure - destroy the dialog get values from all GUI controls, validate them and store them in the instance variables of the object.  WtkWriteObjectValueTable - fill all GUI controls with the appropriate values of the value table. _wpSaveState - saving current settings values save all values of the instance variables of the object.  WtkQueryObjectSettings - query all settings as one string that can easily be saved and further easily be restored by sending it to _wpSetup (see external setup of an object below). external setup of an object _wpSetup (_wpSetupOnce) - modifying the setttings values via settings strings evaluate all settings strings. If they apply to the WPS class and contain valid values, store them in the instance variables of the object.  WtkEvaluateObjectSettings - validates settings values and updates the object value table. deletion/making dormant of an object _wpUnInitData - Deinitializing the object instance data Free all resources being used by the object instance.  WtkDestroyObjectValueTable - frees all memory being used by the settings manager API for the object instance _wpclsUnInitData - Initializing the meta class data Free all resources being used together by all object instance.  WtkDestroyClassSettingsTable - frees all memory being used by the settings manager API for the object class. ═══ 11.2.1. Callback function for the Settings Manager API ═══ You need to specify a callback function when creating a class settings and details table with WtkCreateClassSettingsTable. This callback has the prototype FNCB. Depending on ulAction the callback has to perform the following function: STM_CALLBACK_REPORTINIT - pvData is PCBREPORTINIT optional - initialize all data required by the callback. You might want to read initialization files or other data being required to fill GUI values etc.. This callback is being invoked on WtkCreateClassSettingsTable, which is in turn to be called on _wpclsInitData. Note:  The parameters pvObjectInstance and pvObjectData are NULL for this callback ! STM_CALLBACK_QUERYVALUEINFO - pvData is PCBQUERYVALUEINFO mandatory - for each (sub)value of a setting pass information to the API about the setting and the GUI dialog and control IDs for automatic transport of the settings (sub)value. All values, for which this information is not passed back, are ignored and not handled in any way. Most important is the value type for the settings value. See also Supported value types STM_CALLBACK_QUERYTARGETBUF - pvData is PCBQUERYTARGETBUF mandatory - for each (sub)value of a setting pass the pointer to the object instance variable. STM_CALLBACK_VALIDATE - pvData is PCBVALIDATE optional - for each (sub)value of a setting validate the provided value. Return TRUE The result of the validation is returned in fResult of PCBQUERYVALIDATE FALSE The value is to be validated with the standard validation scheme for the given value type. If no standard validation scheme exists, the value is always valid. See also Supported value types STM_CALLBACK_REPORTCHANGED - pvData is PCBREPORTCHANGED optional - for each setting take an appropriate action, when the reported setting has changed either by passed setup strings (WtkEvaluateObjectSettings) or modified GUI controls (WtkWriteObjectValueTable). When either function exits, a last change report is generated with no name and id specified in order to enable any action required after all changes have been saved. STM_CALLBACK_QUERYVALUE - pvData is PCBQUERYVALUE optional - for each index of a setting set the target buffer for the appropriate value. This callback is being invoked n times for each setting, where n is equal to the parameter ulQueryIndex of WtkAddClassSetting. This value is normally set to one, and thus this callback needs not to be handled. STM_CALLBACK_QUERYINDEX - pvData is PCBQUERYINDEX mandatory - for each (sub)value of a setting that is of type STM_VALUETYPE_INDEX or STM_VALUETYPE_INDEXITEM, this callback passes a string to the WPS class, which needs to be translated by the callback procedure to a numeric value. For STM_VALUETYPE_INDEX, the string may come from either a GUI control or a settings string, for STM_VALUETYPE_INDEXITEM the string can come only from a settings string. The index value is stored in the target buffer reported on callback STM_CALLBACK_QUERYTARGETBUF (mostly the object member variable). STM_CALLBACK_QUERYSTRING - pvData is PCBQUERYSTRING mandatory - for each (sub)value of a setting that is of type STM_VALUETYPE_INDEX or STM_VALUETYPE_INDEXITEM, this callback passes a numeric value to the WPS class, which needs to be translated by the callback procedure to a string representing the numeric value. For STM_VALUETYPE_INDEX, the string is used to either update a GUI control or be added to a settings string, for STM_VALUETYPE_INDEXITEM the string is only to be used to be added to a settings string. The index value is taken from the target buffer reported on callback STM_CALLBACK_QUERYTARGETBUF (mostly the object member variable). STM_CALLBACK_INITCONTROL - pvData is PCBINITCONTROL optional - for each GUI control being associated to a (sub)value of a setting, initialize the GUI control to your needs. Mostly valuable for filling listboxes etc.. More, you can specify the address of a subclass window procedure for a given control. STM_CALLBACK_REPORTERROR - pvData is PCBREPORTERROR optional - for each GUI control not containing a valid value, when WtkValidateObjectValueTable was called. This enables the WPS class to popup a message box. Note:  The WPS class normally does not call WtkValidateObjectValueTable directly. Instead, to let the Settings and Details Manager API automatically validate all setting notebook dialog pages registered with WtkRegisterSettingsDialog on close of the settings notebook, call WtkRegisterSettingsNotebook within the _wpAddSettingsPages method. STM_CALLBACK_REPORTSAVED - pvData is PCBREPORTSAVED optional - for taking an appropriate action, when the object setting values have been saved with WtkWriteObjectValueTable STM_CALLBACK_REPORTDESTROYED - pvData is PCBREPORTDESTROYED optional - free all resources being held by the callback. This callback is being invoked on WtkDestroyClassSettingsTable, which is in turn to be called on _wpclsUnInitData. Note:  The parameters pvObjectInstance and pvObjectData are NULL for this callback ! ═══ 11.2.2. Supported value types ═══ The Settings and Details Manager API of the Workplace Shell Toolkit supports several types of values. The value type must be specified on the callback with ulAction equal to STM_CALLBACK_QUERYVALUEINFO (pvData for this callback is PCBQUERYVALUEINFO). The following value types are supported: ┌───────────────────────┬─────────────────┬────────┬─────────────────────────┐ │type │standard │target │supported GUI controls │ │ │validation │buffer │ │ │ │provided │ │ │ ├───────────────────────┼─────────────────┼────────┼─────────────────────────┤ │STM_VALUETYPE_STRING │No, always valid.│CHAR[] │- except │ │ │ │ │WC_*SLIDER. WC_COMBOBOX │ │ │ │ │and WC_SPINBUTTON only as│ │ │ │ │listbox │ ├───────────────────────┼─────────────────┼────────┼─────────────────────────┤ │STM_VALUETYPE_INDEX │Yes, the │LONG │ │ │ │translation from │ │ │ │ │string to index │ │ │ │ │and vice versa │ │ │ │ │may not fail. │ │ │ ├───────────────────────┼─────────────────┼────────┼─────────────────────────┤ │STM_VALUETYPE_INDEXITEM│Yes, the │LONG │WC_LISTBOX and │ │ │translation from │ │WC_COMBOBOX │ │ │string to index │ │Can currently not be used│ │ │and vice versa │ │for details !!! │ │ │may not fail. │ │ │ ├───────────────────────┼─────────────────┼────────┼─────────────────────────┤ │STM_VALUETYPE_LONG │No, always valid.│LONG │ │ ├───────────────────────┼─────────────────┼────────┼─────────────────────────┤ │STM_VALUETYPE_TRUEFALSE│Yes, the value │BOOL │ except │ │ │must be either │ │WC_*SLIDER │ │ │TRUE or FALSE │ │ │ │ │(case │ │ │ │ │insensitive). │ │ │ ├───────────────────────┼─────────────────┼────────┼─────────────────────────┤ │STM_VALUETYPE_YESNO │Yes, the value │BOOL │ except │ │ │must be either │ │WC_*SLIDER │ │ │YES or NO (case │ │ │ │ │insensitive). │ │ │ ├───────────────────────┼─────────────────┼────────┼─────────────────────────┤ │STM_VALUETYPE_ONOFF │Yes, the value │BOOL │ except │ │ │must be either ON│ │WC_*SLIDER │ │ │or OFF (case │ │ │ │ │insensitive). │ │ │ └───────────────────────┴─────────────────┴────────┴─────────────────────────┘ The following value types are reserved for using with details only:  STM_VALUETYPE_CDATE  STM_VALUETYPE_CTIME ═══ 11.3. Handling of object details in general ═══ The general handling of object details is divided into several parts: initializing the meta class _wpclsQueryDetailsInfo - Retrieving information about provided details Here the Workplace Shell queries, what details are provided by the meta class. This includes type information, layout information for the details view and the title for the column of every detail. This method is mostly called during the initialization of the meta class. updating the details view of a folder that contains an object _wpQueryDetailsData - Querying the current details data Here the Workplace Shell queries the current set of data of an object instance, whenever it has changed. ═══ 11.4. Handling of object details with the Worplace Shell Toolkit ═══ Use the Workplace Shell Toolkit API as follows to automate the details handling: initializing the meta class _wpclsQueryDetailsInfo - Retrieving information about provided details Call WtkQueryClassDetailsInfo in order to let the Settings and Details Manager report all provided details for the given WPS class. Note that when _wpclsQueryDetailsInfo is being called, your WPS class already has done the following things:  it has registered all details by either calling - WtkAddClassSetting or - WtkAddClassDetail during the initialization of the meta class, where the order of of the registration determines the order, in that the details apper in the details view.  for all details provided a value for pszDetailsTitle on the STM_CALLBACK_QUERYVALUEINFO callback within your Callback function for the Settings Manager API. updating the details view of a folder that contains an object _wpQueryDetailsData - Querying the current details data Call WtkQueryObjectDetailsData in order to let the Settings and Details Manager report all current detail data for the given WPS class. ═══ 12. Extended Attributes Manager ═══ The Extended Attributes Manager API of the Workplace Shell Toolkit is designed to greatly ease the handling of extended attributes. While the attribute data structures that can be read and/or written with several OS/2 control programs, provide great flexibility, the setup of these structures require time consuming coding and testing, and such each time that you are required to handle extended attributes. In order to have a simplified API, the API of the Workplace Shell Toolkit differs from conventional extended attribute handling in several ways:  You can only read or write one extended attribute (either with a single or a list of multiple values) at a time. Since this is, what you will do in most cases anyway, this will not really restrict you a lot and this step alone makes the following point possible:  You never have to deal with the binary structures again, if you use the extended attributes API of the Workplace Shell Toolkit. All this handling is completely done for you, while you just provide values for a given extended attribute in a source buffer to let it be written or appended, or you ask for values to be returned in a target buffer for a specific type of extended attributes. The EAT_* type values and some knowledge about organization of extended attributes are the only things that you are still requiring in order to setup extended attributes for a given file or directory.  Normally, you are required to read, modify and write an extended attribute, if you do not even just replace it with a completely new value. Having said this, the Workplace Shell Toolkit provides you both with three APIs to let you do also these single steps one after another, but also with a single step API to accomplish this task in one step. Since writing exactly one value to an extended attribute is exactly, what most Workplace Shell classes need to do, this simplifies your coding a lot. And even if you call these APIs for several extended attributes one after another (compared to setup a complex structure and write it with only one call to a control program API), the effective use of the OS/2 filesystem cache will reduce the overhead of subsequent disk I/O accesses. See the following sections:  Reading an extended attribute  Writing an extended attribute ═══ 12.1. Reading an extended attribute ═══ The following APIs are provided to read an extended attribute of a given file or directory: WtkQueryEaSize determines the size of all values of the given EA. WtkReadEa reads the value (list) of a given extended attribute into memory. Use the following APIs to query all or certain of these values:  WtkFindFirstEaValue  WtkFindNextEaValue Note:  Call WtkCloseEa in order to release the memory occupied by the value (list) of the extended attribute afterwards !  an in-memory value (list) of an extended attribute being read by WtkReadEa can be extended by calling WtkAppendEaValue and saved to disk by WtkSaveEa. WtkGetNextEaValue In order to easily query all values of an extended attribute matching a given type. call this API in a simple while loop, until it returns ERROR_NO_MORE_FILES. WtkGetNextEaValue will call  WtkFindNextEaValue,  WtkFindNextEaValue and  WtkCloseEa for you to accomplish this task. Make sure to either call WtkGetNextEaValue, until it returns ERROR_NO_MORE_FILES, or call WtkCloseEa yourself to free up the memory occupied by the temporary in-memory value (list) for the extended attribute. WtkReadStringEa This API is even simpler to use compared to WtkGetNextEaValue when it comes to read a string extended attribute. While being able to read exactly one value and only a string value, no knowledge of extended attributes is required at all to use it. ═══ 12.2. Writing an extended attribute ═══ The following APIs are provided to write an extended attribute of a given file or directory: WtkCreateEa creates an empty in-memory valuelist for an extended attribute. WtkAppendEaValue appends a value to an in-memory valuelist for an extended attribute that has either been created by WtkCreateEa or read from disk by WtkReadEa. The value can only be appended, if the type matches the current value (list). WtkSave writes a modified value (list) of a given extended attribute to disk. WtkPutEaValue reads the current value (list) of an extended attribute from disk, appends the given value to the list, if the type matches the current value (list), and saves the newly extended valuelist to disk. WtkWriteStringEa This API is even simpler to use compared to WtkPutEaValue when it comes to write an string extended attribute. While being able to write exactly one value and only a string value, no knowledge of extended attributes is required at all to use it. ═══ 13. Memory Mapped Files Manager ═══ The Memory Mapped Files Manager API of the Workplace Shell Toolkit provides an API for reading and writing files by simply reading from and writing to memory. For that files are mapped to memory and the MMF exception handler takes care for that only the required parts of the file are being read from disk and only the modified parts are saved to disk, if requested. With memory mapped files opening a file is as easy as allocating a chunk of memory, and saving all changes is done by a simple API call, there is no need for intermediate files or for fiddeling around with file pointers. See the following sections for more information and the APIs related to them: Intitialize MMF support  WtkInitializeMmf allocate memory mapped file buffer or dynamic memory buffer  WtkAllocMmf maintain buffer size  WtkQueryMmfSize  WtkSetMmfSize save changes from memory mapped file buffer to disk  WtkUpdateMmf free memory buffer  WtkFreeMmf terminate MMF support  WtkTerminateMmf ═══ 13.1. initialize MMF support ═══ When using the Memory Mapped Files Manager API, it must be initialized by a call to WtkInitializeMmf, this must be done per thread. Beside initializing the internal data this call will register the MMF exception handler. Note:  When leaving the function that called WtkInitializeMmf, WtkTerminateMmf must be called to deregister the exception handler again, especially if other exception handlers are used beside the one for MMF support. Otherwise unpredictable results (most often simply protection violations may occurr). ═══ 13.2. allocating a memory mapped file buffer ═══ Allocating a file with the Memory Mapped Files Manager API by a call to WtkAllocMmf does not really already allocate memory. Instead, it only reserves address space for the requested memory object so that the new and/or existant file could fit into the memory. The maximum size of the memory object must be specified on allocation, because it cannot be extended later. All further access to the file can simply be done by accessing the memory, everything else is being taken care by the MMF exception handler. ═══ 13.3. allocating a memory only buffer ═══ The Memory Mapped Files Manager API WtkAllocMmf can also be used to allocate a memory object without mapping a file to it. Such a memory object has still the advantage that it can grow dynamically, so subsequent handling of memory (sub)allocation within the uncommitted memory object is done automatically by the MMF exception handler. ═══ 13.4. update a file from a memory mapped file buffer ═══ After having modified a memory mapped file buffer all changes can be written back to disk by a call to WtkUpdateMmf. When doing so, only the memory pages being marked as modified by the MMF exception handler are written to disk. ═══ 13.5. MMF exception handler ═══ The exception handler used by the Memory Mapped Files Manager API is responsible for keeping track of the file being mapped to memory. On PC platforms memory is reserved and or allocated in 4 Kb memory pages and every page can among others have the attributes committed for read access and/or committed for write access. Having reserved the memory address space only at first, none of the commit attributes are set, this is called uncommitted memory. Every access now of uncommitted memory will normally cause an access violation. This fact is used by the MMF exception handler, it intercepts all exceptions for allocated memory mapped file buffers and performs the following actions: on a read access to a memory page not committed for read read the 4 Kb portion of the mapped file and mark this memory page committed for read access on a write access to a memory page not committed for write  perform the action for memory not being committed for read, if that memory page was not read before  mark this memory page committed for write access, so that a call to WtkUpdateMmf later can write the modified pages back to disk. ═══ 14. Modifying and distributing the Workplace Shell Toolkit ═══ The WPS Toolkit package is free software. You can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation, in version 2 as it comes in the "COPYING.LIB" file of the WPS Toolkit main distribution. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. ═══ 14.1. GNU Library General Public License ═══ GNU LIBRARY GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1991 Free Software Foundation, Inc. 675 Mass Ave, Cambridge, MA 02139, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.] Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights. Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library. Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license. The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such. Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better. However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries. The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library. Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one. GNU LIBRARY GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you". A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) The modified work must itself be a software library. b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. This option is useful when you wish to copy part of the code of the Library into a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) b) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. c) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. d) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS Appendix: How to Apply These Terms to Your New Libraries If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License). To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Also add information on how to contact you by electronic and paper mail. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. , 1 April 1990 Ty Coon, President of Vice That's all there is to it! ═══ 15. Contact ═══ If you have suggestions for or problems with the Workplace Shell Toolkit, send email to wpstk@netlabs.org As soon as the project team grows to some more members, we will also install a mailing list. ═══ 16. Credits ═══ Please note the following credits and thank-yous: Radim Kolar (email: 2:423/66.111@FidoNet.Org) for making his CRC package with source public domain. It was the basis for the CRC related helper functions. Ulrich Moeller (email: ulrich.moeller@rz.hu-berlin.de) Inventor of the XWorkplace and WarpIn packages, for giving a lot of ideas via telephone and by making his packages OpenSource on Netlabs. Sergey I. Yevtushenko (email: es@os2.kiev.ua) for his MMF library. This was the base for the Memory Mapped Files ManagerAPI in this toolkit, where it was only extended to have a separate manager for each tread. See also Sergey's article Memory-Mapped files in OS/2 in the Electronic Developers Magazine (EDM/2) issue of 10/1998. ═══ 17. Authors ═══ Currently, the following persons have contributed to the Workplace Shell Toolkit: Christian Langanke (email: cla@clanganke.de) Inventor of the WPS toolkit, author of "Animated mouse Pointer for OS/2", contributor to XWorkplace, coded and/or integrated all of the functions of the first release and the makefiles and batch files required for compilation. See his homepage for lots of free utilities for OS/2 and eComStation at: http://www.clanganke.de/os2 ═══ 18. Appendix: Building the Workplace Shell Toolkit library / samples ═══ The Workplace Shell Toolkit provides makefiles for the supported compilers, where each source directory contains both a makefile being the makefile for NMAKE (for IBM compilers only), and a GNUmakefile being the makefile for GNU make (for the emx compiler only) Each of them includes a file from within the the config directory, which determines all the compiler and linker flags etc. and the relative pathnames to the directories holding object modules, libraries, etc. to be created during the build. All created files are being written to the directories: compile for object modules, sample program executables, other intermediate files The subdirectories cset2s, cset2m, vac3 and gcc contain the files according to the used compiler and, for the IBM CSet/2 compiler, also according to the thread mode (mixing of singlethreaded or multithreaded code not allowed with this). ipf for intermediate files required to create the online help file. This directory is being created only when compiling the source distribution. Otherwise, it already exists. lib for the Workplace Shell Toolkit library file to be linked with your application Note:  when you compile the Workplace Shell Toolkit yourself, the resulting libraries are put into directories named either debug or release instead of lib, depending on the debug status during compilation. The subdirectories cset2s, cset2m, vac3 and gcc contain the library file according to the used compiler and, for the IBM CSet/2 compiler, also according to the thread mode (mixing of singlethreaded or multithreaded code not allowed with this). This directory is being created only when compiling the source distribution. Otherwise, it already exists. book for the documentation files in INF format This directory is being created only when compiling the source distribution. Otherwise, it already exists. If these directories do not exist, the make process creates them when being invoked for the first time. See the following sections for details about include files used by the (GNU)makefiles for your compiler:  IBM C Set ++ V2.1 / IBM VisualAge C++ V3.0 for OS/2  emx 0.9d for OS/2 ═══ 18.1. IBM C Set ++ V2.1 / IBM VisualAge C++ V3.0 for OS/2 ═══ The following files are used by the makefiles of the Workplace Shell Toolkit in order to define flags and inference rules for usage with the IBM compilers. Normally the makefile process should only be configured by the project team, if you require changes, please tell the team about it. : makefile makefile for NMAKE in each source directory config\rules.in This file is included by all makefiles (makefile in each source directory) of the Workplace Shell Toolkit. It determines flags and inference rules for most tools and utilities used for the compilation process. Please do not modify this file ! config\project.in This file is included by config\rules.in This is the project specific extension to config\rules.in. config.cmd This program is called by project.in to perform the following tasks:  determine the current compiler and tookit  determine if NMAKE is compiling sources in the developer tree or within an installation tree of a binary release (results in different directories where the libraries wpstk*.lib can be found) ═══ 18.2. emx 0.9d for OS/2 ═══ The following files are used by the makefiles of the Workplace Shell Toolkit in order to define flags and inference rules for usage with the emx compiler. Normally the makefile process should only be configured by the project team, if you require changes, please tell the team about it. : The following files are provided with the Workplace Shell Toolkit in order to configure the makefiles for usage with the emx compiler: GNUmakefile makefile for GNU make in each source directory config\GNUrules.in This file is included by all makefiles (GNUmakefile in each source directory) of the Workplace Shell Toolkit. It determines flags and inference rules for most tools and utilities used for the compilation process. Please do not modify this file ! config\GNUproject.in This file is included by config\GNUrules.in This is the project specific extension to config\GNUrules.in. config.cmd This program is called by GNUproject.in to perform the following tasks:  determine the current compiler and tookit  determine if GNU make is compiling sources in the developer tree or within an installation tree of a binary release (results in different directories where the libraries wpstk*.lib can be found)  if not already exists, creates OMF versions of the emx libraries (.a to .lib) in the lib directory of the emx compiler tree.  creates modified copies of some Workplace Shell headers to work with emx  for IBM Toolkit for OS/2 WARP 4, creates a modified copy of os2def.h to eliminate keywords for thunking not being supported by emx (normally not used by WPS classes anyway...) ═══ 19. Appendix: Extending the Worplace Shell Toolkit ═══ This section describes, how new functions are to be integrated into the Workplace Shell Toolkit. Note:  Anyone, who extends the Workplace Shell Toolkit, is kindly asked to do so using the Netlabs Open Source Archive for this project instead of modifying and redistributing it separately. This way all users of the Workplace Shell Toolkit benefit directly.  Most important, is has to be made sure that if new source files are being introduced to the toolkit, they can be compiled with all of the supported compilers, requiring also the update of both the makefile for the IBM compilers and the GNUmakefile for the emx compiler. The biggest problem is that the NMAKE and GNU make work differently at some important points. While it may be not that difficult to make slight modifications in both types of makefiles, testing it can be done most effectively by the project team.  When introducing new functions, anyone wanting to do so is kindly asked to follow the naming scheme for functions, variables and files, which has been mostly adopted from the IBM Toolkit for OS/2 WARP 3/4, and the layout of sourcefiles. This is the only way to make sure that the Workplace Shell Toolkit will stay to be a consistent piece of software, presenting a homogeneous API to the user. Select one of the following topics:  Getting the source from Netlabs  Source Code Notation Conventions  Source File Naming Conventions/Restrictions  Source Code Categories  Adding functions to existing files of the library source - Modifying an existing source file - Modifying an existing header file - Extending an existing sample progam  Adding new files to the library source - Create a new source file - Create a new header file - Extending the makefiles for new source files - Create a new sample program  Adding online help comments for new functions ═══ 19.1. Getting the source from Netlabs ═══ In order to get the up-to-date source code of the Workplace Shell Toolkit, you can access the Netlabs Open Source Archive. For that, you need to use the Concurrent Version System (CVS), and it is recommended to also use the Netlabs Open Source Archive client (NOSAC). With these packages you can donwload the current code, being read up-to-date from the Netlabs CVS server, and, if you would like to join the project team, can later upload bugfixes or extensions to the Workplace Shell Toolkit. See  The Netlabs  The Netlabs Open Source Archive to get more information about Netlabs, Open Source, the Open Source Archive and to download the required software. ═══ 19.2. Source Code Notation Conventions ═══ The following notation conventions are used in the source of the Workplace Shell Toolkit:  All external function names in library sources start with Wtk.  The names of the parameter variables in the prototypes of the functions (being included in the header files) and the names of the parameter variables being used in the documentation comments (being part of the C source) must be identical, otherwise the generation of the online documentation will report warnings that documentation comments for certain parameters of certain functions are missing. This is due to the fact that the script generating the online help file first scans the header files for prototypes, and then searches the documentation comments in the source files. Of course, also the names of the parameter variables used in the library source should be identical to these being used in the headers and the online docs  All internal function names start with a double underscore and are to be marked as static, so that they are not exported.  All type names not being used from the C compiler runtime are written with uppercase letters only.  All type names not being used from the C compiler runtime and being a pointer to a type are named with "Pxxxxxxx", where "xxxxxxx" is the data type being pointed to.  All variable names not being of a type used by the C compiler start with an abbreviation according to the variable type, just like mostly in the Toolkit for OS/2 Warp. Here are some examples: type example for variable names BOOL fVariable SHORT sVariable USHORT usVariable LONG lVariable ULONG ulVariable CHAR szVariable PSZ pszVariable PBYTE pbVariable PVOID pvVariable There are some exceptions (as always) for this rule, where other prefixes are widely used. - If name types and thus resulting prefixes are very long, sometimes shorter prefixes are being used. For example, when coding for extended attributes, a pointer of type PFEA2LIST is mostly prefixed with pfea2l. Also when using structures of DATETIME, very often the variable or the prefix dt is used. - For types of the C compiler runtime, there also may be widely used abbreviations that can also be used instead of the full type name.  Al include files shall follow the same layout. See the layout of existing header files in the include directory.  In header files of the library, C++ comments (double slash) must not be used. Although all makefiles of the toolkit use compiler flags allowing such comments, the library headers should also be useable with programs, where the programmes do not want to allow them. ═══ 19.3. Source File Naming Conventions/Restrictions ═══ The intention of the Workplace Shell Toolkit is (with only few exceptions) to obey the 8.3 notation for all files in such a manner that a compiled version of the library can be installed on a FAT-formatted drive. For the IBM compilers, it is intended also be possible to compile the sample programs on that FAT drive. Note that this is not possible for the emx compiler using GNU make, because the makefiles for this are named GNUmake. As a workaround, one could unpack all files called GNUmakefile an a HPFS drive and copy them over the files called makefile on the FAT drive. This of course would lead to not being able to use the IBM compilers and NMAKE anymore with this installation. The 8.3 notation is to be obeyed within the following directories: bin containing the REXX scripts for supporting the make process book containing the resulting online documentation files config containing the configuration and help files for the make process include containing the header files of the library bin containing the resulting library file(s) with a binary distribution samples containing the sample programs. The only files being allowed not to comply to the 8.3 scheme are the files called GNUmakefile. ship containing some files being required to build a binary distribution source\lib containing the source files Despite of the fact that the source directory would not be shipped with a binary distribution, all .c files must be named exactly like the header files (and thus obey the 8.3 scheme) in order not to break the build of the online help. The following directories may contain filenames not containing 8.3 compliant names, as they are only required to build the library and online doc files, and not being shipped with a binary distribution: compile containing the intermediate files for compiling the library and samples The subdirectory gcc contains files of the toolkit adapted to the GNU compiler. ipf containing the intermediate files for compiling the docs source\book containing the source files ═══ 19.4. Source Code Categories ═══ Two types of source code categories exist within the Workplace Shell Toolkit: minor This category is for the so called little helper or utility functions. The following applies to functions falling into a minor category:  the name of the source and the include file for that category starts with wtku, leaving four more characters for distincting between this and other files of a minor category.  the include file for such category has to be included by wtku.h  the include symbol for such category has to start with INCL_WTKUTL  the included symbol for such category has to be WTKUTLxxxxxx_INCLUDED and defines the text being used in the online help within the functions overview page. This text must include the term "helper functions" in order to distinct between minor and major categories. The text being defined by this symbol is being used as a headline for the category within the Workplace Shell Toolkit Functions Overview. major This category is for the so called major APIs, each consisting of a lot of related functions being desinged to support a special task. The following applies to functions falling into a major category:  the name of the source and the include file for that category starts with wtk, leaving five more characters for distincting between this and other files of a minor category.  the include file for such category has to be included at the end of wtk.h  the include symbol for such category has to start with INCL_WTK  the included symbol for such category has to be WTKxxxxxx_INCLUDED and defines the text being used in the online help within the functions overview page. This text must NOT include the term "helper functions" in order to distinct between minor and major categories. The text being defined by this symbol is being used as a headline for the category within the Workplace Shell Toolkit Functions Overview. ═══ 19.5. Adding functions to existing files of the library source ═══ The following applies, if you want to add new functions to existing source files of the the Workplace Shell Toolkit:  determine, wether your functions fall into an existing category. If you have to only add a few functions, they possibly fall into an existing category. If you add some more to a lot of functions, they very likely require a new category, and it might be useful to introduce a new major category. If they fall into a category that already exists, read further here. If they fall into a non-existing category, see Adding new files to the library source  Please read, (and mostly obey) the Source Code Notation Conventions.  Please make sure that new functions do not interfere with existing ones. A good way to ensure this is to ask the project team !  If your new function(s) make sense to be part of an already existing category, add your function to an existing source file. If you are not sure about wether this is the case, or wether you should open a new category, ask the project team ! More, you should extend the sample program for that category in order to let your new function(s) be automatically tested.  Last, but not least, you should well add documentation comments to the source files, so that the online help can be generated properly. The make process for the online help will generate warnings for each function or parameter of a function, for that no documentation comment exists. ═══ 19.5.1. Modifying an existing source file ═══ If you add a single function or only a few functions, which fall into an existing source code category, adding a new function is fairly easy. In order to have fairly the same layout, it is recommended to copy an existing function and modify it. Please make sure that you also modify the documentation comments. In most cases it makes sense to not just append the new function(s) at the end of the source file, but rather place it beneath certain existing functions in order to group functions, where they serve the same task or belong together in any other sense. In general, the functions shall be placed in the same order as their prototypes in the header file corresponding to the source file. You also have to add the function prototype to the header file corresponding to the source file that you have added your new function(s) to. If your code required new internal datatypes, thus only be used by your code, place them before the first (helper) function. Only datatypes and structures being used by the caller of your code are to be placed in the header file corresponding to the source file. See source\lib\wtkset.c as an example for a source file introducing datatypes being used internally. See also Source Code Notation Conventions ═══ 19.5.2. Modifying an existing header file ═══ If you add a single function or only a few functions, which fall into an existing source code category, add the prototype(s) of the new function(s) to the header file. If you need to introduce new datataypes that are being used by the caller of your code, place them before the first prototype. See include\wtkset.h as an example for a header file introducing datatypes being used by the caller of an API. In most cases it makes sense to not just append the prototype(s) of the new function(s) at the end of the header file, but rather place it beneath certain existing functions in order to group functions, where they serve the same task or belong together in any other sense. In general, the prototypes of the functions shall be placed in the same order as their code appears in the code file corresponding to the header file. See also Source Code Notation Conventions ═══ 19.5.3. Extending an existing sample progam ═══ If you add a single function, or only a few functions, which fall into an existing source code category, extend the sample program for that category in order to let your new function(s) be automatically tested. See the existing sample programs in the subdirectory samples as examples. At least some code should be added that tests, wether the code works ok. With some APIs, it is also important to test, wether the API fails under a certain condition. VIO sample programs should always return zero, if all works well, because otherwise a make run from the top level makefile would also break out because of the non-zero return code. This breaks the method of testing all VIO sample programs with one make call. So if an API is expected to fail, set rc to NO_ERROR to ignore the error. Workplace Shell sample programs are not being installed with make run. The user has to (de)install them with make (de)install See the make file of the WPS sample program in the subdirectory samples\settings\wps as an example. ═══ 19.6. Adding new files to the library source ═══ The following applies, if you want to add new functions to the Workplace Shell Toolkit, where you are required to add new source files to the library :  determine, wether your functions fall into an existing category. If they fall into a category that do not already exists, read further here. If they fall into an existing category, see Adding functions to existing files of the library source  When creating a new category, determine the type of category that should be created. If you have to only add a few functions, they should possibly form a minor category. If you add some more to a lot of functions, it might make more sense to open a major category. A good way to be sure of that is to ask the project team !  Please read, (and mostly obey) the Source Code Notation Conventions.  Please make sure that new functions do not interfere with existing ones. A good way to ensure this is to ask the project team !  Opening a new category requires to add completely new files to the Workplace Shell Toolkit. This most likely will also require you to add a completely new sample program in order to let your new function(s) be automatically tested.  Last, but not least, you should well add documentation comments to the source files, so that the online help can be generated properly. The make process for the online help will generate warnings for each function or parameter of a function, for that no documentation comment exists. ═══ 19.6.1. Create a new source file ═══ If you introduce a new source code category, this requires to add a completely new source file to the Workplace Shell Toolkit. In order to have fairly the same layout, it is recommended to copy an existing source file, remore all functions out of it, modify the comments and includes and then add the code of your functions to them. Please make sure that you also add documentation comments, when you are done. Building a toolkit for others to use, it is very important to think about how the function prototypes could look like, before you actually code it, so it is mostly a good strategy to also create the new header file before actually start the coding. Please also try to make the API look and feel like a "normal" OS/2 API. Surely not all of the OS/2 APIs are well designed, but it also would be a bad thing, if the API of the Workplace Shell Toolkit would be too different from them. See also Source Code Notation Conventions ═══ 19.6.2. Create a new header file ═══ If you introduce a new source code category, this requires to add a completely new header file to the Workplace Shell Toolkit. In order to have fairly the same layout, it is recommended to copy an existing header file, remore all prototypes out of it, modify the comments, include and included symbol definitions (very important !!!!) and then add the prototypes of your functions to them. Building a toolkit for others to use, it is very important to think about how the function prototypes could look like, before you actually code it. Please also try to make the API look and feel like a "normal" OS/2 API. Surely not all of the OS/2 APIs are well designed, but it also would be a bad thing, if the API of the Workplace Shell Toolkit would be too different from it. See also Source Code Notation Conventions ═══ 19.6.3. Extending the makefiles for new source files ═══ If you introduce a new source code category, this requires to extend the makefiles, so that your new source module is being compiled and being placed into the library of the Workplace Shell Toolkit. For that, you have to add the following to both the makefile and the GNUmakefile:  add the object module to the macro OBJS  add a dependency for your object module, so that it is recompiled, if the header file changes Note:  Do not edit the GNUmakefile with an editor that replaces tabs with blanks (like TEDIT), as GNU make requires commands within rules to be preceeded by at least one tab.  within a makefile, the object module and header file needs to be prepended with the path, where the file has to be written or read. For this, use the macros already being used for existing entries.  within a GNUmakefile, the object module and header file MUST NOT be prepended with any path. Also here see the existing entries and add the new entry according to these. Of course it makes sense to test with all supported compilers, wether the library is being properly compiled, including your new module. If you do not have all supported compilers available, ask the project team to help you. ═══ 19.6.4. Create a new sample program ═══ When opening a new source category you are required to create a new sample program that tests your new function(s) automatically. For this, a sample program should call all of your functions at least once (and do somethimg senseful, of course). The following topics are important, when creating a new sample program: Creating a VIO sample program For all categories, at least a VIO sample program should be created. If some of your APIs cannot be executed outside a SOM environment like for the settings manager API, the VIO sample programm can leave them out. A good way to be able to test at least some of the functions is to use dummy pointers instead of real SOM self pointers, where possible. For this the library code should not call real SOM APIs in DEBUG mode, where possible. See macro OBJECTVALID() in source\lib\wtkset.c as an example how to avoid calling SOM methods in DEBUG mode. VIO sample programs should always return zero, if all works well, because otherwise a make run from the top level makefile would also break out because of the non-zero return code. This breaks the method of testing all VIO sample programs with one make call. So if an API is expected to fail, set rc to NO_ERROR to ignore the error. Creating a sample Workplace Shell Class For testing certain APIs, it cannot be avoided to code real SOM/Workplace Shell classes. See the WPS sample for the settings manager in the directory samples\settings\wps as an example. Calling all functions of a category If a function itself calls several functions of the same category at a time, for testing purposes a call to this function is sufficient to regard also the called functions as tested (Example: WtkGetNextEaValue calling WtkReadEa, WtkFindFirstEaValue, WtkFindNextEaValue and WtkCloseEa). Nevertheless it might still make sense to implement also calls to the indirectly tested functions in order to provide also a code sample to the users of the library. Choosing a name for the program Each sample program has a subdirectory below samples. The name has to be unique among the samples, because all sample program executables are being created in the same subdirectory of compile. Therefore most sample programs and their directory are named as follows:  create a directory below samples with a name with up to seven characters  if you create both a vio and a WPS sample, create the subdirectories vio and wps in that directory, otherwise use the directory itself for the vio sample.  create at least - a source file named like the directory. For VIO samples, the name has to be preceeded by an underscore. This will prevent to name sample programs like existing OS/2 commands etc.. For WPS samples, this does not apply, and you will call the main source files and thus the WPS DLL anything line xxxcls.*. Also for such DLLs make sure that the name is unique among all WPS class samples. Other files being generated like resource files have also to be named uniquely among all WPS samples. It is good practise to name all generated files with the name of the testclass source file in order to avoid any name problems. - a readme file named readme.1st, containing informations about the sample program. Take a readme.1st of an existing sample program as a template. - a makefile containing the rules and macros for use with NMAKE and the IBM compilers. Take a makefile of an existing sample program as a template. - a GNUmakefile containing the rules and macros for use with GNU make and the emx compiler. Take a GNUmakefile of an existing sample program as a template. Things to care for when creating makefiles As VIO sample programs are rather small, they mostly consist only of a single C source file. So when taking the makefiles of an existing sample as a template, you mostly have only to modify  the top comment line  the value of the macro DESCRIPTION  the value of the macro STEM Of course the top comment line and the description of the makefile should have an equivalent content, like in the existing samples. In case of a WPS sample, things are much more complicated. Very important is for example that the .c file being maintained by the SOM compiler is written in the sample source directory, but all headers and module definition files in the compile directory. Make sure to use the appropriate inference rules in both makefiles. It is recommended to use the existing WPS sample for the settings and details manager in the samples\settings\wps directory as a template. Note:  Do not edit the GNUmakefile with an editor that replaces tabs with blanks (like TEDIT), as GNU make requires commands within rules to be preceeded by at least one tab. pseudotargets to be supported by makefiles of sample programs VIO sample programs should at least support the following make pseudotargets: all create the sample program run run the sample program. Note that executables are not being created in the sample source directory, but below the compile subdirectory, so this is an easy way to call the program. debug load the sample program into the debugger. Note that this is not possible for emx compiled programs (yet?). clean delete all files being created by the makefile while compiling the sample program Note:  Currently, some samples take a directory pathname as an argument in order to there create temporary files and/or directories. Make sure that your sample program receives the correct parameters when called by the commands of the run and debug pseudotargets. WPS sample classes should at least support the following make pseudotargets: all create the WPS sample class install register the sample class and optionally create an instance of the object class for testing purposes deinstall deregister the sample class Note:  while the run and debug are not to be supported by the makefiles of a WPS sample class, these targets should exist anyway and display a warning message. Add the sample to the top level makefiles In order to enable the top level makefiles to build the new sample program, extend the following parts both in makefile and GNUmakefile in the top level directory: add a new pseudo target for your sample program take an existing pseudotarget as an example and modify the name and the subdirectory within the commands. Please place the new pseudotarget at the end of the appropriate section: VIO sample section only a VIO sample program exists for the source category VIO and SOM sample section both a VIO and a SOM sample program exists for the source category SOM sample section only a SOM sample program exists for the source category macro ALL_SAMPLES add the new pseudotarget to the list of pseudotargets for all samples macro VIO_SAMPLES add the new pseudotarget to the list of pseudotargets for VIO samples, if you add a VIO sample macro SOM_SAMPLES add the new pseudotarget to the list of pseudotargets for SOM samples, if you add a SOM sample ═══ 19.7. Adding online help comments for new functions ═══ After having added functions to the Toolkit for OS/2 Warp, you have to add documentation comments to the source file. To do so, you add the follwoing before the function:  a C comment start /*  a start tag line for the syntax comment of the function @@functionname@SYNTAX Following to that line, you enter the text explaining the syntax in IPF style. This text should be as short and general as possible. In order to have a consistent look and feel of the online documentation, please do not use any IPF tags for the syntax explanation that modify the text style (as highlighting, changing colors etc.).  for each parameter of the function a start tag line for the parameter @@functionname@PARM@parametername@type As type, please specify either in, out or inout. Following to that line, you enter one (!) line for a brief comment. This line is not meant to take only one line in the source file, but rather be one line in terms of IPF source. This first IPF line is shown as a comment in the syntax section for the function. Terminate that first IPF line by a parameter break (:p.) on the first column of the line following the text of this line. Following to that first IPF line you can add more lines in order to give further explanations about the parameter. See existing documentation comments for similar variables as examples !!!  a start tag line for the return value of the function @@functionname@RETURN Following to that line, you enter one (!) IPF line for a brief comment. (see explanation above). Following to that first IPF line you can add more lines in order to give further explanations about the parameter. See existing documentation comments for similar return values as examples !!!  a start tag line for the remarks for the function @@functionname@REMARKS Add IPF text to further describe the function.  a end tag line @@  a C comment end */ After having added all that for all the functions, that you added to the Toolkit for OS/2 Warp, (re)build the library documentation in order to check, wether your comments have properly been included.