home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wpstkrgu.zip / wtkref.inf (.txt)
OS/2 Help File  |  2003-03-18  |  364KB  |  13,754 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. How to Use this Book ΓòÉΓòÉΓòÉ
  3.  
  4. This reference is a detailed technical guide and reference for application 
  5. programmers. It gives reference information and code examples to enable you to 
  6. write source code using the Workplace Shell Toolkit. 
  7.  
  8. It is assumed that you are familliar with the handling of OS/2 online book 
  9. files. More, you need to be familiar with the usage of the Toolkit for OS/2 
  10. Warp and Workplace Shell programming in general. If not, please refer to 
  11.  
  12.       How to use this book 
  13.  
  14.  and other chapters of the Workplace Shell Programming Reference. 
  15.  
  16.  Note:  The information of the section How to Use this Bookof the Workplace 
  17.  Shell Programming Reference not being included in this book applies also here. 
  18.  
  19.  
  20. ΓòÉΓòÉΓòÉ 1.1. Conventions used in this Reference ΓòÉΓòÉΓòÉ
  21.  
  22. The purpose of this reference is to give information about classes, methods, 
  23. constants, and data types. It provides information about the methods which 
  24. enables the user to call functions in the C programming language. 
  25.  
  26. The following information is provided: 
  27.  
  28.      The syntax and parameters for each method. 
  29.      The syntax of each data type and structure. 
  30.  
  31.  
  32. ΓòÉΓòÉΓòÉ 1.2. Reference Notation Conventions ΓòÉΓòÉΓòÉ
  33.  
  34. The following notation conventions are used in this reference: 
  35.  
  36.  NULL                               The term NULL applied to a parameter is 
  37.                                     used to indicate the presence of the 
  38.                                     pointer parameter, but with no value. 
  39.  
  40.  NULLHANDLE                         The term NULLHANDLE applied to a parameter 
  41.                                     is used to indicate the presence of the 
  42.                                     handle parameter, but with no value. 
  43.  
  44.  Implicit Pointer                   If no entry for a data type "Pxxxxxxx" is 
  45.                                     found in Data Types, then it is implicitly 
  46.                                     a pointer to the data type "xxxxxxx". See 
  47.                                     Implicit Pointer Data Types for more 
  48.                                     information about implicit pointers. 
  49.  
  50.  CONSTANT NAMES                     All constants are written in uppercase to 
  51.                                     match the header files. Where applicable, 
  52.                                     constant names have a prefix derived from 
  53.                                     the name of a function, message, or idea 
  54.                                     associated with the constant. 
  55.  
  56.                                     In this book, references to a complete set 
  57.                                     of constants with a given prefix is written 
  58.                                     as shown in the following examples: 
  59.  
  60.                                     Window message      WM_* 
  61.  
  62.                                     System value        SV_* 
  63.  
  64.  
  65. ΓòÉΓòÉΓòÉ 1.3. Header files ΓòÉΓòÉΓòÉ
  66.  
  67. All functions require an "#include" statement for the system header file wtk.h. 
  68.  
  69. #include <wtk.h>
  70.  
  71. Most functions also require a "#define" statement to select an appropriate 
  72. (conditional) section of the header file, and hence, the required prototype. 
  73. Where this is necessary, it is shown at the head of the function definition in 
  74. the form: 
  75.  
  76. #define   INCL_name
  77.  
  78. Note: 
  79.  
  80.      These "#define" statements must precede the "#include <wtk.h>" statement. 
  81.      If you also include os2.h, you must do this before including wtk.h !!! 
  82.  
  83.  
  84. ΓòÉΓòÉΓòÉ 1.4. Implicit Pointer Data Types ΓòÉΓòÉΓòÉ
  85.  
  86. A data type name beginning with "P" (for example, PERRORCODE) is likely to be a 
  87. pointer to another data type (in this instance, ERRORCODE). 
  88.  
  89. In the data type summary, Data Types, no explicit "typedefs" are shown for 
  90. pointers; therefore, if no data type definition can be found in the summary for 
  91. a data type name "Pxxxxxx", it represents a pointer to the data type "xxxxxx", 
  92. for which a definition should be found in the reference. 
  93.  
  94. The implicit type definition needed for such a pointer "Pxxxxxx" is: 
  95.  
  96. typedef xxxxxx *Pxxxxxx;
  97. Such definitions are provided in the header files. 
  98.  
  99.  
  100. ΓòÉΓòÉΓòÉ 2. Why a Workplace Shell Toolkit ? ΓòÉΓòÉΓòÉ
  101.  
  102. The Workplace Shell has by far the most innovative and extendible interface of 
  103. all computer GUIs around. While this is recognized by many programmers aas well 
  104. as users, coding Workplace Shell classes requires some more knowledge compared 
  105. to plain GUI programming. 
  106.  
  107. Even when someone has got this knowledge, coding certain functionality that a 
  108. Workplace Shell class either should or must have, is most often a very time 
  109. consuming task. 
  110.  
  111. More, one often needs to create somewhat redundant code, only changing a few 
  112. things within a lot of code lines, blowing out your source files and most 
  113. likely leading to a lot of little nasty bugs, requiring a lot of tests hunting 
  114. them. 
  115. Even worse, if you are creating not only one, but several Workplace Shell 
  116. classes in one project, then you will quickly come to code several parts 
  117. several times. 
  118.  
  119. Beside giving you a lot of little helper functions, the API of the Workplace 
  120. Shell Toolkit encapsulates the complexity of the handling of some of the tasks 
  121. being most time consuming to code. 
  122.  
  123. See the following guides to specific major APIs of the Workplace Shell Toolkit: 
  124.  
  125.      Text Message Files (TMF) 
  126.      Settings and Details Manager 
  127.      Extended Attributes Manager 
  128.      Memory Mapped Files Manager 
  129.  
  130.  
  131. ΓòÉΓòÉΓòÉ 3. Source and binary distributions of the Workplace Shell Toolkit ΓòÉΓòÉΓòÉ
  132.  
  133. The Workplace Shell Toolkit comes in two flavours, source and binary 
  134. dsitributions. See 
  135.  
  136.       Supported compilers / Prerequisites 
  137.  
  138.  for prerequisites that apply to the two distributions in association with the 
  139.  used compiler. 
  140.  
  141.  source distribution 
  142.            Beside the sample programs and the header files this version 
  143.            includes the sources for the library and the online documentation of 
  144.            the Workplace Shell Toolkit. Unlike the binary distribution this 
  145.            version is not ready to use - it must be compiled first. 
  146.  
  147.            Note: 
  148.  
  149.                This version is available ony via the CVS server of the Netlabs 
  150.                 Open Source Archive. See 
  151.  
  152.                      Getting the source from Netlabs 
  153.  
  154.                 for more information. 
  155.  
  156.  binary distribution 
  157.            Beside the sample programs and the header files this version 
  158.            includes the compiled versions of the library for all supported 
  159.            compilers and the online documentation, thus being ready to use. The 
  160.            sources for the library and the online documentation of the 
  161.            Workplace Shell Toolkit are not included. 
  162.  
  163.            Note: 
  164.  
  165.                This version is 
  166.                   -  available via 
  167.                           The Hobbes OS/2 archive or 
  168.                           other ftp servers within the internet 
  169.  
  170.                      wpstknnn.zip, where nn is the version number. 
  171.                   -  will be announced via comp.os.os2.announce 
  172.                   -  is maintained only by the project team. 
  173.  
  174.  
  175. ΓòÉΓòÉΓòÉ 4. Supported compilers / Prerequisites ΓòÉΓòÉΓòÉ
  176.  
  177. The following compilers are currenty supported for using the Workplace Shell 
  178. Toolkit. See the following sections for prerequisites: 
  179.  
  180.      IBM C Set ++  V2.1 / IBM VisualAge C++ V3.0 for OS/2 
  181.  
  182.      emx 0.9d for OS/2 
  183.  
  184.  
  185. ΓòÉΓòÉΓòÉ 4.1. IBM C Set ++  V2.1 / IBM VisualAge C++ V3.0 for OS/2 - Prerequisites ΓòÉΓòÉΓòÉ
  186.  
  187. The following prerequisites apply when using the Workplace Shell Toolkit with 
  188. the IBM compilers: 
  189.  
  190.      Users of a source distribution of the Workplace Shell Toolkit are 
  191.       required to download it via CVS to an HPFS drive. A HPFS partition is 
  192.       also required in order to to compile it completely. 
  193.       One could copy a CVS development tree to a FAT partition, this would 
  194.       allow to compile at least the library itself and the sample programs, but 
  195.       the online docs could not be compiled, as the source files for this 
  196.       require long filenames. 
  197.  
  198.      Users of a binary distribution of the Workplace Shell Toolkit (not 
  199.       including the sources for the library or online doc) can install it onto 
  200.       a FAT drive without problems, when using the IBM compilers. In that case 
  201.       ignore or delete the files GNUMAKEF where existing, as they are not 
  202.       required by the IBM compilers (these are the GNUmakefile, but just with a 
  203.       filename cut off after the eight characters). 
  204.  
  205.      You are reqired to append the pathname of the include and lib directories 
  206.       of the installed Workplace Shell Toolkit to the INCLUDE and LIB 
  207.       environment variables. Optionally, if you use the EPM, you might also 
  208.       want to add the help index file to the HELPNDX environment variable. 
  209.  
  210.       This can be done either in 
  211.  
  212.         -  your config.sys file (not recommended !) 
  213.         -  a batch file that you use to call to setup your environment. 
  214.            you may want to use the batchfile bin\wtkenv.cmd, setting up the 
  215.            environment automatically 
  216.         -  your makefile 
  217.  
  218.       Note: 
  219.  
  220.         -  when you compile the Workplace Shell Toolkit yourself, the resulting 
  221.            libraries are put into directories named either debug or release 
  222.            instead of lib, depending on the debug status during compilation. 
  223.  
  224.       Further, for each compiler there is a separate subdirectory below the lib 
  225.       directory for each version of the Workplace Shell Toolkitlibrary file. 
  226.       Where the compiler does not allow mixing of single- and 
  227.       multithread-compiled code (for currently one compiler only) a suffix for 
  228.       single- or multithreaded code is appended to the name of the 
  229.       subdirectory: 
  230.  
  231.       cset2s         IBM C Set ++  V2.1 - singlethreaded 
  232.       cset2m         IBM C Set ++  V2.1 - multithreaded 
  233.       vac3           IBM VisualAge C++ V3.0 for OS/2 
  234.  
  235.       Provided that you have installed the Workplace Shell Toolkit in a 
  236.       directory d:\wpstk, you extend the variables as follows in 
  237.  
  238.         -  your config.sys file (This is not recommended, if you use different 
  239.            library versions at a time !) 
  240.  
  241.                                 SET INCLUDE=d:\wpstk\include;<existing_include_path>
  242.                                 SET LIB=d:\wpstk\lib\<subdir>;<existing_lib_path>
  243.                                 SET BOOKSHELF=d:\wpstk\book;<existing_bookshelf_path>
  244.                                 SET HELPNDX=<existing_help_index_list>+d:\wpstk\book\wpstk.ndx
  245.  
  246.         -  a batch file 
  247.  
  248.                                 SET INCLUDE=d:\wpstk\include;%INCLUDE%
  249.                                 SET LIB=d:\wpstk\lib\<subdir>;%LIB%
  250.                                 SET BOOKSHELF=d:\wpstk\book;%BOOKSHELF%
  251.                                 SET HELPNDX=%HELPNDX%+d:\wpstk\book\wpstk.ndx
  252.  
  253.         -  a makefile 
  254.  
  255.                                 INCLUDE=d:\wpstk\include;$(INCLUDE)
  256.                                 LIB=d:\wpstk\lib\<subdir>;$(LIB)
  257.                                 BOOKSHELF=d:\wpstk\book;$(BOOKSHELF)
  258.                                 HELPNDX=$(HELPNDX)+d:\wpstk\book\wpstk.ndx
  259.  
  260.      You are required to use NMAKE as the make tool to compile the toolkit and 
  261.       its samples. Using GNU make is not supported for the IBM compilers. 
  262.  
  263.      If you use the EPM when developing programs, you might further want to 
  264.       use the syntax-highlight extension for empkwds.c provided with the 
  265.       Workplace Shell Toolkit in order to have function names and defines of it 
  266.       highlighted. Simply append the contents of the file book\epm\epmkwds.c__ 
  267.       to the file epmkwds.c in your EPM directory and restart the EPM. 
  268.  
  269.  
  270. ΓòÉΓòÉΓòÉ 4.2. emx 0.9d for OS/2 - Prerequisites ΓòÉΓòÉΓòÉ
  271.  
  272. The following prerequisites apply when using the Workplace Shell Toolkit with 
  273. the emx compiler: 
  274.  
  275.      Users of a source distribution of the Workplace Shell Toolkit are 
  276.       required to download it via CVS to an HPFS drive. A HPFS partition is 
  277.       also required in order to to compile it completely. One could copy a CVS 
  278.       development tree to a FAT partition, but then would have to manually copy 
  279.       the former GNUmakefile over the makefile in each directory, where 
  280.       existing. This would allow to compile at least the library itself and the 
  281.       sample programs, but the online docs could not be compiled, as the source 
  282.       files for this require long filenames. 
  283.  
  284.      Users of a binary distribution of the Workplace Shell Toolkit (not 
  285.       including the sources for the library or online doc) can install it onto 
  286.       a FAT drive, as long they need not to compile the sample programs. 
  287.  
  288.      You are reqired to append the pathname include and lib directories of the 
  289.       installed Workplace Shell Toolkit to the C_INCLUDE_PATH and LIBRARY_PATH 
  290.       environment variables. Optionally, if you use the EPM, you might also 
  291.       want to add the help index file to the HELPNDX environment variable. 
  292.  
  293.       Note: 
  294.  
  295.         -  when you compile the Workplace Shell Toolkit yourself, the resulting 
  296.            libraries are put into directories named either debug or release 
  297.            instead of lib, depending on the debug status during compilation. 
  298.         -  The emx reference states that all pathnames in the environment 
  299.            variables C_INCLUDE_PATH and LIBRARY_PATH should not include 
  300.            backslashes, but only forward slashes. Normally, you should not 
  301.            experience any problems when using backslashes, but in order to be 
  302.            on the safe side the makefiles of the Workplace Shell Toolkit will 
  303.            convert backslashes to forward slashes within these variables during 
  304.            the makefile process. 
  305.         -  It is strongly recommended to setup the LIB environment variable to 
  306.            the same value as the environment variable LIBRARY_PATH. The 
  307.            Workplace Shell Toolkit must be compiled and can link only in the 
  308.            OMF format and thus uses LINK386.EXE, which in turn uses the LIB 
  309.            environment variable instead of LIBRARY_PATH. 
  310.            The Workplace Shell Toolkit will not enforce this automatically, as 
  311.            this severely changes your system configuration. You should be the 
  312.            person to do so... 
  313.  
  314.       You can extend the environment variables either in 
  315.  
  316.         -  your config.sys file (not recommended !) 
  317.         -  a batch file that you use to call to setup your environment. 
  318.            you may want to use the batchfile bin\wtkenv.cmd, setting up the 
  319.            environment automatically 
  320.         -  your makefile 
  321.  
  322.       Provided that you have installed the Workplace Shell Toolkit in a 
  323.       directory d:\wpstk, you extend the variables as follows in 
  324.  
  325.         -  your config.sys file 
  326.  
  327.                                 SET C_INCLUDE_PATH=d:\wpstk\include;<existing_c_include_path>
  328.                                 SET LIBRARY_PATH=d:\wpstk\lib\gcc;<existing_library_path>
  329.                                 SET BOOKSHELF=d:\wpstk\book;<existing_bookshelf_path>
  330.                                 SET HELPNDX=<existing_help_index_list>+d:\wpstk\book\wpstk.ndx
  331.  
  332.         -  a batch file 
  333.  
  334.                                 SET C_INCLUDE_PATH=d:\wpstk\include;%C_INCLUDE_PATH%
  335.                                 SET LIBRARY_PATH=d:\wpstk\lib\gcc;%LIBRARY_PATH%
  336.                                 SET BOOKSHELF=d:\wpstk\book;%BOOKSHELF%
  337.                                 SET HELPNDX=%HELPNDX%+d:\wpstk\book\wpstk.ndx
  338.  
  339.         -  a makefile 
  340.  
  341.                                 C_INCLUDE_PATH=d:\wpstk\include;$(C_INCLUDE_PATH)
  342.                                 LIBRARY_PATH=d:\wpstk\lib\gcc;$(LIBRARY_PATH)
  343.                                 BOOKSHELF=d:\wpstk\book;$(BOOKSHELF)
  344.                                 HELPNDX=$(HELPNDX)+d:\wpstk\book\wpstk.ndx
  345.  
  346.      The Workplace Shell Toolkit must be compiled and can be linked only in 
  347.       the OMF format. To prepare your system for this, all GNUmakefiles 
  348.       implicitely call bin/config.cmd to determine, wether the OMF versions 
  349.       (.lib) of the emx libraries (.a) are already present. If not, it creates 
  350.       them directly in the lib directory of the emx compiler tree. 
  351.  
  352.       See also 
  353.  
  354.            emx 0.9d for OS/2 - makefile configuration 
  355.  
  356.       Note: 
  357.  
  358.         -  If the OMF versions of the emx libraries do not already exist in the 
  359.            lib directory of the emx compiler tree, write access and approx. 4 
  360.            MB free disk space are required on the drive, where you have 
  361.            installed the emx compiler in order to create them. 
  362.  
  363.      You are required to use GNU make as the make tool to compile the toolkit 
  364.       and its samples. Using NMAKE is not supported for the emx compiler. 
  365.  
  366.      If you use the EPM when developing programs, you might further want to 
  367.       use the syntax-highlight extension for empkwds.c provided with the 
  368.       Workplace Shell Toolkit in order to have function names and defines of it 
  369.       highlighted. Simply append the contents of the file book\epm\epmkwds.c__ 
  370.       to the file epmkwds.c in your EPM directory and restart the EPM. 
  371.  
  372.  
  373. ΓòÉΓòÉΓòÉ 5. Limitations ΓòÉΓòÉΓòÉ
  374.  
  375. The Workplace Shell Toolkit has not been tested with Object Rexx activated, so 
  376. errors might occurr using the makefiles, which in turn call Rexx scripts. If 
  377. errors occurr, please send a report to wpstk@netlabs.org. 
  378.  
  379.  
  380. ΓòÉΓòÉΓòÉ 6. Limitations for specific compilers ΓòÉΓòÉΓòÉ
  381.  
  382. The following prerequisites apply when using the Workplace Shell Toolkit with 
  383. one of the following compilers: 
  384.  
  385.      emx 0.9d for OS/2 
  386.  
  387.  
  388. ΓòÉΓòÉΓòÉ 6.1. Limitations for emx 0.9d for OS/2 ΓòÉΓòÉΓòÉ
  389.  
  390. The following limitations apply when using the Workplace Shell Toolkit with the 
  391. emx compiler: 
  392.  
  393.      The Workplace Shell Toolkit must be compiled and can be linked only in 
  394.       the OMF format, as only with this format a standalone DLL for Workplace 
  395.       Shell classes can be compiled (gcc flags -Zsys and -Zso can only be used 
  396.       with -Zomf). 
  397.  
  398.      Due to several reasons, emx compiled Workplace Shell DLLs cannot be 
  399.       debugged with the GNU debugger. If you require debug information, use the 
  400.       pmprintf technique to obtain information what your program does when 
  401.       running. 
  402.  
  403.       Also the test programs cannot be debugged with GDB, as GDB can debug only 
  404.       DOS programs or bound programs (DOS and OS/2). 
  405.  
  406.       For more information, please refer to method E3 for creating executables 
  407.       with the emx compiler under OS/2: 
  408.  
  409.            Introduction to the emx Application Developer's Guide 
  410.  
  411.  
  412. ΓòÉΓòÉΓòÉ 7. Linking the the Workplace Shell Toolkit runtime ΓòÉΓòÉΓòÉ
  413.  
  414. The Workplace Shell Toolkit can be linked to your application in two ways: 
  415.  
  416.      directly to your application, linking the compiler dependent code library 
  417.       wpstk.lib 
  418.      to the runtime DLL wpstk.dll, linking the compiler dependent import 
  419.       library wpstki.lib 
  420.  
  421.  Note: 
  422.  
  423.      For single Workplace Shell class DLLs or single executables direct code 
  424.       linkage is recommended. 
  425.      It is no good idea to copy the runtime DLL with the original name 
  426.       wpstk.dll to a directory within the LIBPATH on a target system, as this 
  427.       would prevent from loading any other version of it once it is loaded in 
  428.       memory and used by an application or Workplace Shell class DLL. 
  429.  
  430.  Having said that, if you plan to ship the runtime DLL for usage with multiple 
  431.  binaries (exe or DLL) of your application package, it is recommended to 
  432.  perform one or all of the following steps in order not to interfere with older 
  433.  versions of the runtime, having possibly an incompatible API: 
  434.  
  435.      run a DLLRNAME utility onto a copy of wpstk.dll and the executables being 
  436.       linked to it and so ship the DLL with a different name (as a DLL must 
  437.       comply to 8.3) 
  438.      explicitely check the version number of wpstk.dll within the startup code 
  439.       of your application and exit, if it does not apply to the version 
  440.       required. This makes sense even with a renamed runtime DLL for the case, 
  441.       if older versions of your application package are already installed and 
  442.       accidentally newer binaries are installed to a system without updating 
  443.       the runtime DLL. 
  444.  
  445.  While the code and import libraries are well compiler dependent and therefore 
  446.  a version for each supported compiler is 
  447.  
  448.      created in the directories debug or release within the development tree 
  449.       of a source distribution 
  450.      shipped in the directory lib within the installation tree of a binary 
  451.       distibution, 
  452.  
  453.  the runtime DLLs can be mixed between compilers. All DLLs are linked with a 
  454.  standalone mutlithreading compiler runtime and using system linkage, so that 
  455.  they are compatible among binaries linked to them, being complied with 
  456.  different of the supported compilers. 
  457.  
  458.  
  459. ΓòÉΓòÉΓòÉ 8. Workplace Shell Toolkit Functions ΓòÉΓòÉΓòÉ
  460.  
  461. This chapter contains a list of the functions available in the Workplace Shell 
  462. Toolkit. 
  463.  
  464.  WPS Toolkit version function 
  465.  
  466.      WtkQueryVersion 
  467.  
  468.   Module helper functions (EXE and DLL) 
  469.  
  470.      WtkGetModuleHandle 
  471.      WtkGetModuleInfo 
  472.      WtkGetPackageFilename 
  473.  
  474.   PM control helper functions 
  475.  
  476.      WtkInitializeNumSpinbuttonArray 
  477.      WtkIsOfPublicPmClass 
  478.      WtkQueryClassIndex 
  479.      WtkQueryNumSpinbuttonIndex 
  480.  
  481.   System helper functions 
  482.  
  483.      WtkIsWarp4 
  484.      WtkQueryBootDrive 
  485.      WtkQuerySysLanguage 
  486.  
  487.   device IO control helper functions 
  488.  
  489.      WtkDevIOCtl 
  490.      WtkOpenDevice 
  491.  
  492.   Error helper functions 
  493.  
  494.      WtkSetErrorInfo 
  495.  
  496.   File helper functions 
  497.  
  498.      WtkCreatePath 
  499.      WtkCreateTmpFile 
  500.      WtkDeletePath 
  501.      WtkDirExists 
  502.      WtkFileExists 
  503.      WtkFileMaskExists 
  504.      WtkFileModified 
  505.      WtkFilespec 
  506.      WtkGetNextDirectory 
  507.      WtkGetNextFile 
  508.      WtkIsDirectory 
  509.      WtkIsFile 
  510.      WtkQueryCurrentDir 
  511.      WtkQueryFileSize 
  512.      WtkQueryFullname 
  513.      WtkReadFile 
  514.      WtkSetCurrentDir 
  515.      WtkWriteFile 
  516.  
  517.   Date and time related helper functions 
  518.  
  519.      WtkCDateTimeToTime 
  520.      WtkDateTimeToTime 
  521.      WtkFDateTimeToTime 
  522.      WtkQueryCDateTimeStamp 
  523.      WtkQueryDateTimeStamp 
  524.      WtkQueryFDateTimeStamp 
  525.      WtkQueryFileCDateTime 
  526.      WtkQueryFileDateTime 
  527.      WtkQueryFileFDateTime 
  528.      WtkSetCDateTime 
  529.      WtkSetDateTime 
  530.      WtkSetFDateTime 
  531.      WtkTimeToCDateTime 
  532.      WtkTimeToDateTime 
  533.      WtkTimeToFDateTime 
  534.  
  535.   CRC related helper functions 
  536.  
  537.      WtkCalcFileCRC32 
  538.      WtkCalcMemCRC32 
  539.  
  540.   Text Message File functions 
  541.  
  542.      WtkGetTextMessage 
  543.  
  544.   Settings and details manager functions 
  545.  
  546.      WtkAddClassDetail 
  547.      WtkAddClassSetting 
  548.      WtkCloseClassSettingsTable 
  549.      WtkCreateClassSettingsTable 
  550.      WtkCreateObjectValueTable 
  551.      WtkDeregisterSettingsDialog 
  552.      WtkDestroyClassSettingsTable 
  553.      WtkDestroyObjectValueTable 
  554.      WtkDumpClassSettingsTable 
  555.      WtkEvaluateObjectSettings 
  556.      WtkQueryClassDetailsInfo 
  557.      WtkQueryGUIControlsChanged 
  558.      WtkQueryObjectDetailsData 
  559.      WtkQueryObjectSettings 
  560.      WtkReadObjectValueTable 
  561.      WtkRegisterSettingsDialog 
  562.      WtkRegisterSettingsNotebook 
  563.      WtkRelocateNotebookpageControls 
  564.      WtkRestoreObjectSettings 
  565.      WtkRestoreObjectState 
  566.      WtkSaveObjectSettings 
  567.      WtkSaveObjectState 
  568.      WtkValidateObjectValueTable 
  569.      WtkWriteObjectValueTable 
  570.  
  571.   Extended Attributes manager functions 
  572.  
  573.      WtkAppendEaValue 
  574.      WtkCloseEa 
  575.      WtkCreateEa 
  576.      WtkFindFirstEaValue 
  577.      WtkFindNextEaValue 
  578.      WtkGetNextEaValue 
  579.      WtkPutEaValue 
  580.      WtkQueryEaSize 
  581.      WtkReadEa 
  582.      WtkReadStringEa 
  583.      WtkSaveEa 
  584.      WtkWriteStringEa 
  585.  
  586.   Memory Mapped Files manager functions 
  587.  
  588.      WtkAllocMmf 
  589.      WtkFreeMmf 
  590.      WtkInitializeMmf 
  591.      WtkQueryMmfSize 
  592.      WtkSetMmfSize 
  593.      WtkTerminateMmf 
  594.      WtkUpdateMmf 
  595.  
  596.  
  597. ΓòÉΓòÉΓòÉ 8.1. WtkAddClassDetail ΓòÉΓòÉΓòÉ
  598.  
  599. Select an item: 
  600.  
  601.      Syntax 
  602.      Parameters 
  603.      Returns 
  604.      Remarks 
  605.      Related Functions 
  606.  
  607.  
  608. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassDetail - Syntax ΓòÉΓòÉΓòÉ
  609.  
  610. This function adds a detail to the class settings table. 
  611.  
  612. #define INCL_WTKSETTINGS
  613. #include <wpstk.h>
  614.  
  615. HSETTINGTABLE   hst;           /* Settingstable handle.  */
  616. ULONG           ulSettingId;   /* Settings ID.           */
  617. BOOL            fResult;       /* Success indicator.     */
  618.  
  619. fResult = WtkAddClassDetail( hst, ulSettingId);
  620.  
  621.  
  622. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassDetail - Parameter hst ΓòÉΓòÉΓòÉ
  623.  
  624. hst (HSETTINGTABLE) - input 
  625.     Settingstable handle. 
  626.  
  627.  
  628. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassDetail - Parameter ulSettingId ΓòÉΓòÉΓòÉ
  629.  
  630. ulSettingId (ULONG) - input 
  631.     Settings ID. 
  632.  
  633.     This ID must be greater than zero and unique among all settings and details 
  634.     added to a class settingstable. While it is used to save and restores 
  635.     object instance settings values to or from the WPS repository, details are 
  636.     not stored, but still need an ID to be uniquely identified, as they do not 
  637.     have a symbolic name. 
  638.  
  639.     See also the remarks on the same parameter ulSettingId for the function 
  640.     WtkAddClassSetting, as both APIs work nearly the same ! 
  641.  
  642.  
  643. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassDetail - Parameters ΓòÉΓòÉΓòÉ
  644.  
  645. hst (HSETTINGTABLE) - input 
  646.     Settingstable handle. 
  647.  
  648.  ulSettingId (ULONG) - input 
  649.     Settings ID. 
  650.  
  651.     This ID must be greater than zero and unique among all settings and details 
  652.     added to a class settingstable. While it is used to save and restores 
  653.     object instance settings values to or from the WPS repository, details are 
  654.     not stored, but still need an ID to be uniquely identified, as they do not 
  655.     have a symbolic name. 
  656.  
  657.     See also the remarks on the same parameter ulSettingId for the function 
  658.     WtkAddClassSetting, as both APIs work nearly the same ! 
  659.  
  660.  fResult (BOOL) - returns 
  661.     Success indicator. 
  662.  
  663.     TRUE 
  664.               Detail could be added to the class settings table 
  665.     FALSE 
  666.               An error occurred. 
  667.  
  668.  
  669. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassDetail Return Value - fResult ΓòÉΓòÉΓòÉ
  670.  
  671. fResult (BOOL) - returns 
  672.     Success indicator. 
  673.  
  674.     TRUE 
  675.               Detail could be added to the class settings table 
  676.     FALSE 
  677.               An error occurred. 
  678.  
  679.  
  680. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassDetail - Remarks ΓòÉΓòÉΓòÉ
  681.  
  682. This function is to be called during _wpclsInitData, right after having created 
  683. the class settingstable with WtkCreateClassSettingsTable. 
  684.  
  685. WtkAddClassDetail has to be called once for each detail to be added to the 
  686. class settingstable. 
  687.  
  688. After having added all details and settings to class settingstable, the WPS 
  689. Class needs to close the class settingstable with WtkCloseClassSettingsTable in 
  690. order make the table available for the objects (instances) of the WPS class. 
  691.  
  692.  
  693. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassDetail - Related functions ΓòÉΓòÉΓòÉ
  694.  
  695. Related Functions 
  696.  
  697. none 
  698.  
  699.  
  700. ΓòÉΓòÉΓòÉ 8.2. WtkAddClassSetting ΓòÉΓòÉΓòÉ
  701.  
  702. Select an item: 
  703.  
  704.      Syntax 
  705.      Parameters 
  706.      Returns 
  707.      Remarks 
  708.      Related Functions 
  709.  
  710.  
  711. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting - Syntax ΓòÉΓòÉΓòÉ
  712.  
  713. This function adds a setting to the class settings table. 
  714.  
  715. #define INCL_WTKSETTINGS
  716. #include <wpstk.h>
  717.  
  718. HSETTINGTABLE   hst;            /* Settingstable handle.                                                */
  719. ULONG           ulSettingId;    /* Settings ID.                                                         */
  720. PSZ             pszSetting;     /* Address of the ASCIIZ name and default value string of the setting.  */
  721. ULONG           ulQueryCount;   /* Query count of a setting.                                            */
  722. BOOL            fResult;        /* Success indicator.                                                   */
  723.  
  724. fResult = WtkAddClassSetting( hst, ulSettingId, pszSetting, ulQueryCount);
  725.  
  726.  
  727. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting - Parameter hst ΓòÉΓòÉΓòÉ
  728.  
  729. hst (HSETTINGTABLE) - input 
  730.     Settingstable handle. 
  731.  
  732.  
  733. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting - Parameter ulSettingId ΓòÉΓòÉΓòÉ
  734.  
  735. ulSettingId (ULONG) - input 
  736.     Settings ID. 
  737.  
  738.     This ID must be either zero or unique among all settings and details added 
  739.     to a class settingstable. 
  740.  
  741.     Note: 
  742.  
  743.         A none-zero value allows to have the corresponding object instance 
  744.          settings values saved and restored to or from the WPS repository by 
  745.          WtkSaveObjectState and WtkRestoreObjectState. 
  746.  
  747.          For the added setting  a range of settings IDs instead of only the 
  748.          specified one will automatically be reserved for if the setting 
  749.  
  750.            -  has subvalues - this is the case if the string pointed to by 
  751.               pszSetting contains more than one value, separated by commas 
  752.  
  753.            -  and/or can be queried multiple times - this is the case if 
  754.               ulQueryCount is greater than 1 
  755.  
  756.          All IDs within that range cannot be used by other settings. The 
  757.          reserved range will be all IDs from ulSettingId to ulSettingId + 
  758.          (subvaluecount * querycount) - 1. 
  759.  
  760.         If used (not setting this value to zero), do not change this id for a 
  761.          given setting in future versions of your WPS class, otherwise values 
  762.          of existing instances cannot be restored properly with 
  763.          WtkRestoreObjectState. This may lead to unpredictable results ! 
  764.  
  765.         Th same applies to the order of subvalues, they may not be changed in 
  766.          their order, as the calculated ID for a subvalue cannot be changed for 
  767.          existing instances at a later point of time. 
  768.  
  769.  
  770. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting - Parameter pszSetting ΓòÉΓòÉΓòÉ
  771.  
  772. pszSetting (PSZ) - input 
  773.     Address of the ASCIIZ name and default value string of the setting. 
  774.  
  775.     This string must have the form 
  776.  
  777.         NAME=value;
  778.  
  779.     where value can 
  780.  
  781.         may be either empty or specify a default value, which is used, when no 
  782.          value is specified for this setting when a settings string is sended 
  783.          to an object of this class 
  784.         consist of several subvalues, each separated by commas. Each subvalue 
  785.          then may either be empty or specify a default value. For each 
  786.          subvalue, a comma must be included within the string. 
  787.  
  788.     Here are some examples: 
  789.  
  790.         "IPCONFIG=DYNAMIC;"
  791.         "LOCALIP=;"
  792.         "MTU=1500;"
  793.         "DEFAULTROUTE=YES;"
  794.         "COMINIT=9600,n,8,1;"
  795.  
  796.     The following example defines a setting with four subvalues, but with no 
  797.     default values: 
  798.  
  799.         "MYSETTING=,,,;"
  800.  
  801.  
  802. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting - Parameter ulQueryCount ΓòÉΓòÉΓòÉ
  803.  
  804. ulQueryCount (ULONG) - input 
  805.     Query count of a setting. 
  806.  
  807.     This value must not be zero! It may be set to a value 
  808.  
  809.         of one, indicating that this setting can have only one value. 
  810.  
  811.         greater than one, indicating that this setting can have more than one 
  812.          value. 
  813.          When the WPS class determines the current settings by calling 
  814.          WtkQueryObjectSettings or saves the settings with either 
  815.          WtkSaveObjectState or WtkSaveObjectSettings, the Settings Manager asks 
  816.          the callback of the WPS class "ulQueryCount" times for the current 
  817.          value of that setting. 
  818.  
  819.          For to be able to handle a setting with multiple values, it needs to 
  820.          have at least one subvalue per dimension to build up a twodimensional 
  821.          matrix internally. 
  822.  
  823.          An example for a multidimensional setting is: 
  824.  
  825.          name                     CURRENTDIR 
  826.  
  827.          value 1                  drive 
  828.  
  829.          value 2                  current dir of drive 
  830.  
  831.          In order to query all drives, you would set ulQueryCount to 26 and let 
  832.          WtkQueryObjectSettings query 26 times the value for the setting 
  833.          CURRENTDIR. When being asked for that setting, you would place the 
  834.          current directory of the drive into the target buffer for that setting 
  835.          accoring to the query index (0-25). WtkQueryObjectSettings would then 
  836.          place somewhat like this into the resulting settingstring: 
  837.  
  838.                   "CURRENTDIR=A:,\;"
  839.                   "CURRENTDIR=C:,\OS2;"
  840.                   "CURRENTDIR=D:,\TCPIP;"
  841.                   etc.
  842.  
  843.          The alternative would be to define a separate setting for each drive 
  844.          (CURRENTDIRA, CURRENTDIRB) or have a separate WPS class for such 
  845.          instances. 
  846.  
  847.  
  848. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting - Parameters ΓòÉΓòÉΓòÉ
  849.  
  850. hst (HSETTINGTABLE) - input 
  851.     Settingstable handle. 
  852.  
  853.  ulSettingId (ULONG) - input 
  854.     Settings ID. 
  855.  
  856.     This ID must be either zero or unique among all settings and details added 
  857.     to a class settingstable. 
  858.  
  859.     Note: 
  860.  
  861.         A none-zero value allows to have the corresponding object instance 
  862.          settings values saved and restored to or from the WPS repository by 
  863.          WtkSaveObjectState and WtkRestoreObjectState. 
  864.  
  865.          For the added setting  a range of settings IDs instead of only the 
  866.          specified one will automatically be reserved for if the setting 
  867.  
  868.            -  has subvalues - this is the case if the string pointed to by 
  869.               pszSetting contains more than one value, separated by commas 
  870.  
  871.            -  and/or can be queried multiple times - this is the case if 
  872.               ulQueryCount is greater than 1 
  873.  
  874.          All IDs within that range cannot be used by other settings. The 
  875.          reserved range will be all IDs from ulSettingId to ulSettingId + 
  876.          (subvaluecount * querycount) - 1. 
  877.  
  878.         If used (not setting this value to zero), do not change this id for a 
  879.          given setting in future versions of your WPS class, otherwise values 
  880.          of existing instances cannot be restored properly with 
  881.          WtkRestoreObjectState. This may lead to unpredictable results ! 
  882.  
  883.         Th same applies to the order of subvalues, they may not be changed in 
  884.          their order, as the calculated ID for a subvalue cannot be changed for 
  885.          existing instances at a later point of time. 
  886.  
  887.  pszSetting (PSZ) - input 
  888.     Address of the ASCIIZ name and default value string of the setting. 
  889.  
  890.     This string must have the form 
  891.  
  892.         NAME=value;
  893.  
  894.     where value can 
  895.  
  896.         may be either empty or specify a default value, which is used, when no 
  897.          value is specified for this setting when a settings string is sended 
  898.          to an object of this class 
  899.         consist of several subvalues, each separated by commas. Each subvalue 
  900.          then may either be empty or specify a default value. For each 
  901.          subvalue, a comma must be included within the string. 
  902.  
  903.     Here are some examples: 
  904.  
  905.         "IPCONFIG=DYNAMIC;"
  906.         "LOCALIP=;"
  907.         "MTU=1500;"
  908.         "DEFAULTROUTE=YES;"
  909.         "COMINIT=9600,n,8,1;"
  910.  
  911.     The following example defines a setting with four subvalues, but with no 
  912.     default values: 
  913.  
  914.         "MYSETTING=,,,;"
  915.  
  916.  ulQueryCount (ULONG) - input 
  917.     Query count of a setting. 
  918.  
  919.     This value must not be zero! It may be set to a value 
  920.  
  921.         of one, indicating that this setting can have only one value. 
  922.  
  923.         greater than one, indicating that this setting can have more than one 
  924.          value. 
  925.          When the WPS class determines the current settings by calling 
  926.          WtkQueryObjectSettings or saves the settings with either 
  927.          WtkSaveObjectState or WtkSaveObjectSettings, the Settings Manager asks 
  928.          the callback of the WPS class "ulQueryCount" times for the current 
  929.          value of that setting. 
  930.  
  931.          For to be able to handle a setting with multiple values, it needs to 
  932.          have at least one subvalue per dimension to build up a twodimensional 
  933.          matrix internally. 
  934.  
  935.          An example for a multidimensional setting is: 
  936.  
  937.          name                     CURRENTDIR 
  938.  
  939.          value 1                  drive 
  940.  
  941.          value 2                  current dir of drive 
  942.  
  943.          In order to query all drives, you would set ulQueryCount to 26 and let 
  944.          WtkQueryObjectSettings query 26 times the value for the setting 
  945.          CURRENTDIR. When being asked for that setting, you would place the 
  946.          current directory of the drive into the target buffer for that setting 
  947.          accoring to the query index (0-25). WtkQueryObjectSettings would then 
  948.          place somewhat like this into the resulting settingstring: 
  949.  
  950.                   "CURRENTDIR=A:,\;"
  951.                   "CURRENTDIR=C:,\OS2;"
  952.                   "CURRENTDIR=D:,\TCPIP;"
  953.                   etc.
  954.  
  955.          The alternative would be to define a separate setting for each drive 
  956.          (CURRENTDIRA, CURRENTDIRB) or have a separate WPS class for such 
  957.          instances. 
  958.  
  959.  fResult ( BOOL) - returns 
  960.     Success indicator. 
  961.  
  962.     TRUE 
  963.               Setting could be added to the class settings table 
  964.     FALSE 
  965.               An error occurred. 
  966.  
  967.  
  968. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting Return Value - fResult ΓòÉΓòÉΓòÉ
  969.  
  970. fResult (BOOL) - returns 
  971.     Success indicator. 
  972.  
  973.     TRUE 
  974.               Setting could be added to the class settings table 
  975.     FALSE 
  976.               An error occurred. 
  977.  
  978.  
  979. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting - Remarks ΓòÉΓòÉΓòÉ
  980.  
  981. This function is to be called during _wpclsInitData, right after having created 
  982. the class settingstable with WtkCreateClassSettingsTable. 
  983.  
  984. WtkAddClassSetting has to be called once for each setting to be added to the 
  985. class settingstable. 
  986.  
  987. After having added all details and settings to class settingstable, the WPS 
  988. Class needs to close the class settingstable with WtkCloseClassSettingsTable in 
  989. order make the table available for the objects (instances) of the WPS class. 
  990.  
  991.  
  992. ΓòÉΓòÉΓòÉ <hidden> WtkAddClassSetting - Related functions ΓòÉΓòÉΓòÉ
  993.  
  994. Related Functions 
  995.  
  996. none 
  997.  
  998.  
  999. ΓòÉΓòÉΓòÉ 8.3. WtkAllocMmf ΓòÉΓòÉΓòÉ
  1000.  
  1001. Select an item: 
  1002.  
  1003.      Syntax 
  1004.      Parameters 
  1005.      Returns 
  1006.      Remarks 
  1007.      Related Functions 
  1008.  
  1009.  
  1010. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Syntax ΓòÉΓòÉΓòÉ
  1011.  
  1012. This function allocates a dynamic memory buffer either for a file or plain 
  1013. memory access. 
  1014.  
  1015. #define INCL_WTKMMF
  1016. #include <wpstk.h>
  1017.  
  1018. HMMF     hmmf;          /* Handle to the MMF manager.                                                   */
  1019. PVOID    *ppvdata;      /* Pointer to a variable receiving the pointer to the allocated address space.  */
  1020. PSZ      pszFilename;   /* Address of the ASCIIZ path name or MMF_FILE_INMEMORY.                        */
  1021. ULONG    ulOpenFlags;   /* Access and open mode flags for file access.                                  */
  1022. ULONG    ulMaxSize;     /* Maximum possible size of the dynamic memory in bytes.                        */
  1023. APIRET   ulrc;          /* Return Code.                                                                 */
  1024.  
  1025. ulrc = WtkAllocMmf( hmmf, *ppvdata, pszFilename, ulOpenFlags, ulMaxSize);
  1026.  
  1027.  
  1028. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Parameter hmmf ΓòÉΓòÉΓòÉ
  1029.  
  1030. hmmf (HMMF) - input 
  1031.     Handle to the MMF manager. 
  1032.  
  1033.  
  1034. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Parameter *ppvdata ΓòÉΓòÉΓòÉ
  1035.  
  1036. *ppvdata (PVOID) - output 
  1037.     Pointer to a variable receiving the pointer to the allocated address space. 
  1038.  
  1039.  
  1040. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Parameter pszFilename ΓòÉΓòÉΓòÉ
  1041.  
  1042. pszFilename (PSZ) - input 
  1043.     Address of the ASCIIZ path name or MMF_FILE_INMEMORY. 
  1044.  
  1045.     If no file is specified, MMF_FILE_INMEMORY (equals NULL) will allocate a 
  1046.     dynamic memory buffer only. 
  1047.  
  1048.     The path name may contain ?: for the drive in order to open the file on the 
  1049.     boot drive. 
  1050.  
  1051.     The name may not include wildcards. 
  1052.  
  1053.  
  1054. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Parameter ulOpenFlags ΓòÉΓòÉΓòÉ
  1055.  
  1056. ulOpenFlags (ULONG) - input 
  1057.     Access and open mode flags for file access. 
  1058.  
  1059.     The following access modes are valid (specify one): 
  1060.  
  1061.     MMF_ACCESS_READONLY 
  1062.               open file in readonly mode and deny write by others (default) 
  1063.  
  1064.     MMF_ACCESS_WRITEONLY 
  1065.               open file in writeonly mode and deny write by others 
  1066.  
  1067.     MMF_ACCESS_READWRITE 
  1068.               open file in readwrite mode and deny read and write by others 
  1069.  
  1070.     The following open modes are valid (specify one): 
  1071.  
  1072.     MMF_OPENMODE_OPENFILE 
  1073.               open existing file or create new one 
  1074.  
  1075.     MMF_OPENMODE_RESETFILE 
  1076.               reset existing file or create new one 
  1077.  
  1078.  
  1079. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Parameter ulMaxSize ΓòÉΓòÉΓòÉ
  1080.  
  1081. ulMaxSize (ULONG) - input 
  1082.     Maximum possible size of the dynamic memory in bytes. 
  1083.  
  1084.     This maximum size cannot be changed later. 
  1085.  
  1086.  
  1087. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Parameters ΓòÉΓòÉΓòÉ
  1088.  
  1089. hmmf (HMMF) - input 
  1090.     Handle to the MMF manager. 
  1091.  
  1092.  *ppvdata (PVOID) - output 
  1093.     Pointer to a variable receiving the pointer to the allocated address space. 
  1094.  
  1095.  pszFilename (PSZ) - input 
  1096.     Address of the ASCIIZ path name or MMF_FILE_INMEMORY. 
  1097.  
  1098.     If no file is specified, MMF_FILE_INMEMORY (equals NULL) will allocate a 
  1099.     dynamic memory buffer only. 
  1100.  
  1101.     The path name may contain ?: for the drive in order to open the file on the 
  1102.     boot drive. 
  1103.  
  1104.     The name may not include wildcards. 
  1105.  
  1106.  ulOpenFlags (ULONG) - input 
  1107.     Access and open mode flags for file access. 
  1108.  
  1109.     The following access modes are valid (specify one): 
  1110.  
  1111.     MMF_ACCESS_READONLY 
  1112.               open file in readonly mode and deny write by others (default) 
  1113.  
  1114.     MMF_ACCESS_WRITEONLY 
  1115.               open file in writeonly mode and deny write by others 
  1116.  
  1117.     MMF_ACCESS_READWRITE 
  1118.               open file in readwrite mode and deny read and write by others 
  1119.  
  1120.     The following open modes are valid (specify one): 
  1121.  
  1122.     MMF_OPENMODE_OPENFILE 
  1123.               open existing file or create new one 
  1124.  
  1125.     MMF_OPENMODE_RESETFILE 
  1126.               reset existing file or create new one 
  1127.  
  1128.  ulMaxSize (ULONG) - input 
  1129.     Maximum possible size of the dynamic memory in bytes. 
  1130.  
  1131.     This maximum size cannot be changed later. 
  1132.  
  1133.  ulrc (APIRET) - returns 
  1134.     Return Code. 
  1135.  
  1136.     WtkAllocMmf returns one of the following return codes: 
  1137.  
  1138.     0         NO_ERROR 
  1139.     4         ERROR_TOO_MANY_OPEN_FILES 
  1140.     6         ERROR_INVALID_HANDLE 
  1141.     87        ERROR_INVALID_PARAMETER 
  1142.     111       ERROR_BUFFER_OVERFLOW 
  1143.  
  1144.     or return codes of the following functions 
  1145.  
  1146.         DosOpen 
  1147.         DosAllocMem 
  1148.  
  1149.  
  1150. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf Return Value - ulrc ΓòÉΓòÉΓòÉ
  1151.  
  1152. ulrc (APIRET) - returns 
  1153.     Return Code. 
  1154.  
  1155.     WtkAllocMmf returns one of the following return codes: 
  1156.  
  1157.     0         NO_ERROR 
  1158.     4         ERROR_TOO_MANY_OPEN_FILES 
  1159.     6         ERROR_INVALID_HANDLE 
  1160.     87        ERROR_INVALID_PARAMETER 
  1161.     111       ERROR_BUFFER_OVERFLOW 
  1162.  
  1163.     or return codes of the following functions 
  1164.  
  1165.         DosOpen 
  1166.         DosAllocMem 
  1167.  
  1168.  
  1169. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Remarks ΓòÉΓòÉΓòÉ
  1170.  
  1171. This function supports boot drive recognition. Specify ?: for the drive in 
  1172. order to open the file on the boot drive. 
  1173.  
  1174. The file is kept open until WtkFreeMmf is called to release the provided memory 
  1175. buffer again. Until that reading or writing to that file by others is denied 
  1176. according to the access flags specified for parameter ulOpenFlags. 
  1177.  
  1178. The memory requested my WtkAllocMmf is not committed by default. This means 
  1179. requestion large amounts of memory will not lead to requesting physical memory 
  1180. of that size, but only reserving the address space. Memory is then committed by 
  1181. the MMF exception handler only when accessed either for read or write. 
  1182.  
  1183. Nevertheless it is a good idea not to reserve more address space than needed, 
  1184. as only some hundred megabytes can be addressed per process. 
  1185.  
  1186.  
  1187. ΓòÉΓòÉΓòÉ <hidden> WtkAllocMmf - Related functions ΓòÉΓòÉΓòÉ
  1188.  
  1189. Related Functions 
  1190.  
  1191. none 
  1192.  
  1193.  
  1194. ΓòÉΓòÉΓòÉ 8.4. WtkAppendEaValue ΓòÉΓòÉΓòÉ
  1195.  
  1196. Select an item: 
  1197.  
  1198.      Syntax 
  1199.      Parameters 
  1200.      Returns 
  1201.      Remarks 
  1202.      Related Functions 
  1203.  
  1204.  
  1205. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Syntax ΓòÉΓòÉΓòÉ
  1206.  
  1207. This function appends a value to an extended attribute in memory. 
  1208.  
  1209. #define INCL_WTKEAS
  1210. #include <wpstk.h>
  1211.  
  1212. HEA      hea;           /* Handle to the extended attribute.                                     */
  1213. ULONG    ulMultiType;   /* Multitype of the value to be added to the extended attribute.         */
  1214. ULONG    ulEaType;      /* Type of the value to be added to the extended attribute.              */
  1215. PBYTE    pbValue;       /* The address of a buffer of the value to be written.                   */
  1216. ULONG    ulValuelen;    /* The length, in bytes, of the buffer described by pbValue.             */
  1217. APIRET   ulrc;          /* Return Code.                                                          */
  1218.  
  1219. ulrc = WtkAppendEaValue( hea, ulMultiType, ulEaType, pbValue, ulValuelen);
  1220.  
  1221.  
  1222. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Parameter hea ΓòÉΓòÉΓòÉ
  1223.  
  1224. hea (HEA) - input 
  1225.     Handle to the extended attribute. 
  1226.  
  1227.  
  1228. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Parameter ulMultiType ΓòÉΓòÉΓòÉ
  1229.  
  1230. ulMultiType (ULONG) - input 
  1231.     Multitype of the value to be added to the extended attribute. 
  1232.  
  1233.     Specify 
  1234.  
  1235.     EAT_MVST 
  1236.               to add a value to a multi value, single type extended attribute. 
  1237.               This only works, if this is the first value being appended or the 
  1238.               existing extended attribute is already multi value, single type, 
  1239.               and ulEaType is of the same type as the existing value(s). 
  1240.     EAT_MVMT 
  1241.               to add a value to a multi value, multi type extended attribute. 
  1242.               This only works, if this is the first value being appended or the 
  1243.               existing extended attribute is already multi value, multi type. 
  1244.     Other EAT_* 
  1245.               to add a value to a single value, single type extended attribute 
  1246.               This only works, if this is the first value being appended, 
  1247.               otherwise it would not be single value, single type ... 
  1248.  
  1249.  
  1250. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Parameter ulEaType ΓòÉΓòÉΓòÉ
  1251.  
  1252. ulEaType (ULONG) - input 
  1253.     Type of the value to be added to the extended attribute. 
  1254.  
  1255.     Specify 
  1256.  
  1257.     EAT_ASCII 
  1258.               to add a string value 
  1259.     EAT_BINARY 
  1260.               to add a binary value 
  1261.     EAT_ICON 
  1262.               to add an icon 
  1263.     EAT_BITMAP 
  1264.               to add a bitmap 
  1265.     EAT_METAFILE 
  1266.               to add a meta file 
  1267.     EAT_EA 
  1268.               to add the name of an embedded extended attribute as an ASCII 
  1269.               string 
  1270.  
  1271.  
  1272. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Parameter pbValue ΓòÉΓòÉΓòÉ
  1273.  
  1274. pbValue (PBYTE) - input 
  1275.     The address of a buffer of the value to be written. 
  1276.  
  1277.  
  1278. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Parameter ulValuelen ΓòÉΓòÉΓòÉ
  1279.  
  1280. ulValuelen (ULONG) - input 
  1281.     The length, in bytes, of the buffer described by pbValue. 
  1282.  
  1283.  
  1284. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Parameters ΓòÉΓòÉΓòÉ
  1285.  
  1286. hea (HEA) - input 
  1287.     Handle to the extended attribute. 
  1288.  
  1289.  ulMultiType (ULONG) - input 
  1290.     Multitype of the value to be added to the extended attribute. 
  1291.  
  1292.     Specify 
  1293.  
  1294.     EAT_MVST 
  1295.               to add a value to a multi value, single type extended attribute. 
  1296.               This only works, if this is the first value being appended or the 
  1297.               existing extended attribute is already multi value, single type, 
  1298.               and ulEaType is of the same type as the existing value(s). 
  1299.     EAT_MVMT 
  1300.               to add a value to a multi value, multi type extended attribute. 
  1301.               This only works, if this is the first value being appended or the 
  1302.               existing extended attribute is already multi value, multi type. 
  1303.     Other EAT_* 
  1304.               to add a value to a single value, single type extended attribute 
  1305.               This only works, if this is the first value being appended, 
  1306.               otherwise it would not be single value, single type ... 
  1307.  
  1308.  ulEaType (ULONG) - input 
  1309.     Type of the value to be added to the extended attribute. 
  1310.  
  1311.     Specify 
  1312.  
  1313.     EAT_ASCII 
  1314.               to add a string value 
  1315.     EAT_BINARY 
  1316.               to add a binary value 
  1317.     EAT_ICON 
  1318.               to add an icon 
  1319.     EAT_BITMAP 
  1320.               to add a bitmap 
  1321.     EAT_METAFILE 
  1322.               to add a meta file 
  1323.     EAT_EA 
  1324.               to add the name of an embedded extended attribute as an ASCII 
  1325.               string 
  1326.  
  1327.  pbValue (PBYTE) - input 
  1328.     The address of a buffer of the value to be written. 
  1329.  
  1330.  ulValuelen (ULONG) - input 
  1331.     The length, in bytes, of the buffer described by pbValue. 
  1332.  
  1333.  ulrc (APIRET) - returns 
  1334.     Return Code. 
  1335.  
  1336.     WtkAppendEaValue returns one of the following return codes: 
  1337.  
  1338.     0         NO_ERROR 
  1339.     6         ERROR_INVALID_HANDLE 
  1340.     8         ERROR_NOT_ENOUGH_MEMORY 
  1341.     13        ERROR_INVALID_DATA 
  1342.     87        ERROR_INVALID_PARAMETER 
  1343.  
  1344.  
  1345. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue Return Value - ulrc ΓòÉΓòÉΓòÉ
  1346.  
  1347. ulrc (APIRET) - returns 
  1348.     Return Code. 
  1349.  
  1350.     WtkAppendEaValue returns one of the following return codes: 
  1351.  
  1352.     0         NO_ERROR 
  1353.     6         ERROR_INVALID_HANDLE 
  1354.     8         ERROR_NOT_ENOUGH_MEMORY 
  1355.     13        ERROR_INVALID_DATA 
  1356.     87        ERROR_INVALID_PARAMETER 
  1357.  
  1358.  
  1359. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Remarks ΓòÉΓòÉΓòÉ
  1360.  
  1361. This function allocates resources for handling the value of the given extended 
  1362. attribute, which must be freeed by calling WtkCloseEa, when not longer needed. 
  1363.  
  1364.  
  1365. ΓòÉΓòÉΓòÉ <hidden> WtkAppendEaValue - Related functions ΓòÉΓòÉΓòÉ
  1366.  
  1367. Related Functions 
  1368.  
  1369. none 
  1370.  
  1371.  
  1372. ΓòÉΓòÉΓòÉ 8.5. WtkCDateTimeToTime ΓòÉΓòÉΓòÉ
  1373.  
  1374. Select an item: 
  1375.  
  1376.      Syntax 
  1377.      Parameters 
  1378.      Returns 
  1379.      Remarks 
  1380.      Related Functions 
  1381.  
  1382.  
  1383. ΓòÉΓòÉΓòÉ <hidden> WtkCDateTimeToTime - Syntax ΓòÉΓòÉΓòÉ
  1384.  
  1385. This function converts the contents of a CDATE and a CTIME stucture to a time 
  1386. value used by the compiler runtime. 
  1387.  
  1388. #define INCL_WTKUTLTIME
  1389. #include <wpstk.h>
  1390.  
  1391. PCDATE    pcdate;    /* Address of the CDATE structure.       */
  1392. PCTIME    pctime;    /* Address of the CTIME structure.       */
  1393. time_t   *ptime;     /* Address of the resulting time value.  */
  1394. BOOL      fResult;   /* Success indicator.                    */
  1395.  
  1396. fResult = WtkCDateTimeToTime( pcdate, pctime, ptime);
  1397.  
  1398.  
  1399. ΓòÉΓòÉΓòÉ <hidden> WtkCDateTimeToTime - Parameter pcdate ΓòÉΓòÉΓòÉ
  1400.  
  1401. pcdate (PCDATE) - input 
  1402.     Address of the CDATE structure. 
  1403.  
  1404.  
  1405. ΓòÉΓòÉΓòÉ <hidden> WtkCDateTimeToTime - Parameter pctime ΓòÉΓòÉΓòÉ
  1406.  
  1407. pctime (PCTIME) - input 
  1408.     Address of the CTIME structure. 
  1409.  
  1410.  
  1411. ΓòÉΓòÉΓòÉ <hidden> WtkCDateTimeToTime - Parameter ptime ΓòÉΓòÉΓòÉ
  1412.  
  1413. ptime (time_t*) - output 
  1414.     Address of the resulting time value. 
  1415.  
  1416.  
  1417. ΓòÉΓòÉΓòÉ <hidden> WtkCDateTimeToTime - Parameters ΓòÉΓòÉΓòÉ
  1418.  
  1419. pcdate (PCDATE) - input 
  1420.     Address of the CDATE structure. 
  1421.  
  1422.  pctime (PCTIME) - input 
  1423.     Address of the CTIME structure. 
  1424.  
  1425.  ptime (time_t*) - output 
  1426.     Address of the resulting time value. 
  1427.  
  1428.  fResult (BOOL) - returns 
  1429.     Success indicator. 
  1430.  
  1431.     TRUE 
  1432.               Conversion successful. 
  1433.     FALSE 
  1434.               Conversion not successful or invalid parameters. 
  1435.  
  1436.  
  1437. ΓòÉΓòÉΓòÉ <hidden> WtkCDateTimeToTime Return Value - fResult ΓòÉΓòÉΓòÉ
  1438.  
  1439. fResult (BOOL) - returns 
  1440.     Success indicator. 
  1441.  
  1442.     TRUE 
  1443.               Conversion successful. 
  1444.     FALSE 
  1445.               Conversion not successful or invalid parameters. 
  1446.  
  1447.  
  1448. ΓòÉΓòÉΓòÉ <hidden> WtkCDateTimeToTime - Remarks ΓòÉΓòÉΓòÉ
  1449.  
  1450. This function does not check any of the values of the CDATE or CTIME structures 
  1451. before converting. 
  1452.  
  1453.  
  1454. ΓòÉΓòÉΓòÉ <hidden> WtkCDateTimeToTime - Related functions ΓòÉΓòÉΓòÉ
  1455.  
  1456. Related Functions 
  1457.  
  1458. none 
  1459.  
  1460.  
  1461. ΓòÉΓòÉΓòÉ 8.6. WtkCalcFileCRC32 ΓòÉΓòÉΓòÉ
  1462.  
  1463. Select an item: 
  1464.  
  1465.      Syntax 
  1466.      Parameters 
  1467.      Returns 
  1468.      Remarks 
  1469.      Related Functions 
  1470.  
  1471.  
  1472. ΓòÉΓòÉΓòÉ <hidden> WtkCalcFileCRC32 - Syntax ΓòÉΓòÉΓòÉ
  1473.  
  1474. This function calculates a 32-bit CRC for a given file. 
  1475.  
  1476. #define INCL_WTKUTLCRC
  1477. #include <wpstk.h>
  1478.  
  1479. PSZ      pszFilename;   /* Address of the ASCIIZ filename, for which the 32-bit CRC is to be calculated.   */
  1480. PULONG   pulCRC32;      /* The address of a variable, into which the 32-bit CRC for the file is returned.  */
  1481. APIRET   ulrc;          /* Return Code.                                                                    */
  1482.  
  1483. ulrc = WtkCalcFileCRC32( pszFilename, pulCRC32);
  1484.  
  1485.  
  1486. ΓòÉΓòÉΓòÉ <hidden> WtkCalcFileCRC32 - Parameter pszFilename ΓòÉΓòÉΓòÉ
  1487.  
  1488. pszFilename (PSZ) - input 
  1489.     Address of the ASCIIZ filename, for which the 32-bit CRC is to be 
  1490.     calculated. 
  1491.  
  1492.     The path name may contain ?: for the drive in order to read the file from 
  1493.     the boot drive. 
  1494.  
  1495.  
  1496. ΓòÉΓòÉΓòÉ <hidden> WtkCalcFileCRC32 - Parameter pulCRC32 ΓòÉΓòÉΓòÉ
  1497.  
  1498. pulCRC32 (PULONG) - output 
  1499.     The address of a variable, into which the 32-bit CRC for the file is 
  1500.     returned. 
  1501.  
  1502.  
  1503. ΓòÉΓòÉΓòÉ <hidden> WtkCalcFileCRC32 - Parameters ΓòÉΓòÉΓòÉ
  1504.  
  1505. pszFilename (PSZ) - input 
  1506.     Address of the ASCIIZ filename, for which the 32-bit CRC is to be 
  1507.     calculated. 
  1508.  
  1509.     The path name may contain ?: for the drive in order to read the file from 
  1510.     the boot drive. 
  1511.  
  1512.  pulCRC32 (PULONG) - output 
  1513.     The address of a variable, into which the 32-bit CRC for the file is 
  1514.     returned. 
  1515.  
  1516.  ulrc (APIRET) - returns 
  1517.     Return Code. 
  1518.  
  1519.     WtkCalcFileCRC32 returns one of the following return codes: 
  1520.  
  1521.     0         NO_ERROR 
  1522.     8         ERROR_NOT_ENOUGH_MEMORY 
  1523.     87        ERROR_INVALID_PARAMETER 
  1524.  
  1525.     or return codes of the following functions 
  1526.  
  1527.         DosOpen 
  1528.  
  1529.  
  1530. ΓòÉΓòÉΓòÉ <hidden> WtkCalcFileCRC32 Return Value - ulrc ΓòÉΓòÉΓòÉ
  1531.  
  1532. ulrc (APIRET) - returns 
  1533.     Return Code. 
  1534.  
  1535.     WtkCalcFileCRC32 returns one of the following return codes: 
  1536.  
  1537.     0         NO_ERROR 
  1538.     8         ERROR_NOT_ENOUGH_MEMORY 
  1539.     87        ERROR_INVALID_PARAMETER 
  1540.  
  1541.     or return codes of the following functions 
  1542.  
  1543.         DosOpen 
  1544.  
  1545.  
  1546. ΓòÉΓòÉΓòÉ <hidden> WtkCalcFileCRC32 - Remarks ΓòÉΓòÉΓòÉ
  1547.  
  1548. This function supports boot drive recognition. Specify ?: for the drive in 
  1549. order to read the file from the boot drive. 
  1550.  
  1551.  
  1552. ΓòÉΓòÉΓòÉ <hidden> WtkCalcFileCRC32 - Related functions ΓòÉΓòÉΓòÉ
  1553.  
  1554. Related Functions 
  1555.  
  1556. none 
  1557.  
  1558.  
  1559. ΓòÉΓòÉΓòÉ 8.7. WtkCalcMemCRC32 ΓòÉΓòÉΓòÉ
  1560.  
  1561. Select an item: 
  1562.  
  1563.      Syntax 
  1564.      Parameters 
  1565.      Returns 
  1566.      Remarks 
  1567.      Related Functions 
  1568.  
  1569.  
  1570. ΓòÉΓòÉΓòÉ <hidden> WtkCalcMemCRC32 - Syntax ΓòÉΓòÉΓòÉ
  1571.  
  1572. This function calculates a 32-bit CRC for a memory buffer. A CRC can also be 
  1573. calculated in multiple calls. 
  1574. This code has been adapted from Radim Kolars crc.c of CRC V0.1. 
  1575.  
  1576. #define INCL_WTKUTLCRC
  1577. #include <wpstk.h>
  1578.  
  1579. PVOID    pvData;      /* Address of the buffer, for which the 32-bit CRC is to be calculated.                                                */
  1580. ULONG    ulDatalen;   /* The length, in bytes, of the buffer described by pvData.                                                            */
  1581. PULONG   pulCRC32;    /* The address of a variable for the starting value for the CRC calculation and storage for the resulting 32-bit CRC.  */
  1582. APIRET   ulrc;        /* Return Code.                                                                                                        */
  1583.  
  1584. ulrc = WtkCalcMemCRC32( pvData, ulDatalen, pulCRC32);
  1585.  
  1586.  
  1587. ΓòÉΓòÉΓòÉ <hidden> WtkCalcMemCRC32 - Parameter pvData ΓòÉΓòÉΓòÉ
  1588.  
  1589. pvData (PVOID) - input 
  1590.     Address of the buffer, for which the 32-bit CRC is to be calculated. 
  1591.  
  1592.  
  1593. ΓòÉΓòÉΓòÉ <hidden> WtkCalcMemCRC32 - Parameter ulDatalen ΓòÉΓòÉΓòÉ
  1594.  
  1595. ulDatalen (ULONG) - input 
  1596.     The length, in bytes, of the buffer described by pvData. 
  1597.  
  1598.  
  1599. ΓòÉΓòÉΓòÉ <hidden> WtkCalcMemCRC32 - Parameter pulCRC32 ΓòÉΓòÉΓòÉ
  1600.  
  1601. pulCRC32 (PULONG) - input/output 
  1602.     The address of a variable for the starting value for the CRC calculation 
  1603.     and storage for the resulting 32-bit CRC. 
  1604.  
  1605.     Input     starting value for CRC calculation. On a first call, set this 
  1606.               value to -1. On consecutive calls, leave the value as returned by 
  1607.               the previous call to WtkCalcMemCRC32. 
  1608.  
  1609.     Output    resulting CRC value 
  1610.  
  1611.  
  1612. ΓòÉΓòÉΓòÉ <hidden> WtkCalcMemCRC32 - Parameters ΓòÉΓòÉΓòÉ
  1613.  
  1614. pvData (PVOID) - input 
  1615.     Address of the buffer, for which the 32-bit CRC is to be calculated. 
  1616.  
  1617.  ulDatalen (ULONG) - input 
  1618.     The length, in bytes, of the buffer described by pvData. 
  1619.  
  1620.  pulCRC32 (PULONG) - input/output 
  1621.     The address of a variable for the starting value for the CRC calculation 
  1622.     and storage for the resulting 32-bit CRC. 
  1623.  
  1624.     Input     starting value for CRC calculation. On a first call, set this 
  1625.               value to -1. On consecutive calls, leave the value as returned by 
  1626.               the previous call to WtkCalcMemCRC32. 
  1627.  
  1628.     Output    resulting CRC value 
  1629.  
  1630.  ulrc (APIRET) - returns 
  1631.     Return Code. 
  1632.  
  1633.     WtkCalcMemCRC32 returns one of the following return codes: 
  1634.  
  1635.     0         NO_ERROR 
  1636.     87        ERROR_INVALID_PARAMETER 
  1637.     111       ERROR_BUFFER_OVERFLOW 
  1638.     123       ERROR_INVALID_NAME 
  1639.  
  1640.     or return codes of the following functions 
  1641.  
  1642.         DosOpen 
  1643.  
  1644.  
  1645. ΓòÉΓòÉΓòÉ <hidden> WtkCalcMemCRC32 Return Value - ulrc ΓòÉΓòÉΓòÉ
  1646.  
  1647. ulrc (APIRET) - returns 
  1648.     Return Code. 
  1649.  
  1650.     WtkCalcMemCRC32 returns one of the following return codes: 
  1651.  
  1652.     0         NO_ERROR 
  1653.     87        ERROR_INVALID_PARAMETER 
  1654.     111       ERROR_BUFFER_OVERFLOW 
  1655.     123       ERROR_INVALID_NAME 
  1656.  
  1657.     or return codes of the following functions 
  1658.  
  1659.         DosOpen 
  1660.  
  1661.  
  1662. ΓòÉΓòÉΓòÉ <hidden> WtkCalcMemCRC32 - Remarks ΓòÉΓòÉΓòÉ
  1663.  
  1664. When WtkCalcMemCRC32 is called to calculate a 32-bit CRC for one memory buffer, 
  1665. the variable pointed to by pulCRC32 has to be set to -1. 
  1666.  
  1667. If the CRC is to be calculated for multiple memory buffers by calling 
  1668. WtkCalcMemCRC32 several times, the variable pointed to by pulCRC32 has to be 
  1669. set to -1 for the first call only. On consecutive calls, leave the value as 
  1670. returned by the previous call to WtkCalcMemCRC32. 
  1671.  
  1672.  
  1673. ΓòÉΓòÉΓòÉ <hidden> WtkCalcMemCRC32 - Related functions ΓòÉΓòÉΓòÉ
  1674.  
  1675. Related Functions 
  1676.  
  1677. none 
  1678.  
  1679.  
  1680. ΓòÉΓòÉΓòÉ 8.8. WtkCloseClassSettingsTable ΓòÉΓòÉΓòÉ
  1681.  
  1682. Select an item: 
  1683.  
  1684.      Syntax 
  1685.      Parameters 
  1686.      Returns 
  1687.      Remarks 
  1688.      Related Functions 
  1689.  
  1690.  
  1691. ΓòÉΓòÉΓòÉ <hidden> WtkCloseClassSettingsTable - Syntax ΓòÉΓòÉΓòÉ
  1692.  
  1693. This function closes the class settingstable, so that objects (instances) of 
  1694. the WPS class can use it. 
  1695.  
  1696. #define INCL_WTKSETTINGS
  1697. #include <wpstk.h>
  1698.  
  1699. HSETTINGTABLE   hst;       /* Settingstable handle.  */
  1700. BOOL            fResult;   /* Success indicator.     */
  1701.  
  1702. fResult = WtkCloseClassSettingsTable( hst);
  1703.  
  1704.  
  1705. ΓòÉΓòÉΓòÉ <hidden> WtkCloseClassSettingsTable - Parameter hst ΓòÉΓòÉΓòÉ
  1706.  
  1707. hst (HSETTINGTABLE) - input 
  1708.     Settingstable handle. 
  1709.  
  1710.  
  1711. ΓòÉΓòÉΓòÉ <hidden> WtkCloseClassSettingsTable - Parameters ΓòÉΓòÉΓòÉ
  1712.  
  1713. hst (HSETTINGTABLE) - input 
  1714.     Settingstable handle. 
  1715.  
  1716.  fResult (BOOL) - returns 
  1717.     Success indicator. 
  1718.  
  1719.     TRUE 
  1720.               Class settingstable was closed successfully. 
  1721.     FALSE 
  1722.               An error occurred. 
  1723.  
  1724.  
  1725. ΓòÉΓòÉΓòÉ <hidden> WtkCloseClassSettingsTable Return Value - fResult ΓòÉΓòÉΓòÉ
  1726.  
  1727. fResult (BOOL) - returns 
  1728.     Success indicator. 
  1729.  
  1730.     TRUE 
  1731.               Class settingstable was closed successfully. 
  1732.     FALSE 
  1733.               An error occurred. 
  1734.  
  1735.  
  1736. ΓòÉΓòÉΓòÉ <hidden> WtkCloseClassSettingsTable - Remarks ΓòÉΓòÉΓòÉ
  1737.  
  1738. This function is to be called during _wpclsInitData, right after having created 
  1739. the class settingstable with WtkCreateClassSettingsTable and added all settings 
  1740. and details with 
  1741.  
  1742.      WtkAddClassSetting 
  1743.      WtkAddClassDetail 
  1744.  
  1745.  If the WPS class does not close the settingstable using 
  1746.  WtkCloseClassSettingsTable, it cannot be used by objects (instances() of the 
  1747.  WPS class. 
  1748.  
  1749.  
  1750. ΓòÉΓòÉΓòÉ <hidden> WtkCloseClassSettingsTable - Related functions ΓòÉΓòÉΓòÉ
  1751.  
  1752. Related Functions 
  1753.  
  1754. none 
  1755.  
  1756.  
  1757. ΓòÉΓòÉΓòÉ 8.9. WtkCloseEa ΓòÉΓòÉΓòÉ
  1758.  
  1759. Select an item: 
  1760.  
  1761.      Syntax 
  1762.      Parameters 
  1763.      Returns 
  1764.      Remarks 
  1765.      Related Functions 
  1766.  
  1767.  
  1768. ΓòÉΓòÉΓòÉ <hidden> WtkCloseEa - Syntax ΓòÉΓòÉΓòÉ
  1769.  
  1770. This function releases the reosurces for handling an extended attribute. 
  1771.  
  1772. #define INCL_WTKEAS
  1773. #include <wpstk.h>
  1774.  
  1775. HEA      hea;    /* Handle to the extended attribute.  */
  1776. APIRET   ulrc;   /* Return Code.                       */
  1777.  
  1778. ulrc = WtkCloseEa( hea);
  1779.  
  1780.  
  1781. ΓòÉΓòÉΓòÉ <hidden> WtkCloseEa - Parameter hea ΓòÉΓòÉΓòÉ
  1782.  
  1783. hea (HEA) - input 
  1784.     Handle to the extended attribute. 
  1785.  
  1786.  
  1787. ΓòÉΓòÉΓòÉ <hidden> WtkCloseEa - Parameters ΓòÉΓòÉΓòÉ
  1788.  
  1789. hea (HEA) - input 
  1790.     Handle to the extended attribute. 
  1791.  
  1792.  ulrc (APIRET) - returns 
  1793.     Return Code. 
  1794.  
  1795.     WtkCloseEa returns one of the following return codes: 
  1796.  
  1797.     0         NO_ERROR 
  1798.     6         ERROR_INVALID_HANDLE 
  1799.  
  1800.  
  1801. ΓòÉΓòÉΓòÉ <hidden> WtkCloseEa Return Value - ulrc ΓòÉΓòÉΓòÉ
  1802.  
  1803. ulrc (APIRET) - returns 
  1804.     Return Code. 
  1805.  
  1806.     WtkCloseEa returns one of the following return codes: 
  1807.  
  1808.     0         NO_ERROR 
  1809.     6         ERROR_INVALID_HANDLE 
  1810.  
  1811.  
  1812. ΓòÉΓòÉΓòÉ <hidden> WtkCloseEa - Remarks ΓòÉΓòÉΓòÉ
  1813.  
  1814. This function does not write the extended attribute to disk. Use WtkSaveEa 
  1815. before to write changes to disk, if necessary. 
  1816.  
  1817.  
  1818. ΓòÉΓòÉΓòÉ <hidden> WtkCloseEa - Related functions ΓòÉΓòÉΓòÉ
  1819.  
  1820. Related Functions 
  1821.  
  1822. none 
  1823.  
  1824.  
  1825. ΓòÉΓòÉΓòÉ 8.10. WtkCreateClassSettingsTable ΓòÉΓòÉΓòÉ
  1826.  
  1827. Select an item: 
  1828.  
  1829.      Syntax 
  1830.      Parameters 
  1831.      Returns 
  1832.      Remarks 
  1833.      Related Functions 
  1834.  
  1835.  
  1836. ΓòÉΓòÉΓòÉ <hidden> WtkCreateClassSettingsTable - Syntax ΓòÉΓòÉΓòÉ
  1837.  
  1838. This function creates a settings table for a meta class. 
  1839.  
  1840. #define INCL_WTKSETTINGS
  1841. #include <wpstk.h>
  1842.  
  1843. PVOID           pvObjectClass;      /* somSelf of the meta class.         */
  1844. PFNCB           pfnCallbackValue;   /* Adress of the callback procedure.  */
  1845. HSETTINGTABLE   hsettingtable;      /* Settingstable handle.              */
  1846.  
  1847. hsettingtable = WtkCreateClassSettingsTable( pvObjectClass, pfnCallbackValue);
  1848.  
  1849.  
  1850. ΓòÉΓòÉΓòÉ <hidden> WtkCreateClassSettingsTable - Parameter pvObjectClass ΓòÉΓòÉΓòÉ
  1851.  
  1852. pvObjectClass (PVOID) - input 
  1853.     somSelf of the meta class. 
  1854.  
  1855.  
  1856. ΓòÉΓòÉΓòÉ <hidden> WtkCreateClassSettingsTable - Parameter pfnCallbackValue ΓòÉΓòÉΓòÉ
  1857.  
  1858. pfnCallbackValue (PFNCB) - input 
  1859.     Adress of the callback procedure. 
  1860.  
  1861.  
  1862. ΓòÉΓòÉΓòÉ <hidden> WtkCreateClassSettingsTable - Parameters ΓòÉΓòÉΓòÉ
  1863.  
  1864. pvObjectClass (PVOID) - input 
  1865.     somSelf of the meta class. 
  1866.  
  1867.  pfnCallbackValue (PFNCB) - input 
  1868.     Adress of the callback procedure. 
  1869.  
  1870.  hsettingtable (HSETTINGTABLE) - returns 
  1871.     Settingstable handle. 
  1872.  
  1873.     NULLHANDLE 
  1874.               Settingstable could not be created. 
  1875.     other 
  1876.               handle to the new settingstable 
  1877.  
  1878.  
  1879. ΓòÉΓòÉΓòÉ <hidden> WtkCreateClassSettingsTable Return Value - hsettingtable ΓòÉΓòÉΓòÉ
  1880.  
  1881. hsettingtable (HSETTINGTABLE) - returns 
  1882.     Settingstable handle. 
  1883.  
  1884.     NULLHANDLE 
  1885.               Settingstable could not be created. 
  1886.     other 
  1887.               handle to the new settingstable 
  1888.  
  1889.  
  1890. ΓòÉΓòÉΓòÉ <hidden> WtkCreateClassSettingsTable - Remarks ΓòÉΓòÉΓòÉ
  1891.  
  1892. This function is to be called during _wpsclsInitData. 
  1893.  
  1894. After having created the settingstable, still within _wpsclsInitData settings 
  1895. and details are to be added to the table by invoking 
  1896.  
  1897.      WtkAddClassSetting 
  1898.      WtkAddClassDetail 
  1899.  
  1900.  and the table is to be closed for usage by instances of the WPS class by 
  1901.  calling 
  1902.  
  1903.      WtkCloseClassSettingsTable 
  1904.  
  1905.  
  1906. ΓòÉΓòÉΓòÉ <hidden> WtkCreateClassSettingsTable - Related functions ΓòÉΓòÉΓòÉ
  1907.  
  1908. Related Functions 
  1909.  
  1910. none 
  1911.  
  1912.  
  1913. ΓòÉΓòÉΓòÉ 8.11. WtkCreateEa ΓòÉΓòÉΓòÉ
  1914.  
  1915. Select an item: 
  1916.  
  1917.      Syntax 
  1918.      Parameters 
  1919.      Returns 
  1920.      Remarks 
  1921.      Related Functions 
  1922.  
  1923.  
  1924. ΓòÉΓòÉΓòÉ <hidden> WtkCreateEa - Syntax ΓòÉΓòÉΓòÉ
  1925.  
  1926. This function creates an extended attribute with no values in memory. 
  1927.  
  1928. #define INCL_WTKEAS
  1929. #include <wpstk.h>
  1930.  
  1931. PSZ      pszName;     /* Address of the ASCIIZ path name of the file or directory, that the extended attribute shall belong to.  */
  1932. PSZ      pszEaName;   /* Address of the ASCIIZ name of the extended attribute.                                                   */
  1933. PHEA     phea;        /* The address of a variable containing the handle to the extended attribute                               */
  1934. APIRET   ulrc;        /* Return Code.                                                                                            */
  1935.  
  1936. ulrc = WtkCreateEa( pszName, pszEaName, phea);
  1937.  
  1938.  
  1939. ΓòÉΓòÉΓòÉ <hidden> WtkCreateEa - Parameter pszName ΓòÉΓòÉΓòÉ
  1940.  
  1941. pszName (PSZ) - input 
  1942.     Address of the ASCIIZ path name of the file or directory, that the extended 
  1943.     attribute shall belong to. 
  1944.  
  1945.     The path name may contain ?: for the drive in order to open the file or 
  1946.     directory on the boot drive. 
  1947.  
  1948.     The name may not include wildcards. 
  1949.  
  1950.  
  1951. ΓòÉΓòÉΓòÉ <hidden> WtkCreateEa - Parameter pszEaName ΓòÉΓòÉΓòÉ
  1952.  
  1953. pszEaName (PSZ) - input 
  1954.     Address of the ASCIIZ name of the extended attribute. 
  1955.  
  1956.  
  1957. ΓòÉΓòÉΓòÉ <hidden> WtkCreateEa - Parameter phea ΓòÉΓòÉΓòÉ
  1958.  
  1959. phea (PHEA) - output 
  1960.     The address of a variable containing the handle to the extended attribute 
  1961.  
  1962.  
  1963. ΓòÉΓòÉΓòÉ <hidden> WtkCreateEa - Parameters ΓòÉΓòÉΓòÉ
  1964.  
  1965. pszName (PSZ) - input 
  1966.     Address of the ASCIIZ path name of the file or directory, that the extended 
  1967.     attribute shall belong to. 
  1968.  
  1969.     The path name may contain ?: for the drive in order to open the file or 
  1970.     directory on the boot drive. 
  1971.  
  1972.     The name may not include wildcards. 
  1973.  
  1974.  pszEaName (PSZ) - input 
  1975.     Address of the ASCIIZ name of the extended attribute. 
  1976.  
  1977.  phea (PHEA) - output 
  1978.     The address of a variable containing the handle to the extended attribute 
  1979.  
  1980.  ulrc (APIRET) - returns 
  1981.     Return Code. 
  1982.  
  1983.     WtkCreateEa returns one of the following return codes: 
  1984.  
  1985.     0         NO_ERROR 
  1986.     8         ERROR_NOT_ENOUGH_MEMORY 
  1987.     87        ERROR_INVALID_PARAMETER 
  1988.  
  1989.  
  1990. ΓòÉΓòÉΓòÉ <hidden> WtkCreateEa Return Value - ulrc ΓòÉΓòÉΓòÉ
  1991.  
  1992. ulrc (APIRET) - returns 
  1993.     Return Code. 
  1994.  
  1995.     WtkCreateEa returns one of the following return codes: 
  1996.  
  1997.     0         NO_ERROR 
  1998.     8         ERROR_NOT_ENOUGH_MEMORY 
  1999.     87        ERROR_INVALID_PARAMETER 
  2000.  
  2001.  
  2002. ΓòÉΓòÉΓòÉ <hidden> WtkCreateEa - Remarks ΓòÉΓòÉΓòÉ
  2003.  
  2004. This function allocates resources for handling the value of the given extended 
  2005. attribute, which must be freeed by calling WtkCloseEa, when not longer needed. 
  2006.  
  2007. This function supports boot drive recognition. Specify ?: for the drive in 
  2008. order to open the file or directory on the boot drive. 
  2009.  
  2010.  
  2011. ΓòÉΓòÉΓòÉ <hidden> WtkCreateEa - Related functions ΓòÉΓòÉΓòÉ
  2012.  
  2013. Related Functions 
  2014.  
  2015. none 
  2016.  
  2017.  
  2018. ΓòÉΓòÉΓòÉ 8.12. WtkCreateObjectValueTable ΓòÉΓòÉΓòÉ
  2019.  
  2020. Select an item: 
  2021.  
  2022.      Syntax 
  2023.      Parameters 
  2024.      Returns 
  2025.      Remarks 
  2026.      Related Functions 
  2027.  
  2028.  
  2029. ΓòÉΓòÉΓòÉ <hidden> WtkCreateObjectValueTable - Syntax ΓòÉΓòÉΓòÉ
  2030.  
  2031. This function creates a valuetable for an object (instance) of a WPS class. 
  2032.  
  2033. #define INCL_WTKSETTINGS
  2034. #include <wpstk.h>
  2035.  
  2036. HSETTINGTABLE   hst;                /* Settingstable handle.   */
  2037. PVOID           pvObjectInstance;   /* somSelf of the object.  */
  2038. PVOID           pvObjectData;       /* somThis of the object.  */
  2039. HVALUETABLE     hvaluetable;        /* Valuetable handle.      */
  2040.  
  2041. hvaluetable = WtkCreateObjectValueTable( hst, pvObjectInstance, pvObjectData);
  2042.  
  2043.  
  2044. ΓòÉΓòÉΓòÉ <hidden> WtkCreateObjectValueTable - Parameter hst ΓòÉΓòÉΓòÉ
  2045.  
  2046. hst (HSETTINGTABLE) - input 
  2047.     Settingstable handle. 
  2048.  
  2049.     Note:  The settingstable being specified must have been closed before by 
  2050.     calling WtkCloseClassSettingsTable. 
  2051.  
  2052.  
  2053. ΓòÉΓòÉΓòÉ <hidden> WtkCreateObjectValueTable - Parameter pvObjectInstance ΓòÉΓòÉΓòÉ
  2054.  
  2055. pvObjectInstance (PVOID) - input 
  2056.     somSelf of the object. 
  2057.  
  2058.  
  2059. ΓòÉΓòÉΓòÉ <hidden> WtkCreateObjectValueTable - Parameter pvObjectData ΓòÉΓòÉΓòÉ
  2060.  
  2061. pvObjectData (PVOID) - input 
  2062.     somThis of the object. 
  2063.  
  2064.  
  2065. ΓòÉΓòÉΓòÉ <hidden> WtkCreateObjectValueTable - Parameters ΓòÉΓòÉΓòÉ
  2066.  
  2067. hst (HSETTINGTABLE) - input 
  2068.     Settingstable handle. 
  2069.  
  2070.     Note:  The settingstable being specified must have been closed before by 
  2071.     calling WtkCloseClassSettingsTable. 
  2072.  
  2073.  pvObjectInstance (PVOID) - input 
  2074.     somSelf of the object. 
  2075.  
  2076.  pvObjectData (PVOID) - input 
  2077.     somThis of the object. 
  2078.  
  2079.  hvaluetable (HVALUETABLE) - returns 
  2080.     Valuetable handle. 
  2081.  
  2082.     NULLHANDLE 
  2083.               Valuetable could not be created. 
  2084.     other 
  2085.               handle to the new settingstable 
  2086.  
  2087.  
  2088. ΓòÉΓòÉΓòÉ <hidden> WtkCreateObjectValueTable Return Value - hvaluetable ΓòÉΓòÉΓòÉ
  2089.  
  2090. hvaluetable (HVALUETABLE) - returns 
  2091.     Valuetable handle. 
  2092.  
  2093.     NULLHANDLE 
  2094.               Valuetable could not be created. 
  2095.     other 
  2096.               handle to the new settingstable 
  2097.  
  2098.  
  2099. ΓòÉΓòÉΓòÉ <hidden> WtkCreateObjectValueTable - Remarks ΓòÉΓòÉΓòÉ
  2100.  
  2101. This function is to be called during _wpInitData. This way it creates a table 
  2102. for settingsvalues for each object (instance) of the WPS class. 
  2103.  
  2104.  
  2105. ΓòÉΓòÉΓòÉ <hidden> WtkCreateObjectValueTable - Related functions ΓòÉΓòÉΓòÉ
  2106.  
  2107. Related Functions 
  2108.  
  2109. none 
  2110.  
  2111.  
  2112. ΓòÉΓòÉΓòÉ 8.13. WtkCreatePath ΓòÉΓòÉΓòÉ
  2113.  
  2114. Select an item: 
  2115.  
  2116.      Syntax 
  2117.      Parameters 
  2118.      Returns 
  2119.      Remarks 
  2120.      Related Functions 
  2121.  
  2122.  
  2123. ΓòÉΓòÉΓòÉ <hidden> WtkCreatePath - Syntax ΓòÉΓòÉΓòÉ
  2124.  
  2125. This function creates a complete path. An error is returned only, if the last 
  2126. subdirectory in the pathname could not be created. 
  2127.  
  2128. #define INCL_WTKUTLFILE
  2129. #include <wpstk.h>
  2130.  
  2131. PSZ      pszPath;   /* Address of the ASCIIZ path name of the path to be created.  */
  2132. APIRET   ulrc;      /* Return Code.                                                */
  2133.  
  2134. ulrc = WtkCreatePath( pszPath);
  2135.  
  2136.  
  2137. ΓòÉΓòÉΓòÉ <hidden> WtkCreatePath - Parameter pszPath ΓòÉΓòÉΓòÉ
  2138.  
  2139. pszPath (PSZ) - input 
  2140.     Address of the ASCIIZ path name of the path to be created. 
  2141.  
  2142.     The path name may contain ?: for the drive in order to create the path on 
  2143.     the boot drive. 
  2144.  
  2145.  
  2146. ΓòÉΓòÉΓòÉ <hidden> WtkCreatePath - Parameters ΓòÉΓòÉΓòÉ
  2147.  
  2148. pszPath (PSZ) - input 
  2149.     Address of the ASCIIZ path name of the path to be created. 
  2150.  
  2151.     The path name may contain ?: for the drive in order to create the path on 
  2152.     the boot drive. 
  2153.  
  2154.  ulrc (APIRET) - returns 
  2155.     Return Code. 
  2156.  
  2157.     WtkCreatePath returns one of the following return codes: 
  2158.  
  2159.     0         NO_ERROR 
  2160.     87        ERROR_INVALID_PARAMETER 
  2161.  
  2162.     or return codes of the following functions 
  2163.  
  2164.         DosCreateDir 
  2165.  
  2166.  
  2167. ΓòÉΓòÉΓòÉ <hidden> WtkCreatePath Return Value - ulrc ΓòÉΓòÉΓòÉ
  2168.  
  2169. ulrc (APIRET) - returns 
  2170.     Return Code. 
  2171.  
  2172.     WtkCreatePath returns one of the following return codes: 
  2173.  
  2174.     0         NO_ERROR 
  2175.     87        ERROR_INVALID_PARAMETER 
  2176.  
  2177.     or return codes of the following functions 
  2178.  
  2179.         DosCreateDir 
  2180.  
  2181.  
  2182. ΓòÉΓòÉΓòÉ <hidden> WtkCreatePath - Remarks ΓòÉΓòÉΓòÉ
  2183.  
  2184. WtkCreatePath tries to create all directories within the path. An error is 
  2185. returned only, if the last subdirectory in the pathname could not be created. 
  2186.  
  2187. This function supports boot drive recognition. Specify ?: for the drive in 
  2188. order to create the path on the boot drive. 
  2189.  
  2190.  
  2191. ΓòÉΓòÉΓòÉ <hidden> WtkCreatePath - Related functions ΓòÉΓòÉΓòÉ
  2192.  
  2193. Related Functions 
  2194.  
  2195. none 
  2196.  
  2197.  
  2198. ΓòÉΓòÉΓòÉ 8.14. WtkCreateTmpFile ΓòÉΓòÉΓòÉ
  2199.  
  2200. Select an item: 
  2201.  
  2202.      Syntax 
  2203.      Parameters 
  2204.      Returns 
  2205.      Remarks 
  2206.      Related Functions 
  2207.  
  2208.  
  2209. ΓòÉΓòÉΓòÉ <hidden> WtkCreateTmpFile - Syntax ΓòÉΓòÉΓòÉ
  2210.  
  2211. This function creates a temporary file of zero byte size with a generic name. 
  2212. Specify a filemask without drive and path in order to create the file in the 
  2213. %TMP% directory. 
  2214.  
  2215. #define INCL_WTKUTLFILE
  2216. #include <wpstk.h>
  2217.  
  2218. PSZ      pszFileMask;   /* Address of the ASCIIZ filemask, which is to be used to create a temporary file.                     */
  2219. PSZ      pszBuffer;     /* The address of a buffer, into which the full name of the newly created temporary file is returned.  */
  2220. ULONG    ulBuflen;      /* The length, in bytes, of the buffer described by pszBuffer.                                         */
  2221. APIRET   ulrc;          /* Return Code.                                                                                        */
  2222.  
  2223. ulrc = WtkCreateTmpFile( pszFileMask, pszBuffer, ulBuflen);
  2224.  
  2225.  
  2226. ΓòÉΓòÉΓòÉ <hidden> WtkCreateTmpFile - Parameter pszFileMask ΓòÉΓòÉΓòÉ
  2227.  
  2228. pszFileMask (PSZ) - input 
  2229.     Address of the ASCIIZ filemask, which is to be used to create a temporary 
  2230.     file. 
  2231.  
  2232.     The filename must contain one or more ?, which are being replaced by random 
  2233.     digits. 
  2234.  
  2235.     If the file mask specified with pszFileMask does neither contain a drive or 
  2236.     a path specification, the temporary file is being created in the %TMP% 
  2237.     directory. In order to create a temporary file in the current directory, 
  2238.     you may specify a ".\" as the path component. 
  2239.  
  2240.     The path name may contain ?: for the drive in order to create the temporary 
  2241.     file on the boot drive. 
  2242.  
  2243.  
  2244. ΓòÉΓòÉΓòÉ <hidden> WtkCreateTmpFile - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  2245.  
  2246. pszBuffer (PSZ) - output 
  2247.     The address of a buffer, into which the full name of the newly created 
  2248.     temporary file is returned. 
  2249.  
  2250.  
  2251. ΓòÉΓòÉΓòÉ <hidden> WtkCreateTmpFile - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  2252.  
  2253. ulBuflen (ULONG) - input 
  2254.     The length, in bytes, of the buffer described by pszBuffer. 
  2255.  
  2256.  
  2257. ΓòÉΓòÉΓòÉ <hidden> WtkCreateTmpFile - Parameters ΓòÉΓòÉΓòÉ
  2258.  
  2259. pszFileMask (PSZ) - input 
  2260.     Address of the ASCIIZ filemask, which is to be used to create a temporary 
  2261.     file. 
  2262.  
  2263.     The filename must contain one or more ?, which are being replaced by random 
  2264.     digits. 
  2265.  
  2266.     If the file mask specified with pszFileMask does neither contain a drive or 
  2267.     a path specification, the temporary file is being created in the %TMP% 
  2268.     directory. In order to create a temporary file in the current directory, 
  2269.     you may specify a ".\" as the path component. 
  2270.  
  2271.     The path name may contain ?: for the drive in order to create the temporary 
  2272.     file on the boot drive. 
  2273.  
  2274.  pszBuffer (PSZ) - output 
  2275.     The address of a buffer, into which the full name of the newly created 
  2276.     temporary file is returned. 
  2277.  
  2278.  ulBuflen (ULONG) - input 
  2279.     The length, in bytes, of the buffer described by pszBuffer. 
  2280.  
  2281.  ulrc (APIRET) - returns 
  2282.     Return Code. 
  2283.  
  2284.     WtkCreateTmpFile returns one of the following return codes: 
  2285.  
  2286.     0         NO_ERROR 
  2287.     87        ERROR_INVALID_PARAMETER 
  2288.     111       ERROR_BUFFER_OVERFLOW 
  2289.     123       ERROR_INVALID_NAME 
  2290.  
  2291.     or return codes of the following functions 
  2292.  
  2293.         DosOpen 
  2294.  
  2295.  
  2296. ΓòÉΓòÉΓòÉ <hidden> WtkCreateTmpFile Return Value - ulrc ΓòÉΓòÉΓòÉ
  2297.  
  2298. ulrc (APIRET) - returns 
  2299.     Return Code. 
  2300.  
  2301.     WtkCreateTmpFile returns one of the following return codes: 
  2302.  
  2303.     0         NO_ERROR 
  2304.     87        ERROR_INVALID_PARAMETER 
  2305.     111       ERROR_BUFFER_OVERFLOW 
  2306.     123       ERROR_INVALID_NAME 
  2307.  
  2308.     or return codes of the following functions 
  2309.  
  2310.         DosOpen 
  2311.  
  2312.  
  2313. ΓòÉΓòÉΓòÉ <hidden> WtkCreateTmpFile - Remarks ΓòÉΓòÉΓòÉ
  2314.  
  2315. If the file mask specified with pszFileMask does neither contain a drive or a 
  2316. path specification, the temporary file is being created in the %TMP% directory. 
  2317. In order to create a temporary file in the current directory, you may specify a 
  2318. ".\" as the path component. 
  2319.  
  2320. This function supports boot drive recognition. Specify ?: for the drive in 
  2321. order to create the temporary file on the boot drive. 
  2322.  
  2323.  
  2324. ΓòÉΓòÉΓòÉ <hidden> WtkCreateTmpFile - Related functions ΓòÉΓòÉΓòÉ
  2325.  
  2326. Related Functions 
  2327.  
  2328. none 
  2329.  
  2330.  
  2331. ΓòÉΓòÉΓòÉ 8.15. WtkDateTimeToTime ΓòÉΓòÉΓòÉ
  2332.  
  2333. Select an item: 
  2334.  
  2335.      Syntax 
  2336.      Parameters 
  2337.      Returns 
  2338.      Remarks 
  2339.      Related Functions 
  2340.  
  2341.  
  2342. ΓòÉΓòÉΓòÉ <hidden> WtkDateTimeToTime - Syntax ΓòÉΓòÉΓòÉ
  2343.  
  2344. This function converts the contents of a DATETIME stucture to a time value used 
  2345. by the compiler runtime. 
  2346.  
  2347. #define INCL_WTKUTLTIME
  2348. #include <wpstk.h>
  2349.  
  2350. PDATETIME   pdt;       /* Address of the DATETIME structure.    */
  2351. time_t     *ptime;     /* Address of the resulting time value.  */
  2352. BOOL        fResult;   /* Success indicator.                    */
  2353.  
  2354. fResult = WtkDateTimeToTime( pdt, ptime);
  2355.  
  2356.  
  2357. ΓòÉΓòÉΓòÉ <hidden> WtkDateTimeToTime - Parameter pdt ΓòÉΓòÉΓòÉ
  2358.  
  2359. pdt (PDATETIME) - input 
  2360.     Address of the DATETIME structure. 
  2361.  
  2362.  
  2363. ΓòÉΓòÉΓòÉ <hidden> WtkDateTimeToTime - Parameter ptime ΓòÉΓòÉΓòÉ
  2364.  
  2365. ptime (time_t*) - output 
  2366.     Address of the resulting time value. 
  2367.  
  2368.  
  2369. ΓòÉΓòÉΓòÉ <hidden> WtkDateTimeToTime - Parameters ΓòÉΓòÉΓòÉ
  2370.  
  2371. pdt (PDATETIME) - input 
  2372.     Address of the DATETIME structure. 
  2373.  
  2374.  ptime (time_t*) - output 
  2375.     Address of the resulting time value. 
  2376.  
  2377.  fResult (BOOL) - returns 
  2378.     Success indicator. 
  2379.  
  2380.     TRUE 
  2381.               Conversion successful. 
  2382.     FALSE 
  2383.               Conversion not successful or invalid parameters. 
  2384.  
  2385.  
  2386. ΓòÉΓòÉΓòÉ <hidden> WtkDateTimeToTime Return Value - fResult ΓòÉΓòÉΓòÉ
  2387.  
  2388. fResult (BOOL) - returns 
  2389.     Success indicator. 
  2390.  
  2391.     TRUE 
  2392.               Conversion successful. 
  2393.     FALSE 
  2394.               Conversion not successful or invalid parameters. 
  2395.  
  2396.  
  2397. ΓòÉΓòÉΓòÉ <hidden> WtkDateTimeToTime - Remarks ΓòÉΓòÉΓòÉ
  2398.  
  2399. This function does not check any of the values of the DATETIME structure before 
  2400. converting. 
  2401.  
  2402.  
  2403. ΓòÉΓòÉΓòÉ <hidden> WtkDateTimeToTime - Related functions ΓòÉΓòÉΓòÉ
  2404.  
  2405. Related Functions 
  2406.  
  2407. none 
  2408.  
  2409.  
  2410. ΓòÉΓòÉΓòÉ 8.16. WtkDeletePath ΓòÉΓòÉΓòÉ
  2411.  
  2412. Select an item: 
  2413.  
  2414.      Syntax 
  2415.      Parameters 
  2416.      Returns 
  2417.      Remarks 
  2418.      Related Functions 
  2419.  
  2420.  
  2421. ΓòÉΓòÉΓòÉ <hidden> WtkDeletePath - Syntax ΓòÉΓòÉΓòÉ
  2422.  
  2423. This function deletes a complete path. An error is returned only, if the last 
  2424. subdirectory in the pathname could not be deleted. 
  2425.  
  2426. #define INCL_WTKUTLFILE
  2427. #include <wpstk.h>
  2428.  
  2429. PSZ      pszPath;   /* Address of the ASCIIZ path name of the path to be deleted.  */
  2430. APIRET   ulrc;      /* Return Code.                                                */
  2431.  
  2432. ulrc = WtkDeletePath( pszPath);
  2433.  
  2434.  
  2435. ΓòÉΓòÉΓòÉ <hidden> WtkDeletePath - Parameter pszPath ΓòÉΓòÉΓòÉ
  2436.  
  2437. pszPath (PSZ) - input 
  2438.     Address of the ASCIIZ path name of the path to be deleted. 
  2439.  
  2440.     The path name may contain ?: for the drive in order to delete the path on 
  2441.     the boot drive. 
  2442.  
  2443.  
  2444. ΓòÉΓòÉΓòÉ <hidden> WtkDeletePath - Parameters ΓòÉΓòÉΓòÉ
  2445.  
  2446. pszPath (PSZ) - input 
  2447.     Address of the ASCIIZ path name of the path to be deleted. 
  2448.  
  2449.     The path name may contain ?: for the drive in order to delete the path on 
  2450.     the boot drive. 
  2451.  
  2452.  ulrc (APIRET) - returns 
  2453.     Return Code. 
  2454.  
  2455.     WtkDeletePath returns one of the following return codes: 
  2456.  
  2457.     0         NO_ERROR 
  2458.     87        ERROR_INVALID_PARAMETER 
  2459.  
  2460.     or return codes of the following functions 
  2461.  
  2462.         DosDeleteDir 
  2463.  
  2464.  
  2465. ΓòÉΓòÉΓòÉ <hidden> WtkDeletePath Return Value - ulrc ΓòÉΓòÉΓòÉ
  2466.  
  2467. ulrc (APIRET) - returns 
  2468.     Return Code. 
  2469.  
  2470.     WtkDeletePath returns one of the following return codes: 
  2471.  
  2472.     0         NO_ERROR 
  2473.     87        ERROR_INVALID_PARAMETER 
  2474.  
  2475.     or return codes of the following functions 
  2476.  
  2477.         DosDeleteDir 
  2478.  
  2479.  
  2480. ΓòÉΓòÉΓòÉ <hidden> WtkDeletePath - Remarks ΓòÉΓòÉΓòÉ
  2481.  
  2482. WtkDeletePath tries to delete all directories within the path. An error is 
  2483. returned only, if the last subdirectory in the pathname could not be deleted. 
  2484.  
  2485. This function supports boot drive recognition. Specify ?: for the drive in 
  2486. order to delete the file on the boot drive. 
  2487.  
  2488.  
  2489. ΓòÉΓòÉΓòÉ <hidden> WtkDeletePath - Related functions ΓòÉΓòÉΓòÉ
  2490.  
  2491. Related Functions 
  2492.  
  2493. none 
  2494.  
  2495.  
  2496. ΓòÉΓòÉΓòÉ 8.17. WtkDeregisterSettingsDialog ΓòÉΓòÉΓòÉ
  2497.  
  2498. Select an item: 
  2499.  
  2500.      Syntax 
  2501.      Parameters 
  2502.      Returns 
  2503.      Remarks 
  2504.      Related Functions 
  2505.  
  2506.  
  2507. ΓòÉΓòÉΓòÉ <hidden> WtkDeregisterSettingsDialog - Syntax ΓòÉΓòÉΓòÉ
  2508.  
  2509. This function dereqisters a dialog of a settings notebookpage. 
  2510.  
  2511. #define INCL_WTKSETTINGS
  2512. #include <wpstk.h>
  2513.  
  2514. HVALUETABLE   hvt;          /* Valuetable handle.                            */
  2515. HWND          hwndDialog;   /* Dialog handle of the settings notebook page.  */
  2516. BOOL          fResult;      /* Success indicator.                            */
  2517.  
  2518. fResult = WtkDeregisterSettingsDialog( hvt, hwndDialog);
  2519.  
  2520.  
  2521. ΓòÉΓòÉΓòÉ <hidden> WtkDeregisterSettingsDialog - Parameter hvt ΓòÉΓòÉΓòÉ
  2522.  
  2523. hvt (HVALUETABLE) - input 
  2524.     Valuetable handle. 
  2525.  
  2526.  
  2527. ΓòÉΓòÉΓòÉ <hidden> WtkDeregisterSettingsDialog - Parameter hwndDialog ΓòÉΓòÉΓòÉ
  2528.  
  2529. hwndDialog (HWND) - input 
  2530.     Dialog handle of the settings notebook page. 
  2531.  
  2532.  
  2533. ΓòÉΓòÉΓòÉ <hidden> WtkDeregisterSettingsDialog - Parameters ΓòÉΓòÉΓòÉ
  2534.  
  2535. hvt (HVALUETABLE) - input 
  2536.     Valuetable handle. 
  2537.  
  2538.  hwndDialog (HWND) - input 
  2539.     Dialog handle of the settings notebook page. 
  2540.  
  2541.  fResult (BOOL) - returns 
  2542.     Success indicator. 
  2543.  
  2544.     TRUE 
  2545.               Dialog could be deregistered. 
  2546.     FALSE 
  2547.               An error occurred. 
  2548.  
  2549.  
  2550. ΓòÉΓòÉΓòÉ <hidden> WtkDeregisterSettingsDialog Return Value - fResult ΓòÉΓòÉΓòÉ
  2551.  
  2552. fResult (BOOL) - returns 
  2553.     Success indicator. 
  2554.  
  2555.     TRUE 
  2556.               Dialog could be deregistered. 
  2557.     FALSE 
  2558.               An error occurred. 
  2559.  
  2560.  
  2561. ΓòÉΓòÉΓòÉ <hidden> WtkDeregisterSettingsDialog - Remarks ΓòÉΓòÉΓòÉ
  2562.  
  2563. This function is to be called in the WM_DESTROY message handling of the window 
  2564. procedure being used for the settings notebookpages. 
  2565.  
  2566.  
  2567. ΓòÉΓòÉΓòÉ <hidden> WtkDeregisterSettingsDialog - Related functions ΓòÉΓòÉΓòÉ
  2568.  
  2569. Related Functions 
  2570.  
  2571. none 
  2572.  
  2573.  
  2574. ΓòÉΓòÉΓòÉ 8.18. WtkDestroyClassSettingsTable ΓòÉΓòÉΓòÉ
  2575.  
  2576. Select an item: 
  2577.  
  2578.      Syntax 
  2579.      Parameters 
  2580.      Returns 
  2581.      Remarks 
  2582.      Related Functions 
  2583.  
  2584.  
  2585. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyClassSettingsTable - Syntax ΓòÉΓòÉΓòÉ
  2586.  
  2587. This function destroys a settings table for a meta class. 
  2588.  
  2589. #define INCL_WTKSETTINGS
  2590. #include <wpstk.h>
  2591.  
  2592. HSETTINGTABLE   hst;       /* Settingstable handle.  */
  2593. BOOL            fResult;   /* Success indicator.     */
  2594.  
  2595. fResult = WtkDestroyClassSettingsTable( hst);
  2596.  
  2597.  
  2598. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyClassSettingsTable - Parameter hst ΓòÉΓòÉΓòÉ
  2599.  
  2600. hst (HSETTINGTABLE) - input 
  2601.     Settingstable handle. 
  2602.  
  2603.  
  2604. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyClassSettingsTable - Parameters ΓòÉΓòÉΓòÉ
  2605.  
  2606. hst (HSETTINGTABLE) - input 
  2607.     Settingstable handle. 
  2608.  
  2609.  fResult (BOOL) - returns 
  2610.     Success indicator. 
  2611.  
  2612.     TRUE 
  2613.               Settingstable could be destroyed. 
  2614.     FALSE 
  2615.               An error occurred. 
  2616.  
  2617.  
  2618. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyClassSettingsTable Return Value - fResult ΓòÉΓòÉΓòÉ
  2619.  
  2620. fResult (BOOL) - returns 
  2621.     Success indicator. 
  2622.  
  2623.     TRUE 
  2624.               Settingstable could be destroyed. 
  2625.     FALSE 
  2626.               An error occurred. 
  2627.  
  2628.  
  2629. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyClassSettingsTable - Remarks ΓòÉΓòÉΓòÉ
  2630.  
  2631. This function is to be called during _wpclsUnInitData. 
  2632.  
  2633.  
  2634. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyClassSettingsTable - Related functions ΓòÉΓòÉΓòÉ
  2635.  
  2636. Related Functions 
  2637.  
  2638. none 
  2639.  
  2640.  
  2641. ΓòÉΓòÉΓòÉ 8.19. WtkDestroyObjectValueTable ΓòÉΓòÉΓòÉ
  2642.  
  2643. Select an item: 
  2644.  
  2645.      Syntax 
  2646.      Parameters 
  2647.      Returns 
  2648.      Remarks 
  2649.      Related Functions 
  2650.  
  2651.  
  2652. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyObjectValueTable - Syntax ΓòÉΓòÉΓòÉ
  2653.  
  2654. This function detroys a valuetable for an object (instance) of a WPS class. 
  2655.  
  2656. #define INCL_WTKSETTINGS
  2657. #include <wpstk.h>
  2658.  
  2659. HVALUETABLE   hvt;       /* Valuetable handle.  */
  2660. BOOL          fResult;   /* Success indicator.  */
  2661.  
  2662. fResult = WtkDestroyObjectValueTable( hvt);
  2663.  
  2664.  
  2665. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyObjectValueTable - Parameter hvt ΓòÉΓòÉΓòÉ
  2666.  
  2667. hvt (HVALUETABLE) - input 
  2668.     Valuetable handle. 
  2669.  
  2670.  
  2671. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyObjectValueTable - Parameters ΓòÉΓòÉΓòÉ
  2672.  
  2673. hvt (HVALUETABLE) - input 
  2674.     Valuetable handle. 
  2675.  
  2676.  fResult (BOOL) - returns 
  2677.     Success indicator. 
  2678.  
  2679.     TRUE 
  2680.               Valuetable could be destroyed. 
  2681.     FALSE 
  2682.               An error occurred. 
  2683.  
  2684.  
  2685. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyObjectValueTable Return Value - fResult ΓòÉΓòÉΓòÉ
  2686.  
  2687. fResult (BOOL) - returns 
  2688.     Success indicator. 
  2689.  
  2690.     TRUE 
  2691.               Valuetable could be destroyed. 
  2692.     FALSE 
  2693.               An error occurred. 
  2694.  
  2695.  
  2696. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyObjectValueTable - Remarks ΓòÉΓòÉΓòÉ
  2697.  
  2698. This function is to be called during _wpUnInitData. 
  2699.  
  2700.  
  2701. ΓòÉΓòÉΓòÉ <hidden> WtkDestroyObjectValueTable - Related functions ΓòÉΓòÉΓòÉ
  2702.  
  2703. Related Functions 
  2704.  
  2705. none 
  2706.  
  2707.  
  2708. ΓòÉΓòÉΓòÉ 8.20. WtkDevIOCtl ΓòÉΓòÉΓòÉ
  2709.  
  2710. Select an item: 
  2711.  
  2712.      Syntax 
  2713.      Parameters 
  2714.      Returns 
  2715.      Remarks 
  2716.      Related Functions 
  2717.  
  2718.  
  2719. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Syntax ΓòÉΓòÉΓòÉ
  2720.  
  2721. This function performs an I/O control call transaction using DosDevIOCtl. The 
  2722. devices is opened, the I/O control call is made and the device is immediately 
  2723. closed again. 
  2724.  
  2725. #define INCL_WTKUTLIOCTRL
  2726. #include <wpstk.h>
  2727.  
  2728. PSZ      pszName;      /* Address of the ASCIIZ name of the device.        */
  2729. ULONG    ulOpenMode;   /* The mode, in which the device has to be opened.  */
  2730. ULONG    ulCategory;   /* Device category.                                 */
  2731. ULONG    ulFunction;   /* Device-specific function code.                   */
  2732. PVOID    pvParams;     /* Address of the command-specific argument list.   */
  2733. PULONG   pcbParmLen;   /* Pointer to the length of parameters.             */
  2734. PVOID    pvData;       /* Address of the data area.                        */
  2735. PULONG   pcbDataLen;   /* Pointer to the length of data.                   */
  2736. APIRET   ulrc;         /* Return Code.                                     */
  2737.  
  2738. ulrc = WtkDevIOCtl( pszName, ulOpenMode, ulCategory, ulFunction, pvParams, pcbParmLen, pvData, pcbDataLen);
  2739.  
  2740.  
  2741. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameter pszName ΓòÉΓòÉΓòÉ
  2742.  
  2743. pszName (PSZ) - input 
  2744.     Address of the ASCIIZ name of the device. 
  2745.  
  2746.     If the last character is a colon, the device is opened in block mode. 
  2747.  
  2748.  
  2749. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameter ulOpenMode ΓòÉΓòÉΓòÉ
  2750.  
  2751. ulOpenMode (ULONG) - input 
  2752.     The mode, in which the device has to be opened. 
  2753.  
  2754.     WTK_OPENDEVICE_SHARED 
  2755.               opens the device in readonly and thus in shared mode 
  2756.  
  2757.     WTK_OPENDEVICE_EXCLUSIVE 
  2758.               opens the device in readwrite and thus in exlusive mode 
  2759.  
  2760.     WTK_OPENDEVICE_NOCACHE 
  2761.               bypasses the cache, if block devices are opened 
  2762.  
  2763.     WTK_OPENDEVICE_BLOCKDEVICE 
  2764.               explicitely states, that the specified device is a block device. 
  2765.  
  2766.     Note:  If the last character is a colon, the device is opened in block 
  2767.     mode, even when WTK_OPENDEVICE_BLOCKDEVICE is not specified. 
  2768.  
  2769.  
  2770. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameter ulCategory ΓòÉΓòÉΓòÉ
  2771.  
  2772. ulCategory (ULONG) - input 
  2773.     Device category. 
  2774.  
  2775.     The valid range is 0 to 255. 
  2776.  
  2777.  
  2778. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameter ulFunction ΓòÉΓòÉΓòÉ
  2779.  
  2780. ulFunction (ULONG) - input 
  2781.     Device-specific function code. 
  2782.  
  2783.     The valid range is 0 to 255. 
  2784.  
  2785.  
  2786. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameter pvParams ΓòÉΓòÉΓòÉ
  2787.  
  2788. pvParams (PVOID) - input 
  2789.     Address of the command-specific argument list. 
  2790.  
  2791.  
  2792. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameter pcbParmLen ΓòÉΓòÉΓòÉ
  2793.  
  2794. pcbParmLen (PULONG) - input/output 
  2795.     Pointer to the length of parameters. 
  2796.  
  2797.     Input     Pointer to the length, in bytes, of the parameters passed in 
  2798.               pParams by the application. 
  2799.  
  2800.     Output    Pointer to the length, in bytes, of the parameters returned. 
  2801.  
  2802.               If this function returns ERROR_BUFFER_OVERFLOW, then pcbParmLen 
  2803.               points to the size of the buffer required to hold the parameters 
  2804.               returned. No other data is returned in this case. 
  2805.  
  2806.     Note:  Compared to DosDevIOCtl, this function is missing the parameter 
  2807.     cbParmLenMax. On calling DosDevIOCtl this function sets cbParmLenMax to the 
  2808.     value pointed to by pcbParmLen. If this is not applicable to your code, use 
  2809.     DosDevIOCtl instead. 
  2810.  
  2811.  
  2812. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameter pvData ΓòÉΓòÉΓòÉ
  2813.  
  2814. pvData (PVOID) - input 
  2815.     Address of the data area. 
  2816.  
  2817.  
  2818. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameter pcbDataLen ΓòÉΓòÉΓòÉ
  2819.  
  2820. pcbDataLen (PULONG) - input/output 
  2821.     Pointer to the length of data. 
  2822.  
  2823.     Input     Pointer to the length, in bytes, of the data passed by the 
  2824.               application in pData. 
  2825.  
  2826.     Output    Pointer to the length, in bytes, of the data returned. 
  2827.  
  2828.               If this function returns ERROR_BUFFER_OVERFLOW, then pcbDataLen 
  2829.               points to the size of the buffer required to hold the data 
  2830.               returned. 
  2831.  
  2832.     Note:  Compared to DosDevIOCtl, this function is missing the parameter 
  2833.     cbDataLenMax. On calling DosDevIOCtl this function sets cbDataLenMax to the 
  2834.     value pointed to by pcbDataLen. If this is not applicable to your code, use 
  2835.     DosDevIOCtl instead. 
  2836.  
  2837.  
  2838. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Parameters ΓòÉΓòÉΓòÉ
  2839.  
  2840. pszName (PSZ) - input 
  2841.     Address of the ASCIIZ name of the device. 
  2842.  
  2843.     If the last character is a colon, the device is opened in block mode. 
  2844.  
  2845.  ulOpenMode (ULONG) - input 
  2846.     The mode, in which the device has to be opened. 
  2847.  
  2848.     WTK_OPENDEVICE_SHARED 
  2849.               opens the device in readonly and thus in shared mode 
  2850.  
  2851.     WTK_OPENDEVICE_EXCLUSIVE 
  2852.               opens the device in readwrite and thus in exlusive mode 
  2853.  
  2854.     WTK_OPENDEVICE_NOCACHE 
  2855.               bypasses the cache, if block devices are opened 
  2856.  
  2857.     WTK_OPENDEVICE_BLOCKDEVICE 
  2858.               explicitely states, that the specified device is a block device. 
  2859.  
  2860.     Note:  If the last character is a colon, the device is opened in block 
  2861.     mode, even when WTK_OPENDEVICE_BLOCKDEVICE is not specified. 
  2862.  
  2863.  ulCategory (ULONG) - input 
  2864.     Device category. 
  2865.  
  2866.     The valid range is 0 to 255. 
  2867.  
  2868.  ulFunction (ULONG) - input 
  2869.     Device-specific function code. 
  2870.  
  2871.     The valid range is 0 to 255. 
  2872.  
  2873.  pvParams (PVOID) - input 
  2874.     Address of the command-specific argument list. 
  2875.  
  2876.  pcbParmLen (PULONG) - input/output 
  2877.     Pointer to the length of parameters. 
  2878.  
  2879.     Input     Pointer to the length, in bytes, of the parameters passed in 
  2880.               pParams by the application. 
  2881.  
  2882.     Output    Pointer to the length, in bytes, of the parameters returned. 
  2883.  
  2884.               If this function returns ERROR_BUFFER_OVERFLOW, then pcbParmLen 
  2885.               points to the size of the buffer required to hold the parameters 
  2886.               returned. No other data is returned in this case. 
  2887.  
  2888.     Note:  Compared to DosDevIOCtl, this function is missing the parameter 
  2889.     cbParmLenMax. On calling DosDevIOCtl this function sets cbParmLenMax to the 
  2890.     value pointed to by pcbParmLen. If this is not applicable to your code, use 
  2891.     DosDevIOCtl instead. 
  2892.  
  2893.  pvData (PVOID) - input 
  2894.     Address of the data area. 
  2895.  
  2896.  pcbDataLen (PULONG) - input/output 
  2897.     Pointer to the length of data. 
  2898.  
  2899.     Input     Pointer to the length, in bytes, of the data passed by the 
  2900.               application in pData. 
  2901.  
  2902.     Output    Pointer to the length, in bytes, of the data returned. 
  2903.  
  2904.               If this function returns ERROR_BUFFER_OVERFLOW, then pcbDataLen 
  2905.               points to the size of the buffer required to hold the data 
  2906.               returned. 
  2907.  
  2908.     Note:  Compared to DosDevIOCtl, this function is missing the parameter 
  2909.     cbDataLenMax. On calling DosDevIOCtl this function sets cbDataLenMax to the 
  2910.     value pointed to by pcbDataLen. If this is not applicable to your code, use 
  2911.     DosDevIOCtl instead. 
  2912.  
  2913.  ulrc (APIRET) - returns 
  2914.     Return Code. 
  2915.  
  2916.     WtkDevIOCtl returns one of the following return codes: 
  2917.  
  2918.     0         NO_ERROR 
  2919.     87        ERROR_INVALID_PARAMETER 
  2920.  
  2921.     or return codes of the following functions 
  2922.  
  2923.         DosDevIOCtl 
  2924.  
  2925.  
  2926. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl Return Value - ulrc ΓòÉΓòÉΓòÉ
  2927.  
  2928. ulrc (APIRET) - returns 
  2929.     Return Code. 
  2930.  
  2931.     WtkDevIOCtl returns one of the following return codes: 
  2932.  
  2933.     0         NO_ERROR 
  2934.     87        ERROR_INVALID_PARAMETER 
  2935.  
  2936.     or return codes of the following functions 
  2937.  
  2938.         DosDevIOCtl 
  2939.  
  2940.  
  2941. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Remarks ΓòÉΓòÉΓòÉ
  2942.  
  2943. In order to simplify coding a littlebit, this function does not provide the 
  2944. parameters cbParmLenMax and cbDataLenMax, but instead implicitely sets them to 
  2945. the values pointed by the parameters pcbParmLen and pcbDataLen. This is done as 
  2946. in most cases this is sufficient. If this is not applicable to your code, use 
  2947. DosDevIOCtl instead. 
  2948.  
  2949.  
  2950. ΓòÉΓòÉΓòÉ <hidden> WtkDevIOCtl - Related functions ΓòÉΓòÉΓòÉ
  2951.  
  2952. Related Functions 
  2953.  
  2954. none 
  2955.  
  2956.  
  2957. ΓòÉΓòÉΓòÉ 8.21. WtkDirExists ΓòÉΓòÉΓòÉ
  2958.  
  2959. Select an item: 
  2960.  
  2961.      Syntax 
  2962.      Parameters 
  2963.      Returns 
  2964.      Remarks 
  2965.      Related Functions 
  2966.  
  2967.  
  2968. ΓòÉΓòÉΓòÉ <hidden> WtkDirExists - Syntax ΓòÉΓòÉΓòÉ
  2969.  
  2970. This function checks, if a given directory exists. 
  2971.  
  2972. #define INCL_WTKUTLFILE
  2973. #include <wpstk.h>
  2974.  
  2975. PSZ    pszName;   /* Address of the ASCIIZ path name of the directory to be searched.  */
  2976. BOOL   fResult;   /* Success indicator.                                                */
  2977.  
  2978. fResult = WtkDirExists( pszName);
  2979.  
  2980.  
  2981. ΓòÉΓòÉΓòÉ <hidden> WtkDirExists - Parameter pszName ΓòÉΓòÉΓòÉ
  2982.  
  2983. pszName (PSZ) - input 
  2984.     Address of the ASCIIZ path name of the directory to be searched. 
  2985.  
  2986.     The path name may contain ?: for the drive in order to open the directory 
  2987.     on the boot drive. 
  2988.  
  2989.     The name may not include wildcards. 
  2990.  
  2991.  
  2992. ΓòÉΓòÉΓòÉ <hidden> WtkDirExists - Parameters ΓòÉΓòÉΓòÉ
  2993.  
  2994. pszName (PSZ) - input 
  2995.     Address of the ASCIIZ path name of the directory to be searched. 
  2996.  
  2997.     The path name may contain ?: for the drive in order to open the directory 
  2998.     on the boot drive. 
  2999.  
  3000.     The name may not include wildcards. 
  3001.  
  3002.  fResult (BOOL) - returns 
  3003.     Success indicator. 
  3004.  
  3005.     TRUE 
  3006.               Directory exists. 
  3007.     FALSE 
  3008.               Directory not found. 
  3009.  
  3010.  
  3011. ΓòÉΓòÉΓòÉ <hidden> WtkDirExists Return Value - fResult ΓòÉΓòÉΓòÉ
  3012.  
  3013. fResult (BOOL) - returns 
  3014.     Success indicator. 
  3015.  
  3016.     TRUE 
  3017.               Directory exists. 
  3018.     FALSE 
  3019.               Directory not found. 
  3020.  
  3021.  
  3022. ΓòÉΓòÉΓòÉ <hidden> WtkDirExists - Remarks ΓòÉΓòÉΓòÉ
  3023.  
  3024. This function is identical to WtkIsDirectory. 
  3025.  
  3026. This function supports boot drive recognition. Specify ?: for the drive in 
  3027. order to open the directory on the boot drive. 
  3028.  
  3029.  
  3030. ΓòÉΓòÉΓòÉ <hidden> WtkDirExists - Related functions ΓòÉΓòÉΓòÉ
  3031.  
  3032. Related Functions 
  3033.  
  3034. none 
  3035.  
  3036.  
  3037. ΓòÉΓòÉΓòÉ 8.22. WtkDumpClassSettingsTable ΓòÉΓòÉΓòÉ
  3038.  
  3039. Select an item: 
  3040.  
  3041.      Syntax 
  3042.      Parameters 
  3043.      Returns 
  3044.      Remarks 
  3045.      Related Functions 
  3046.  
  3047.  
  3048. ΓòÉΓòÉΓòÉ <hidden> WtkDumpClassSettingsTable - Syntax ΓòÉΓòÉΓòÉ
  3049.  
  3050. This function dumps a settings table to the console. 
  3051.  
  3052. #define INCL_WTKSETTINGS
  3053. #include <wpstk.h>
  3054.  
  3055. HSETTINGTABLE   hst;       /* Settingstable handle.  */
  3056. BOOL            fResult;   /* Success indicator.     */
  3057.  
  3058. fResult = WtkDumpClassSettingsTable( hst);
  3059.  
  3060.  
  3061. ΓòÉΓòÉΓòÉ <hidden> WtkDumpClassSettingsTable - Parameter hst ΓòÉΓòÉΓòÉ
  3062.  
  3063. hst (HSETTINGTABLE) - input 
  3064.     Settingstable handle. 
  3065.  
  3066.  
  3067. ΓòÉΓòÉΓòÉ <hidden> WtkDumpClassSettingsTable - Parameters ΓòÉΓòÉΓòÉ
  3068.  
  3069. hst (HSETTINGTABLE) - input 
  3070.     Settingstable handle. 
  3071.  
  3072.  fResult (BOOL) - returns 
  3073.     Success indicator. 
  3074.  
  3075.     TRUE 
  3076.               Settingstable could be dumped. 
  3077.     FALSE 
  3078.               An error occurred. 
  3079.  
  3080.  
  3081. ΓòÉΓòÉΓòÉ <hidden> WtkDumpClassSettingsTable Return Value - fResult ΓòÉΓòÉΓòÉ
  3082.  
  3083. fResult (BOOL) - returns 
  3084.     Success indicator. 
  3085.  
  3086.     TRUE 
  3087.               Settingstable could be dumped. 
  3088.     FALSE 
  3089.               An error occurred. 
  3090.  
  3091.  
  3092. ΓòÉΓòÉΓòÉ <hidden> WtkDumpClassSettingsTable - Remarks ΓòÉΓòÉΓòÉ
  3093.  
  3094. This function is for debug purposes only. It uses printf to display the current 
  3095. status of the class settingstable, so that you can catch the output by linking 
  3096. printf.obj of the PM Printf package to your WPS class while testing. 
  3097.  
  3098.  
  3099. ΓòÉΓòÉΓòÉ <hidden> WtkDumpClassSettingsTable - Related functions ΓòÉΓòÉΓòÉ
  3100.  
  3101. Related Functions 
  3102.  
  3103. none 
  3104.  
  3105.  
  3106. ΓòÉΓòÉΓòÉ 8.23. WtkEvaluateObjectSettings ΓòÉΓòÉΓòÉ
  3107.  
  3108. Select an item: 
  3109.  
  3110.      Syntax 
  3111.      Parameters 
  3112.      Returns 
  3113.      Remarks 
  3114.      Related Functions 
  3115.  
  3116.  
  3117. ΓòÉΓòÉΓòÉ <hidden> WtkEvaluateObjectSettings - Syntax ΓòÉΓòÉΓòÉ
  3118.  
  3119. This function evaluates a settingsstring for a WPS class. This includes 
  3120. validation of the values and the update of both the object valuetable and 
  3121. object details, and, if desired, the update of controls of open settings 
  3122. notebook dialog being associated to certain settings (sub)values. 
  3123.  
  3124. #define INCL_WTKSETTINGS
  3125. #include <wpstk.h>
  3126.  
  3127. HVALUETABLE   hvt;        /* Valuetable handle.           */
  3128. PSZ           pszSetup;   /* Setup string from _wpSetup.  */
  3129. BOOL          fResult;    /* Success indicator.           */
  3130.  
  3131. fResult = WtkEvaluateObjectSettings( hvt, pszSetup);
  3132.  
  3133.  
  3134. ΓòÉΓòÉΓòÉ <hidden> WtkEvaluateObjectSettings - Parameter hvt ΓòÉΓòÉΓòÉ
  3135.  
  3136. hvt (HVALUETABLE) - input 
  3137.     Valuetable handle. 
  3138.  
  3139.  
  3140. ΓòÉΓòÉΓòÉ <hidden> WtkEvaluateObjectSettings - Parameter pszSetup ΓòÉΓòÉΓòÉ
  3141.  
  3142. pszSetup (PSZ) - input 
  3143.     Setup string from _wpSetup. 
  3144.  
  3145.  
  3146. ΓòÉΓòÉΓòÉ <hidden> WtkEvaluateObjectSettings - Parameters ΓòÉΓòÉΓòÉ
  3147.  
  3148. hvt (HVALUETABLE) - input 
  3149.     Valuetable handle. 
  3150.  
  3151.  pszSetup (PSZ) - input 
  3152.     Setup string from _wpSetup. 
  3153.  
  3154.  fResult (BOOL) - returns 
  3155.     Success indicator. 
  3156.  
  3157.     TRUE 
  3158.               String could be evaluated. 
  3159.     FALSE 
  3160.               An error occurred. 
  3161.  
  3162.  
  3163. ΓòÉΓòÉΓòÉ <hidden> WtkEvaluateObjectSettings Return Value - fResult ΓòÉΓòÉΓòÉ
  3164.  
  3165. fResult (BOOL) - returns 
  3166.     Success indicator. 
  3167.  
  3168.     TRUE 
  3169.               String could be evaluated. 
  3170.     FALSE 
  3171.               An error occurred. 
  3172.  
  3173.  
  3174. ΓòÉΓòÉΓòÉ <hidden> WtkEvaluateObjectSettings - Remarks ΓòÉΓòÉΓòÉ
  3175.  
  3176. This function is to be called during _wpSetup in order to handle the given 
  3177. setup string. 
  3178.  
  3179. Note:  You still must pass pszSetup to the parent class, because 
  3180. WtkEvaluateObjectSettings will only handle the settings being implemented by 
  3181. your WPS class ! 
  3182.  
  3183. If a settings notebook of the object is open, and you asked the settings 
  3184. manager for automatic update of GUI controls, the appropriate GUI controls are 
  3185. automatically updated. 
  3186.  
  3187.  
  3188. ΓòÉΓòÉΓòÉ <hidden> WtkEvaluateObjectSettings - Related functions ΓòÉΓòÉΓòÉ
  3189.  
  3190. Related Functions 
  3191.  
  3192. none 
  3193.  
  3194.  
  3195. ΓòÉΓòÉΓòÉ 8.24. WtkFDateTimeToTime ΓòÉΓòÉΓòÉ
  3196.  
  3197. Select an item: 
  3198.  
  3199.      Syntax 
  3200.      Parameters 
  3201.      Returns 
  3202.      Remarks 
  3203.      Related Functions 
  3204.  
  3205.  
  3206. ΓòÉΓòÉΓòÉ <hidden> WtkFDateTimeToTime - Syntax ΓòÉΓòÉΓòÉ
  3207.  
  3208. This function converts the contents of a FDATE and a FTIME stucture to a time 
  3209. value used by the compiler runtime. 
  3210.  
  3211. #define INCL_WTKUTLTIME
  3212. #include <wpstk.h>
  3213.  
  3214. PFDATE    pfdate;    /* Address of the FDATE structure.       */
  3215. PFTIME    pftime;    /* Address of the FTIME structure.       */
  3216. time_t   *ptime;     /* Address of the resulting time value.  */
  3217. BOOL      fResult;   /* Success indicator.                    */
  3218.  
  3219. fResult = WtkFDateTimeToTime( pfdate, pftime, ptime);
  3220.  
  3221.  
  3222. ΓòÉΓòÉΓòÉ <hidden> WtkFDateTimeToTime - Parameter pfdate ΓòÉΓòÉΓòÉ
  3223.  
  3224. pfdate (PFDATE) - input 
  3225.     Address of the FDATE structure. 
  3226.  
  3227.  
  3228. ΓòÉΓòÉΓòÉ <hidden> WtkFDateTimeToTime - Parameter pftime ΓòÉΓòÉΓòÉ
  3229.  
  3230. pftime (PFTIME) - input 
  3231.     Address of the FTIME structure. 
  3232.  
  3233.  
  3234. ΓòÉΓòÉΓòÉ <hidden> WtkFDateTimeToTime - Parameter ptime ΓòÉΓòÉΓòÉ
  3235.  
  3236. ptime (time_t*) - output 
  3237.     Address of the resulting time value. 
  3238.  
  3239.  
  3240. ΓòÉΓòÉΓòÉ <hidden> WtkFDateTimeToTime - Parameters ΓòÉΓòÉΓòÉ
  3241.  
  3242. pfdate (PFDATE) - input 
  3243.     Address of the FDATE structure. 
  3244.  
  3245.  pftime (PFTIME) - input 
  3246.     Address of the FTIME structure. 
  3247.  
  3248.  ptime (time_t*) - output 
  3249.     Address of the resulting time value. 
  3250.  
  3251.  fResult (BOOL) - returns 
  3252.     Success indicator. 
  3253.  
  3254.     TRUE 
  3255.               Conversion successful. 
  3256.     FALSE 
  3257.               Conversion not successful or invalid parameters. 
  3258.  
  3259.  
  3260. ΓòÉΓòÉΓòÉ <hidden> WtkFDateTimeToTime Return Value - fResult ΓòÉΓòÉΓòÉ
  3261.  
  3262. fResult (BOOL) - returns 
  3263.     Success indicator. 
  3264.  
  3265.     TRUE 
  3266.               Conversion successful. 
  3267.     FALSE 
  3268.               Conversion not successful or invalid parameters. 
  3269.  
  3270.  
  3271. ΓòÉΓòÉΓòÉ <hidden> WtkFDateTimeToTime - Remarks ΓòÉΓòÉΓòÉ
  3272.  
  3273. This function does not check any of the values of the FDATE or FTIME structures 
  3274. before converting. 
  3275.  
  3276.  
  3277. ΓòÉΓòÉΓòÉ <hidden> WtkFDateTimeToTime - Related functions ΓòÉΓòÉΓòÉ
  3278.  
  3279. Related Functions 
  3280.  
  3281. none 
  3282.  
  3283.  
  3284. ΓòÉΓòÉΓòÉ 8.25. WtkFileExists ΓòÉΓòÉΓòÉ
  3285.  
  3286. Select an item: 
  3287.  
  3288.      Syntax 
  3289.      Parameters 
  3290.      Returns 
  3291.      Remarks 
  3292.      Related Functions 
  3293.  
  3294.  
  3295. ΓòÉΓòÉΓòÉ <hidden> WtkFileExists - Syntax ΓòÉΓòÉΓòÉ
  3296.  
  3297. This function checks, if a given file exists. 
  3298.  
  3299. #define INCL_WTKUTLFILE
  3300. #include <wpstk.h>
  3301.  
  3302. PSZ    pszName;   /* Address of the ASCIIZ path name of the file to be searched.  */
  3303. BOOL   fResult;   /* Success indicator.                                           */
  3304.  
  3305. fResult = WtkFileExists( pszName);
  3306.  
  3307.  
  3308. ΓòÉΓòÉΓòÉ <hidden> WtkFileExists - Parameter pszName ΓòÉΓòÉΓòÉ
  3309.  
  3310. pszName (PSZ) - input 
  3311.     Address of the ASCIIZ path name of the file to be searched. 
  3312.  
  3313.     The path name may contain ?: for the drive in order to open the file on the 
  3314.     boot drive. 
  3315.  
  3316.     The name may not include wildcards. In order to search with wildcards, use 
  3317.     WtkFileMaskExists. 
  3318.  
  3319.  
  3320. ΓòÉΓòÉΓòÉ <hidden> WtkFileExists - Parameters ΓòÉΓòÉΓòÉ
  3321.  
  3322. pszName (PSZ) - input 
  3323.     Address of the ASCIIZ path name of the file to be searched. 
  3324.  
  3325.     The path name may contain ?: for the drive in order to open the file on the 
  3326.     boot drive. 
  3327.  
  3328.     The name may not include wildcards. In order to search with wildcards, use 
  3329.     WtkFileMaskExists. 
  3330.  
  3331.  fResult (BOOL) - returns 
  3332.     Success indicator. 
  3333.  
  3334.     TRUE 
  3335.               File exists. 
  3336.     FALSE 
  3337.               File not found. 
  3338.  
  3339.  
  3340. ΓòÉΓòÉΓòÉ <hidden> WtkFileExists Return Value - fResult ΓòÉΓòÉΓòÉ
  3341.  
  3342. fResult (BOOL) - returns 
  3343.     Success indicator. 
  3344.  
  3345.     TRUE 
  3346.               File exists. 
  3347.     FALSE 
  3348.               File not found. 
  3349.  
  3350.  
  3351. ΓòÉΓòÉΓòÉ <hidden> WtkFileExists - Remarks ΓòÉΓòÉΓòÉ
  3352.  
  3353. This function is identical to WtkIsFile. 
  3354.  
  3355. This function supports boot drive recognition. Specify ?: for the drive in 
  3356. order to open the file on the boot drive. 
  3357.  
  3358.  
  3359. ΓòÉΓòÉΓòÉ <hidden> WtkFileExists - Related functions ΓòÉΓòÉΓòÉ
  3360.  
  3361. Related Functions 
  3362.  
  3363. none 
  3364.  
  3365.  
  3366. ΓòÉΓòÉΓòÉ 8.26. WtkFileMaskExists ΓòÉΓòÉΓòÉ
  3367.  
  3368. Select an item: 
  3369.  
  3370.      Syntax 
  3371.      Parameters 
  3372.      Returns 
  3373.      Remarks 
  3374.      Related Functions 
  3375.  
  3376.  
  3377. ΓòÉΓòÉΓòÉ <hidden> WtkFileMaskExists - Syntax ΓòÉΓòÉΓòÉ
  3378.  
  3379. This function checks, if a set of files exist, and returns the first file being 
  3380. found. 
  3381.  
  3382. #define INCL_WTKUTLFILE
  3383. #include <wpstk.h>
  3384.  
  3385. PSZ     pszFileMask;    /* Address of the ASCIIZ path name of the fileset to search.                                  */
  3386. PSZ     pszFirstFile;   /* The address of a buffer in into which the name of the first file being found is returned.  */
  3387. ULONG   ulBuflen;       /* The length, in bytes, of the buffer described by pszFirstFile.                             */
  3388. BOOL    fResult;        /* Success indicator.                                                                         */
  3389.  
  3390. fResult = WtkFileMaskExists( pszFileMask, pszFirstFile, ulBuflen);
  3391.  
  3392.  
  3393. ΓòÉΓòÉΓòÉ <hidden> WtkFileMaskExists - Parameter pszFileMask ΓòÉΓòÉΓòÉ
  3394.  
  3395. pszFileMask (PSZ) - input 
  3396.     Address of the ASCIIZ path name of the fileset to search. 
  3397.  
  3398.     The path name may contain wildcard characters. 
  3399.  
  3400.     The path name may contain ?: for the drive in order to search files on the 
  3401.     boot drive. 
  3402.  
  3403.  
  3404. ΓòÉΓòÉΓòÉ <hidden> WtkFileMaskExists - Parameter pszFirstFile ΓòÉΓòÉΓòÉ
  3405.  
  3406. pszFirstFile (PSZ) - output 
  3407.     The address of a buffer in into which the name of the first file being 
  3408.     found is returned. 
  3409.  
  3410.  
  3411. ΓòÉΓòÉΓòÉ <hidden> WtkFileMaskExists - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  3412.  
  3413. ulBuflen (ULONG) - input 
  3414.     The length, in bytes, of the buffer described by pszFirstFile. 
  3415.  
  3416.  
  3417. ΓòÉΓòÉΓòÉ <hidden> WtkFileMaskExists - Parameters ΓòÉΓòÉΓòÉ
  3418.  
  3419. pszFileMask (PSZ) - input 
  3420.     Address of the ASCIIZ path name of the fileset to search. 
  3421.  
  3422.     The path name may contain wildcard characters. 
  3423.  
  3424.     The path name may contain ?: for the drive in order to search files on the 
  3425.     boot drive. 
  3426.  
  3427.  pszFirstFile (PSZ) - output 
  3428.     The address of a buffer in into which the name of the first file being 
  3429.     found is returned. 
  3430.  
  3431.  ulBuflen (ULONG) - input 
  3432.     The length, in bytes, of the buffer described by pszFirstFile. 
  3433.  
  3434.  fResult (BOOL) - returns 
  3435.     Success indicator. 
  3436.  
  3437.     TRUE 
  3438.               File(s) exist(s). 
  3439.     FALSE 
  3440.               File(s) not found. 
  3441.  
  3442.  
  3443. ΓòÉΓòÉΓòÉ <hidden> WtkFileMaskExists Return Value - fResult ΓòÉΓòÉΓòÉ
  3444.  
  3445. fResult (BOOL) - returns 
  3446.     Success indicator. 
  3447.  
  3448.     TRUE 
  3449.               File(s) exist(s). 
  3450.     FALSE 
  3451.               File(s) not found. 
  3452.  
  3453.  
  3454. ΓòÉΓòÉΓòÉ <hidden> WtkFileMaskExists - Remarks ΓòÉΓòÉΓòÉ
  3455.  
  3456. This function supports boot drive recognition. Specify ?: for the drive in 
  3457. order to search the files on the boot drive. 
  3458.  
  3459.  
  3460. ΓòÉΓòÉΓòÉ <hidden> WtkFileMaskExists - Related functions ΓòÉΓòÉΓòÉ
  3461.  
  3462. Related Functions 
  3463.  
  3464. none 
  3465.  
  3466.  
  3467. ΓòÉΓòÉΓòÉ 8.27. WtkFileModified ΓòÉΓòÉΓòÉ
  3468.  
  3469. Select an item: 
  3470.  
  3471.      Syntax 
  3472.      Parameters 
  3473.      Returns 
  3474.      Remarks 
  3475.      Related Functions 
  3476.  
  3477.  
  3478. ΓòÉΓòÉΓòÉ <hidden> WtkFileModified - Syntax ΓòÉΓòÉΓòÉ
  3479.  
  3480. This function detects modifications of a file or directory. 
  3481.  
  3482. #define INCL_WTKUTLFILE
  3483. #include <wpstk.h>
  3484.  
  3485. PSZ            pszName;   /* Address of the ASCIIZ path name of the file or directory, which is to be checked for modifications.                                                                                                       */
  3486. 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.  */
  3487. BOOL           fResult;   /* Modification indicator.                                                                                                                                                                                   */
  3488.  
  3489. fResult = WtkFileModified( pszName, pfs3);
  3490.  
  3491.  
  3492. ΓòÉΓòÉΓòÉ <hidden> WtkFileModified - Parameter pszName ΓòÉΓòÉΓòÉ
  3493.  
  3494. pszName (PSZ) - input 
  3495.     Address of the ASCIIZ path name of the file or directory, which is to be 
  3496.     checked for modifications. 
  3497.  
  3498.     The path name may contain ?: for the drive in order to search the file or 
  3499.     directory on the boot drive. 
  3500.  
  3501.  
  3502. ΓòÉΓòÉΓòÉ <hidden> WtkFileModified - Parameter pfs3 ΓòÉΓòÉΓòÉ
  3503.  
  3504. pfs3 (PFILESTATUS3) - input 
  3505.     Address of a FILESTATUS3 structure previously being filled by 
  3506.     DosQueryPathInfo or WtkFileModified for the same file. Every call to 
  3507.     WtkFileModified will update that structure, if the file has modified. 
  3508.  
  3509.  
  3510. ΓòÉΓòÉΓòÉ <hidden> WtkFileModified - Parameters ΓòÉΓòÉΓòÉ
  3511.  
  3512. pszName (PSZ) - input 
  3513.     Address of the ASCIIZ path name of the file or directory, which is to be 
  3514.     checked for modifications. 
  3515.  
  3516.     The path name may contain ?: for the drive in order to search the file or 
  3517.     directory on the boot drive. 
  3518.  
  3519.  pfs3 (PFILESTATUS3) - input 
  3520.     Address of a FILESTATUS3 structure previously being filled by 
  3521.     DosQueryPathInfo or WtkFileModified for the same file. Every call to 
  3522.     WtkFileModified will update that structure, if the file has modified. 
  3523.  
  3524.  fResult (BOOL) - returns 
  3525.     Modification indicator. 
  3526.  
  3527.     TRUE 
  3528.               File has been modified 
  3529.     FALSE 
  3530.  
  3531.                   File has not been modified or could not be found 
  3532.                   An invalid parameter has been specified. 
  3533.  
  3534.  
  3535. ΓòÉΓòÉΓòÉ <hidden> WtkFileModified Return Value - fResult ΓòÉΓòÉΓòÉ
  3536.  
  3537. fResult (BOOL) - returns 
  3538.     Modification indicator. 
  3539.  
  3540.     TRUE 
  3541.               File has been modified 
  3542.     FALSE 
  3543.  
  3544.                   File has not been modified or could not be found 
  3545.                   An invalid parameter has been specified. 
  3546.  
  3547.  
  3548. ΓòÉΓòÉΓòÉ <hidden> WtkFileModified - Remarks ΓòÉΓòÉΓòÉ
  3549.  
  3550. Before calling WtkFileModified, the caller must get the FIL_STANDARD 
  3551. information from DosQueryPathInfo for the file or directory in order to be able 
  3552. to determine, wether the file has been modified or not. Also the file status 
  3553. data may have been updated by a previous call to WtkFileModified. 
  3554.  
  3555. Note, that all modifications in the FILESTATUS3 structure are being monitored, 
  3556. thus also the date and time of last access and last read. 
  3557.  
  3558. This function supports boot drive recognition. Specify ?: for the drive in 
  3559. order to search the file or directory on the boot drive. 
  3560.  
  3561.  
  3562. ΓòÉΓòÉΓòÉ <hidden> WtkFileModified - Related functions ΓòÉΓòÉΓòÉ
  3563.  
  3564. Related Functions 
  3565.  
  3566. none 
  3567.  
  3568.  
  3569. ΓòÉΓòÉΓòÉ 8.28. WtkFilespec ΓòÉΓòÉΓòÉ
  3570.  
  3571. Select an item: 
  3572.  
  3573.      Syntax 
  3574.      Parameters 
  3575.      Returns 
  3576.      Remarks 
  3577.      Related Functions 
  3578.  
  3579.  
  3580. ΓòÉΓòÉΓòÉ <hidden> WtkFilespec - Syntax ΓòÉΓòÉΓòÉ
  3581.  
  3582. This function searches for certain pathname components in a given pathname. 
  3583.  
  3584. #define INCL_WTKUTLFILE
  3585. #include <wpstk.h>
  3586.  
  3587. PSZ     pszName;     /* Address of the ASCIIZ filename, of which a part ist to be returned.  */
  3588. ULONG   ulPart;      /* The type of information to be returned.                              */
  3589. PSZ     pszResult;   /* Pointer to the requested pathname component.                         */
  3590.  
  3591. pszResult = WtkFilespec( pszName, ulPart);
  3592.  
  3593.  
  3594. ΓòÉΓòÉΓòÉ <hidden> WtkFilespec - Parameter pszName ΓòÉΓòÉΓòÉ
  3595.  
  3596. pszName (PSZ) - input 
  3597.     Address of the ASCIIZ filename, of which a part ist to be returned. 
  3598.  
  3599.  
  3600. ΓòÉΓòÉΓòÉ <hidden> WtkFilespec - Parameter ulPart ΓòÉΓòÉΓòÉ
  3601.  
  3602. ulPart (ULONG) - input 
  3603.     The type of information to be returned. 
  3604.  
  3605.     WTK_FILESPEC_PATHNAME 
  3606.               returns a pointer to the begin of the path, not icluding a 
  3607.               possibly specified drive 
  3608.  
  3609.     WTK_FILESPEC_NAME 
  3610.               returns a pointer to the filename 
  3611.  
  3612.     WTK_FILESPEC_EXTENSION 
  3613.               returns a pointer to the last file extension 
  3614.  
  3615.  
  3616. ΓòÉΓòÉΓòÉ <hidden> WtkFilespec - Parameters ΓòÉΓòÉΓòÉ
  3617.  
  3618. pszName (PSZ) - input 
  3619.     Address of the ASCIIZ filename, of which a part ist to be returned. 
  3620.  
  3621.  ulPart (ULONG) - input 
  3622.     The type of information to be returned. 
  3623.  
  3624.     WTK_FILESPEC_PATHNAME 
  3625.               returns a pointer to the begin of the path, not icluding a 
  3626.               possibly specified drive 
  3627.  
  3628.     WTK_FILESPEC_NAME 
  3629.               returns a pointer to the filename 
  3630.  
  3631.     WTK_FILESPEC_EXTENSION 
  3632.               returns a pointer to the last file extension 
  3633.  
  3634.  pszResult (PSZ) - returns 
  3635.     Pointer to the requested pathname component.  If the requested component 
  3636.     could not be found, NULL is returned. 
  3637.  
  3638.  
  3639. ΓòÉΓòÉΓòÉ <hidden> WtkFilespec Return Value - pszResult ΓòÉΓòÉΓòÉ
  3640.  
  3641. pszResult (PSZ) - returns 
  3642.     Pointer to the requested pathname component.  If the requested component 
  3643.     could not be found, NULL is returned. 
  3644.  
  3645.  
  3646. ΓòÉΓòÉΓòÉ <hidden> WtkFilespec - Remarks ΓòÉΓòÉΓòÉ
  3647.  
  3648. WtkFilespec returns a pointer to a part fo the string, that is being passed 
  3649. with pszName. 
  3650.  
  3651.  
  3652. ΓòÉΓòÉΓòÉ <hidden> WtkFilespec - Related functions ΓòÉΓòÉΓòÉ
  3653.  
  3654. Related Functions 
  3655.  
  3656. none 
  3657.  
  3658.  
  3659. ΓòÉΓòÉΓòÉ 8.29. WtkFindFirstEaValue ΓòÉΓòÉΓòÉ
  3660.  
  3661. Select an item: 
  3662.  
  3663.      Syntax 
  3664.      Parameters 
  3665.      Returns 
  3666.      Remarks 
  3667.      Related Functions 
  3668.  
  3669.  
  3670. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue - Syntax ΓòÉΓòÉΓòÉ
  3671.  
  3672. This function scans a extended attribute previously read by WtkReadEa for the 
  3673. first value of a given type. 
  3674.  
  3675. #define INCL_WTKEAS
  3676. #include <wpstk.h>
  3677.  
  3678. HEA      hea;         /* Handle to the extended attribute.                                                                           */
  3679. PULONG   pulEaType;   /* The address of a variable containing the type of the searched/found extended attribute.                     */
  3680. PSZ      pszValue;    /* The address of a buffer in into which the found value is returned.                                          */
  3681. PULONG   pulBuflen;   /* The address of a variable containing the length, in bytes, of the buffer described by pszValue.             */
  3682. APIRET   ulrc;        /* Return Code.                                                                                                */
  3683.  
  3684. ulrc = WtkFindFirstEaValue( hea, pulEaType, pszValue, pulBuflen);
  3685.  
  3686.  
  3687. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue - Parameter hea ΓòÉΓòÉΓòÉ
  3688.  
  3689. hea (HEA) - input 
  3690.     Handle to the extended attribute. 
  3691.  
  3692.  
  3693. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue - Parameter pulEaType ΓòÉΓòÉΓòÉ
  3694.  
  3695. pulEaType (PULONG) - input/output 
  3696.     The address of a variable containing the type of the searched/found 
  3697.     extended attribute. 
  3698.  
  3699.     All subsequent searches with WtkFindNextEaValue will use this type value. 
  3700.     Specify WTK_EAT_ANY on input to search for values of any type. 
  3701.  
  3702.  
  3703. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue - Parameter pszValue ΓòÉΓòÉΓòÉ
  3704.  
  3705. pszValue (PSZ) - output 
  3706.     The address of a buffer in into which the found value is returned. 
  3707.  
  3708.  
  3709. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue - Parameter pulBuflen ΓòÉΓòÉΓòÉ
  3710.  
  3711. pulBuflen (PULONG) - input/output 
  3712.     The address of a variable containing the length, in bytes, of the buffer 
  3713.     described by pszValue. 
  3714.  
  3715.     On return, this variable contains the length of the returned value. 
  3716.  
  3717.  
  3718. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue - Parameters ΓòÉΓòÉΓòÉ
  3719.  
  3720. hea (HEA) - input 
  3721.     Handle to the extended attribute. 
  3722.  
  3723.  pulEaType (PULONG) - input/output 
  3724.     The address of a variable containing the type of the searched/found 
  3725.     extended attribute. 
  3726.  
  3727.     All subsequent searches with WtkFindNextEaValue will use this type value. 
  3728.     Specify WTK_EAT_ANY on input to search for values of any type. 
  3729.  
  3730.  pszValue (PSZ) - output 
  3731.     The address of a buffer in into which the found value is returned. 
  3732.  
  3733.  pulBuflen (PULONG) - input/output 
  3734.     The address of a variable containing the length, in bytes, of the buffer 
  3735.     described by pszValue. 
  3736.  
  3737.     On return, this variable contains the length of the returned value. 
  3738.  
  3739.  ulrc (APIRET) - returns 
  3740.     Return Code. 
  3741.  
  3742.     WtkFindFirstEaValue returns one of the following return codes: 
  3743.  
  3744.     0         NO_ERROR 
  3745.     6         ERROR_INVALID_HANDLE 
  3746.     18        ERROR_NO_MORE_FILES 
  3747.     111       ERROR_BUFFER_OVERFLOW 
  3748.  
  3749.  
  3750. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue Return Value - ulrc ΓòÉΓòÉΓòÉ
  3751.  
  3752. ulrc (APIRET) - returns 
  3753.     Return Code. 
  3754.  
  3755.     WtkFindFirstEaValue returns one of the following return codes: 
  3756.  
  3757.     0         NO_ERROR 
  3758.     6         ERROR_INVALID_HANDLE 
  3759.     18        ERROR_NO_MORE_FILES 
  3760.     111       ERROR_BUFFER_OVERFLOW 
  3761.  
  3762.  
  3763. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue - Remarks ΓòÉΓòÉΓòÉ
  3764.  
  3765. Unlike DosFindFirst, this API does not allocate resources, that must be freed. 
  3766. The resources for handling the value of the extended attribute are rather 
  3767. allocated by WtkReadEa, which must be freeed by calling WtkCloseEa, when not 
  3768. longer needed. 
  3769.  
  3770. You can start searches with WtkFindFirstEaValue on a given extended attribute 
  3771. as often, as you like. The search will then always just start at the first 
  3772. value again. 
  3773.  
  3774.  
  3775. ΓòÉΓòÉΓòÉ <hidden> WtkFindFirstEaValue - Related functions ΓòÉΓòÉΓòÉ
  3776.  
  3777. Related Functions 
  3778.  
  3779. none 
  3780.  
  3781.  
  3782. ΓòÉΓòÉΓòÉ 8.30. WtkFindNextEaValue ΓòÉΓòÉΓòÉ
  3783.  
  3784. Select an item: 
  3785.  
  3786.      Syntax 
  3787.      Parameters 
  3788.      Returns 
  3789.      Remarks 
  3790.      Related Functions 
  3791.  
  3792.  
  3793. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue - Syntax ΓòÉΓòÉΓòÉ
  3794.  
  3795. This function scans a extended attribute previously scanned by 
  3796. WtkFindFirstEaValue for the next value(s) of a given type. 
  3797.  
  3798. #define INCL_WTKEAS
  3799. #include <wpstk.h>
  3800.  
  3801. HEA      hea;         /* Handle to the extended attribute.                                                                           */
  3802. PULONG   pulEaType;   /* The address of a variable containing the type of the found extended attribute.                              */
  3803. PSZ      pszValue;    /* The address of a buffer in into which the found value is returned.                                          */
  3804. PULONG   pulBuflen;   /* The address of a variable containing the length, in bytes, of the buffer described by pszValue.             */
  3805. APIRET   ulrc;        /* Return Code.                                                                                                */
  3806.  
  3807. ulrc = WtkFindNextEaValue( hea, pulEaType, pszValue, pulBuflen);
  3808.  
  3809.  
  3810. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue - Parameter hea ΓòÉΓòÉΓòÉ
  3811.  
  3812. hea (HEA) - input 
  3813.     Handle to the extended attribute. 
  3814.  
  3815.  
  3816. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue - Parameter pulEaType ΓòÉΓòÉΓòÉ
  3817.  
  3818. pulEaType (PULONG) - output 
  3819.     The address of a variable containing the type of the found extended 
  3820.     attribute. 
  3821.  
  3822.     All searches with WtkFindNextEaValue use the type being specified with 
  3823.     pulEaType on WtkFindFirstEaValue, 
  3824.  
  3825.  
  3826. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue - Parameter pszValue ΓòÉΓòÉΓòÉ
  3827.  
  3828. pszValue (PSZ) - output 
  3829.     The address of a buffer in into which the found value is returned. 
  3830.  
  3831.  
  3832. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue - Parameter pulBuflen ΓòÉΓòÉΓòÉ
  3833.  
  3834. pulBuflen (PULONG) - input/output 
  3835.     The address of a variable containing the length, in bytes, of the buffer 
  3836.     described by pszValue. 
  3837.  
  3838.     On return, this variable contains the length of the returned value. 
  3839.  
  3840.  
  3841. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue - Parameters ΓòÉΓòÉΓòÉ
  3842.  
  3843. hea (HEA) - input 
  3844.     Handle to the extended attribute. 
  3845.  
  3846.  pulEaType (PULONG) - output 
  3847.     The address of a variable containing the type of the found extended 
  3848.     attribute. 
  3849.  
  3850.     All searches with WtkFindNextEaValue use the type being specified with 
  3851.     pulEaType on WtkFindFirstEaValue, 
  3852.  
  3853.  pszValue (PSZ) - output 
  3854.     The address of a buffer in into which the found value is returned. 
  3855.  
  3856.  pulBuflen (PULONG) - input/output 
  3857.     The address of a variable containing the length, in bytes, of the buffer 
  3858.     described by pszValue. 
  3859.  
  3860.     On return, this variable contains the length of the returned value. 
  3861.  
  3862.  ulrc (APIRET) - returns 
  3863.     Return Code. 
  3864.  
  3865.     WtkFindNextEaValue returns one of the following return codes: 
  3866.  
  3867.     0         NO_ERROR 
  3868.     1         ERROR_INVALID_FUNCTION 
  3869.     6         ERROR_INVALID_HANDLE 
  3870.     18        ERROR_NO_MORE_FILES 
  3871.     87        ERROR_INVALID_PARAMETER 
  3872.     111       ERROR_BUFFER_OVERFLOW 
  3873.  
  3874.  
  3875. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue Return Value - ulrc ΓòÉΓòÉΓòÉ
  3876.  
  3877. ulrc (APIRET) - returns 
  3878.     Return Code. 
  3879.  
  3880.     WtkFindNextEaValue returns one of the following return codes: 
  3881.  
  3882.     0         NO_ERROR 
  3883.     1         ERROR_INVALID_FUNCTION 
  3884.     6         ERROR_INVALID_HANDLE 
  3885.     18        ERROR_NO_MORE_FILES 
  3886.     87        ERROR_INVALID_PARAMETER 
  3887.     111       ERROR_BUFFER_OVERFLOW 
  3888.  
  3889.  
  3890. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue - Remarks ΓòÉΓòÉΓòÉ
  3891.  
  3892. If the extended attribute was not scanned with WtkFindFirstEaValue before using 
  3893. WtkFindNextEaValue, ERROR_INVALID_FUNCTION is returned. 
  3894.  
  3895. If no more value according to the type specified on WtkFindFirstEaValue can be 
  3896. found, ERROR_NO_MORE_FILES is returned. 
  3897.  
  3898.  
  3899. ΓòÉΓòÉΓòÉ <hidden> WtkFindNextEaValue - Related functions ΓòÉΓòÉΓòÉ
  3900.  
  3901. Related Functions 
  3902.  
  3903. none 
  3904.  
  3905.  
  3906. ΓòÉΓòÉΓòÉ 8.31. WtkFreeMmf ΓòÉΓòÉΓòÉ
  3907.  
  3908. Select an item: 
  3909.  
  3910.      Syntax 
  3911.      Parameters 
  3912.      Returns 
  3913.      Remarks 
  3914.      Related Functions 
  3915.  
  3916.  
  3917. ΓòÉΓòÉΓòÉ <hidden> WtkFreeMmf - Syntax ΓòÉΓòÉΓòÉ
  3918.  
  3919. This function frees a dynamic memory buffer. 
  3920.  
  3921. #define INCL_WTKMMF
  3922. #include <wpstk.h>
  3923.  
  3924. HMMF     hmmf;     /* Handle to the MMF manager.                           */
  3925. PVOID    pvData;   /* Pointer to the allocated address space to be freed.  */
  3926. APIRET   ulrc;     /* Return Code.                                         */
  3927.  
  3928. ulrc = WtkFreeMmf( hmmf, pvData);
  3929.  
  3930.  
  3931. ΓòÉΓòÉΓòÉ <hidden> WtkFreeMmf - Parameter hmmf ΓòÉΓòÉΓòÉ
  3932.  
  3933. hmmf (HMMF) - input 
  3934.     Handle to the MMF manager. 
  3935.  
  3936.  
  3937. ΓòÉΓòÉΓòÉ <hidden> WtkFreeMmf - Parameter pvData ΓòÉΓòÉΓòÉ
  3938.  
  3939. pvData (PVOID) - input 
  3940.     Pointer to the allocated address space to be freed. 
  3941.  
  3942.  
  3943. ΓòÉΓòÉΓòÉ <hidden> WtkFreeMmf - Parameters ΓòÉΓòÉΓòÉ
  3944.  
  3945. hmmf (HMMF) - input 
  3946.     Handle to the MMF manager. 
  3947.  
  3948.  pvData (PVOID) - input 
  3949.     Pointer to the allocated address space to be freed. 
  3950.  
  3951.  ulrc (APIRET) - returns 
  3952.     Return Code. 
  3953.  
  3954.     WtkFreeMmf returns one of the following return codes: 
  3955.  
  3956.     0         NO_ERROR 
  3957.     87        ERROR_INVALID_HANDLE 
  3958.     87        ERROR_INVALID_PARAMETER 
  3959.  
  3960.     or return codes of the following functions 
  3961.  
  3962.         DosFreeMem 
  3963.  
  3964.  
  3965. ΓòÉΓòÉΓòÉ <hidden> WtkFreeMmf Return Value - ulrc ΓòÉΓòÉΓòÉ
  3966.  
  3967. ulrc (APIRET) - returns 
  3968.     Return Code. 
  3969.  
  3970.     WtkFreeMmf returns one of the following return codes: 
  3971.  
  3972.     0         NO_ERROR 
  3973.     87        ERROR_INVALID_HANDLE 
  3974.     87        ERROR_INVALID_PARAMETER 
  3975.  
  3976.     or return codes of the following functions 
  3977.  
  3978.         DosFreeMem 
  3979.  
  3980.  
  3981. ΓòÉΓòÉΓòÉ <hidden> WtkFreeMmf - Remarks ΓòÉΓòÉΓòÉ
  3982.  
  3983. Calling WtkFreeMmf will not save unsaved data. For that WtkFreeMmf. must be 
  3984. called. 
  3985.  
  3986.  
  3987. ΓòÉΓòÉΓòÉ <hidden> WtkFreeMmf - Related functions ΓòÉΓòÉΓòÉ
  3988.  
  3989. Related Functions 
  3990.  
  3991. none 
  3992.  
  3993.  
  3994. ΓòÉΓòÉΓòÉ 8.32. WtkGetModuleHandle ΓòÉΓòÉΓòÉ
  3995.  
  3996. Select an item: 
  3997.  
  3998.      Syntax 
  3999.      Parameters 
  4000.      Returns 
  4001.      Remarks 
  4002.      Related Functions 
  4003.  
  4004.  
  4005. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleHandle - Syntax ΓòÉΓòÉΓòÉ
  4006.  
  4007. This function returns the handle of the module containing a given function. 
  4008.  
  4009. #define INCL_WTKUTLMODULE
  4010. #include <wpstk.h>
  4011.  
  4012. PFN       pfn;       /* Address of the function.                                                                          */
  4013. HMODULE   hmodule;   /* Handle of the module containing the function or NULLHANDLE, if the handle could not be obtained.  */
  4014.  
  4015. hmodule = WtkGetModuleHandle( pfn);
  4016.  
  4017.  
  4018. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleHandle - Parameter pfn ΓòÉΓòÉΓòÉ
  4019.  
  4020. pfn (PFN) - input 
  4021.     Address of the function. 
  4022.  
  4023.  
  4024. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleHandle - Parameters ΓòÉΓòÉΓòÉ
  4025.  
  4026. pfn (PFN) - input 
  4027.     Address of the function. 
  4028.  
  4029.  hmodule (HMODULE) - returns 
  4030.     Handle of the module containing the function or NULLHANDLE, if the handle 
  4031.     could not be obtained. 
  4032.  
  4033.  
  4034. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleHandle Return Value - hmodule ΓòÉΓòÉΓòÉ
  4035.  
  4036. hmodule (HMODULE) - returns 
  4037.     Handle of the module containing the function or NULLHANDLE, if the handle 
  4038.     could not be obtained. 
  4039.  
  4040.  
  4041. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleHandle - Remarks ΓòÉΓòÉΓòÉ
  4042.  
  4043. This function calls WtkGetModuleInfo in order to obtain the module handle. 
  4044.  
  4045.  
  4046. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleHandle - Related functions ΓòÉΓòÉΓòÉ
  4047.  
  4048. Related Functions 
  4049.  
  4050. none 
  4051.  
  4052.  
  4053. ΓòÉΓòÉΓòÉ 8.33. WtkGetModuleInfo ΓòÉΓòÉΓòÉ
  4054.  
  4055. Select an item: 
  4056.  
  4057.      Syntax 
  4058.      Parameters 
  4059.      Returns 
  4060.      Remarks 
  4061.      Related Functions 
  4062.  
  4063.  
  4064. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo - Syntax ΓòÉΓòÉΓòÉ
  4065.  
  4066. This function returns information about the module containing a given function. 
  4067.  
  4068. #define INCL_WTKUTLMODULE
  4069. #include <wpstk.h>
  4070.  
  4071. PFN        pfn;         /* Address of the function.                                                             */
  4072. PHMODULE   phmod;       /* Address of the module handle, or NULL, if this infortation is not required.          */
  4073. PSZ        pszBuffer;   /* Address of a buffer, where the full qualified name of the module is being returned.  */
  4074. ULONG      ulBuflen;    /* The length, in bytes, of the buffer described by pszBuffer.                          */
  4075. APIRET     ulrc;        /* Return Code.                                                                         */
  4076.  
  4077. ulrc = WtkGetModuleInfo( pfn, phmod, pszBuffer, ulBuflen);
  4078.  
  4079.  
  4080. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo - Parameter pfn ΓòÉΓòÉΓòÉ
  4081.  
  4082. pfn (PFN) - input 
  4083.     Address of the function. 
  4084.  
  4085.  
  4086. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo - Parameter phmod ΓòÉΓòÉΓòÉ
  4087.  
  4088. phmod (PHMODULE) - output 
  4089.     Address of the module handle, or NULL, if this infortation is not required. 
  4090.  
  4091.  
  4092. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  4093.  
  4094. pszBuffer (PSZ) - output 
  4095.     Address of a buffer, where the full qualified name of the module is being 
  4096.     returned. 
  4097.  
  4098.  
  4099. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  4100.  
  4101. ulBuflen (ULONG) - input 
  4102.     The length, in bytes, of the buffer described by pszBuffer. 
  4103.  
  4104.  
  4105. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo - Parameters ΓòÉΓòÉΓòÉ
  4106.  
  4107. pfn (PFN) - input 
  4108.     Address of the function. 
  4109.  
  4110.  phmod (PHMODULE) - output 
  4111.     Address of the module handle, or NULL, if this infortation is not required. 
  4112.  
  4113.  pszBuffer (PSZ) - output 
  4114.     Address of a buffer, where the full qualified name of the module is being 
  4115.     returned. 
  4116.  
  4117.  ulBuflen (ULONG) - input 
  4118.     The length, in bytes, of the buffer described by pszBuffer. 
  4119.  
  4120.  ulrc (APIRET) - returns 
  4121.     Return Code. 
  4122.  
  4123.     WtkGetModuleInfo returns one of the following return codes: 
  4124.  
  4125.     0         NO_ERROR 
  4126.     87        ERROR_INVALID_PARAMETER 
  4127.     111       ERROR_BUFFER_OVERFLOW 
  4128.  
  4129.     or return codes of the following functions 
  4130.  
  4131.         DosQueryModuleName 
  4132.  
  4133.  
  4134. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo Return Value - ulrc ΓòÉΓòÉΓòÉ
  4135.  
  4136. ulrc (APIRET) - returns 
  4137.     Return Code. 
  4138.  
  4139.     WtkGetModuleInfo returns one of the following return codes: 
  4140.  
  4141.     0         NO_ERROR 
  4142.     87        ERROR_INVALID_PARAMETER 
  4143.     111       ERROR_BUFFER_OVERFLOW 
  4144.  
  4145.     or return codes of the following functions 
  4146.  
  4147.         DosQueryModuleName 
  4148.  
  4149.  
  4150. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo - Remarks ΓòÉΓòÉΓòÉ
  4151.  
  4152. WtkGetModuleInfo uses the undocumented function DosQueryModFromEIP: 
  4153.  
  4154. APIRET APIENTRY
  4155. DosQueryModFromEIP (HMODULE *phModule, ULONG *pulObjectNumber,
  4156.                     ULONG ulBufferLength, PCHAR pchBuffer,
  4157.                     ULONG *pulOffset, PVOID pvAddress);
  4158.  
  4159.  
  4160. ΓòÉΓòÉΓòÉ <hidden> WtkGetModuleInfo - Related functions ΓòÉΓòÉΓòÉ
  4161.  
  4162. Related Functions 
  4163.  
  4164. none 
  4165.  
  4166.  
  4167. ΓòÉΓòÉΓòÉ 8.34. WtkGetNextDirectory ΓòÉΓòÉΓòÉ
  4168.  
  4169. Select an item: 
  4170.  
  4171.      Syntax 
  4172.      Parameters 
  4173.      Returns 
  4174.      Remarks 
  4175.      Related Functions 
  4176.  
  4177.  
  4178. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory - Syntax ΓòÉΓòÉΓòÉ
  4179.  
  4180. This function provides a simple way to search directories with one API call 
  4181. instead of using DosFindFirst / DosFindNext / DosFindClose. 
  4182.  
  4183. #define INCL_WTKUTLFILE
  4184. #include <wpstk.h>
  4185.  
  4186. PSZ      pszFileMask;        /* Address of the ASCIIZ file mask of the files to be searched.                          */
  4187. PHDIR    phdir;              /* Address of the directory handle associated with this request.                         */
  4188. PSZ      pszNextDirectory;   /* The address of a buffer, into which the name of the recently found file is returned.  */
  4189. ULONG    ulBuflen;           /* The length, in bytes, of the buffer described by pszNextDirectory.                    */
  4190. APIRET   ulrc;               /* Return Code.                                                                          */
  4191.  
  4192. ulrc = WtkGetNextDirectory( pszFileMask, phdir, pszNextDirectory, ulBuflen);
  4193.  
  4194.  
  4195. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory - Parameter pszFileMask ΓòÉΓòÉΓòÉ
  4196.  
  4197. pszFileMask (PSZ) - input 
  4198.     Address of the ASCIIZ file mask of the files to be searched. 
  4199.  
  4200.  
  4201. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory - Parameter phdir ΓòÉΓòÉΓòÉ
  4202.  
  4203. phdir (PHDIR) - input/output 
  4204.     Address of the directory handle associated with this request. 
  4205.  
  4206.     Before calling WtkGetNextDirectory for the first time to search a given 
  4207.     file mask, the directory handle must be set to HDIR_CREATE. On subsequent 
  4208.     calls, the directory handle must not be modified. 
  4209.  
  4210.     IMPORTANT: 
  4211.  
  4212.         The directory handle will be automatically closed, when 
  4213.          WtkGetNextDirectory is being called, until it returns 
  4214.          ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use 
  4215.          DosFindClose to close the directory handle. 
  4216.  
  4217.  
  4218. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory - Parameter pszNextDirectory ΓòÉΓòÉΓòÉ
  4219.  
  4220. pszNextDirectory (PSZ) - output 
  4221.     The address of a buffer, into which the name of the recently found file is 
  4222.     returned. 
  4223.  
  4224.  
  4225. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  4226.  
  4227. ulBuflen (ULONG) - input 
  4228.     The length, in bytes, of the buffer described by pszNextDirectory. 
  4229.  
  4230.  
  4231. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory - Parameters ΓòÉΓòÉΓòÉ
  4232.  
  4233. pszFileMask (PSZ) - input 
  4234.     Address of the ASCIIZ file mask of the files to be searched. 
  4235.  
  4236.  phdir (PHDIR) - input/output 
  4237.     Address of the directory handle associated with this request. 
  4238.  
  4239.     Before calling WtkGetNextDirectory for the first time to search a given 
  4240.     file mask, the directory handle must be set to HDIR_CREATE. On subsequent 
  4241.     calls, the directory handle must not be modified. 
  4242.  
  4243.     IMPORTANT: 
  4244.  
  4245.         The directory handle will be automatically closed, when 
  4246.          WtkGetNextDirectory is being called, until it returns 
  4247.          ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use 
  4248.          DosFindClose to close the directory handle. 
  4249.  
  4250.  pszNextDirectory (PSZ) - output 
  4251.     The address of a buffer, into which the name of the recently found file is 
  4252.     returned. 
  4253.  
  4254.  ulBuflen (ULONG) - input 
  4255.     The length, in bytes, of the buffer described by pszNextDirectory. 
  4256.  
  4257.  ulrc (APIRET) - returns 
  4258.     Return Code. 
  4259.  
  4260.     WtkGetNextDirectory returns one of the following return codes: 
  4261.  
  4262.     0         NO_ERROR 
  4263.     87        ERROR_INVALID_PARAMETER 
  4264.  
  4265.     or return codes of the following functions 
  4266.  
  4267.         DosFindFirst 
  4268.         DosFindNext 
  4269.  
  4270.  
  4271. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory Return Value - ulrc ΓòÉΓòÉΓòÉ
  4272.  
  4273. ulrc (APIRET) - returns 
  4274.     Return Code. 
  4275.  
  4276.     WtkGetNextDirectory returns one of the following return codes: 
  4277.  
  4278.     0         NO_ERROR 
  4279.     87        ERROR_INVALID_PARAMETER 
  4280.  
  4281.     or return codes of the following functions 
  4282.  
  4283.         DosFindFirst 
  4284.         DosFindNext 
  4285.  
  4286.  
  4287. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory - Remarks ΓòÉΓòÉΓòÉ
  4288.  
  4289. Before calling WtkGetNextDirectory for the first time to search a given file 
  4290. mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, the 
  4291. directory handle must not be modified. 
  4292.  
  4293. IMPORTANT: 
  4294.  
  4295.      The directory handle will be automatically closed, when 
  4296.       WtkGetNextDirectory is being called, until it returns 
  4297.       ERROR_NO_MORE_FILES. Otherwise the caller must explicitely use 
  4298.       DosFindClose to close the directory handle. 
  4299.  
  4300.  
  4301. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextDirectory - Related functions ΓòÉΓòÉΓòÉ
  4302.  
  4303. Related Functions 
  4304.  
  4305. none 
  4306.  
  4307.  
  4308. ΓòÉΓòÉΓòÉ 8.35. WtkGetNextEaValue ΓòÉΓòÉΓòÉ
  4309.  
  4310. Select an item: 
  4311.  
  4312.      Syntax 
  4313.      Parameters 
  4314.      Returns 
  4315.      Remarks 
  4316.      Related Functions 
  4317.  
  4318.  
  4319. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Syntax ΓòÉΓòÉΓòÉ
  4320.  
  4321. This function reads the value of an extended attribute of a given file or 
  4322. directory. It provides the use of WtkReadEa / WtkFind*EaValue / WtkCloseEa in 
  4323. one API by calling it several times, until ERROR_NO_MORE_FILES is returned. 
  4324.  
  4325. #define INCL_WTKEAS
  4326. #include <wpstk.h>
  4327.  
  4328. PSZ      pszName;     /* Address of the ASCIIZ path name of the file or directory.                                                   */
  4329. PSZ      pszEaName;   /* Address of the ASCIIZ name of the extended attribute.                                                       */
  4330. PULONG   pulEaType;   /* The address of a variable containing the type of the searched/found extended attribute.                     */
  4331. PHEA     phea;        /* The address of a variable containing the handle to the extended attribute.                                  */
  4332. PSZ      pszValue;    /* The address of a buffer in into which the found value is returned.                                          */
  4333. PULONG   pulBuflen;   /* The address of a variable containing the length, in bytes, of the buffer described by pszValue.             */
  4334. APIRET   ulrc;        /* Return Code.                                                                                                */
  4335.  
  4336. ulrc = WtkGetNextEaValue( pszName, pszEaName, pulEaType, phea, pszValue, pulBuflen);
  4337.  
  4338.  
  4339. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Parameter pszName ΓòÉΓòÉΓòÉ
  4340.  
  4341. pszName (PSZ) - input 
  4342.     Address of the ASCIIZ path name of the file or directory. 
  4343.  
  4344.     The path name may contain ?: for the drive in order to open the file or 
  4345.     directory on the boot drive. 
  4346.  
  4347.     The name may not include wildcards. 
  4348.  
  4349.  
  4350. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Parameter pszEaName ΓòÉΓòÉΓòÉ
  4351.  
  4352. pszEaName (PSZ) - input 
  4353.     Address of the ASCIIZ name of the extended attribute. 
  4354.  
  4355.  
  4356. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Parameter pulEaType ΓòÉΓòÉΓòÉ
  4357.  
  4358. pulEaType (PULONG) - input/output 
  4359.     The address of a variable containing the type of the searched/found 
  4360.     extended attribute. 
  4361.  
  4362.     Specify WTK_EAT_ANY on input to search for values of any type. 
  4363.  
  4364.  
  4365. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Parameter phea ΓòÉΓòÉΓòÉ
  4366.  
  4367. phea (PHEA) - input/output 
  4368.     The address of a variable containing the handle to the extended attribute. 
  4369.  
  4370.     On the first call to WtkGetNextEaValue, set this variable to HEA_CREATE. On 
  4371.     return, *phea will contain the correct handle value for subsequent calls. 
  4372.  
  4373.  
  4374. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Parameter pszValue ΓòÉΓòÉΓòÉ
  4375.  
  4376. pszValue (PSZ) - output 
  4377.     The address of a buffer in into which the found value is returned. 
  4378.  
  4379.  
  4380. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Parameter pulBuflen ΓòÉΓòÉΓòÉ
  4381.  
  4382. pulBuflen (PULONG) - input/output 
  4383.     The address of a variable containing the length, in bytes, of the buffer 
  4384.     described by pszValue. 
  4385.  
  4386.     On return, this variable contains the length of the returned value. 
  4387.  
  4388.  
  4389. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Parameters ΓòÉΓòÉΓòÉ
  4390.  
  4391. pszName (PSZ) - input 
  4392.     Address of the ASCIIZ path name of the file or directory. 
  4393.  
  4394.     The path name may contain ?: for the drive in order to open the file or 
  4395.     directory on the boot drive. 
  4396.  
  4397.     The name may not include wildcards. 
  4398.  
  4399.  pszEaName (PSZ) - input 
  4400.     Address of the ASCIIZ name of the extended attribute. 
  4401.  
  4402.  pulEaType (PULONG) - input/output 
  4403.     The address of a variable containing the type of the searched/found 
  4404.     extended attribute. 
  4405.  
  4406.     Specify WTK_EAT_ANY on input to search for values of any type. 
  4407.  
  4408.  phea (PHEA) - input/output 
  4409.     The address of a variable containing the handle to the extended attribute. 
  4410.  
  4411.     On the first call to WtkGetNextEaValue, set this variable to HEA_CREATE. On 
  4412.     return, *phea will contain the correct handle value for subsequent calls. 
  4413.  
  4414.  pszValue (PSZ) - output 
  4415.     The address of a buffer in into which the found value is returned. 
  4416.  
  4417.  pulBuflen (PULONG) - input/output 
  4418.     The address of a variable containing the length, in bytes, of the buffer 
  4419.     described by pszValue. 
  4420.  
  4421.     On return, this variable contains the length of the returned value. 
  4422.  
  4423.  ulrc (APIRET) - returns 
  4424.     Return Code. 
  4425.  
  4426.     WtkGetNextEaValue returns one of the following return codes: 
  4427.  
  4428.     0         NO_ERROR 
  4429.     8         ERROR_NOT_ENOUGH_MEMORY 
  4430.     18        ERROR_NO_MORE_FILES 
  4431.     87        ERROR_INVALID_PARAMETER 
  4432.  
  4433.     or return codes of the following functions 
  4434.  
  4435.         DosQueryPathInfo 
  4436.  
  4437.  
  4438. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue Return Value - ulrc ΓòÉΓòÉΓòÉ
  4439.  
  4440. ulrc (APIRET) - returns 
  4441.     Return Code. 
  4442.  
  4443.     WtkGetNextEaValue returns one of the following return codes: 
  4444.  
  4445.     0         NO_ERROR 
  4446.     8         ERROR_NOT_ENOUGH_MEMORY 
  4447.     18        ERROR_NO_MORE_FILES 
  4448.     87        ERROR_INVALID_PARAMETER 
  4449.  
  4450.     or return codes of the following functions 
  4451.  
  4452.         DosQueryPathInfo 
  4453.  
  4454.  
  4455. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Remarks ΓòÉΓòÉΓòÉ
  4456.  
  4457. This function supports boot drive recognition. Specify ?: for the drive in 
  4458. order to open the file or directory on the boot drive. 
  4459.  
  4460. This function is meant to provide you with easy handling of extended 
  4461. attributes. Instead of calling WtkReadEa / WtkFind*EaValue / WtkCloseEa, you 
  4462. can retrieve all values of an extended attribute by just calling 
  4463. WtkGetNextEaValue, until it returns ERROR_NO_MORE_FILES. 
  4464.  
  4465. This function allocates resources for handling the value of the given extended 
  4466. attribute by callig WtkReadEa. They must either be freed by 
  4467.  
  4468.      calling WtkGetNextEaValue, until it is returning ERROR_NO_MORE_FILES. 
  4469.       This will call WtkCloseEa implicitely. 
  4470.      calling WtkClose 
  4471.  
  4472.  
  4473. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextEaValue - Related functions ΓòÉΓòÉΓòÉ
  4474.  
  4475. Related Functions 
  4476.  
  4477. none 
  4478.  
  4479.  
  4480. ΓòÉΓòÉΓòÉ 8.36. WtkGetNextFile ΓòÉΓòÉΓòÉ
  4481.  
  4482. Select an item: 
  4483.  
  4484.      Syntax 
  4485.      Parameters 
  4486.      Returns 
  4487.      Remarks 
  4488.      Related Functions 
  4489.  
  4490.  
  4491. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile - Syntax ΓòÉΓòÉΓòÉ
  4492.  
  4493. This function provides a simple way to search files with one API call instead 
  4494. of using DosFindFirst / DosFindNext / DosFindClose. 
  4495.  
  4496. #define INCL_WTKUTLFILE
  4497. #include <wpstk.h>
  4498.  
  4499. PSZ      pszFileMask;   /* Address of the ASCIIZ file mask of the files to be searched.                          */
  4500. PHDIR    phdir;         /* Address of the directory handle associated with this request.                         */
  4501. PSZ      pszNextFile;   /* The address of a buffer, into which the name of the recently found file is returned.  */
  4502. ULONG    ulBuflen;      /* The length, in bytes, of the buffer described by pszNextFile.                         */
  4503. APIRET   ulrc;          /* Return Code.                                                                          */
  4504.  
  4505. ulrc = WtkGetNextFile( pszFileMask, phdir, pszNextFile, ulBuflen);
  4506.  
  4507.  
  4508. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile - Parameter pszFileMask ΓòÉΓòÉΓòÉ
  4509.  
  4510. pszFileMask (PSZ) - input 
  4511.     Address of the ASCIIZ file mask of the files to be searched. 
  4512.  
  4513.  
  4514. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile - Parameter phdir ΓòÉΓòÉΓòÉ
  4515.  
  4516. phdir (PHDIR) - input/output 
  4517.     Address of the directory handle associated with this request. 
  4518.  
  4519.     Before calling WtkGetNextFile for the first time to search a given file 
  4520.     mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, 
  4521.     the directory handle must not be modified. 
  4522.  
  4523.     IMPORTANT: 
  4524.  
  4525.         The directory handle will be automatically closed, when WtkGetNextFile 
  4526.          is being called, until it returns ERROR_NO_MORE_FILES. Otherwise the 
  4527.          caller must explicitely use DosFindClose to close the directory 
  4528.          handle. 
  4529.  
  4530.  
  4531. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile - Parameter pszNextFile ΓòÉΓòÉΓòÉ
  4532.  
  4533. pszNextFile (PSZ) - output 
  4534.     The address of a buffer, into which the name of the recently found file is 
  4535.     returned. 
  4536.  
  4537.  
  4538. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  4539.  
  4540. ulBuflen (ULONG) - input 
  4541.     The length, in bytes, of the buffer described by pszNextFile. 
  4542.  
  4543.  
  4544. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile - Parameters ΓòÉΓòÉΓòÉ
  4545.  
  4546. pszFileMask (PSZ) - input 
  4547.     Address of the ASCIIZ file mask of the files to be searched. 
  4548.  
  4549.  phdir (PHDIR) - input/output 
  4550.     Address of the directory handle associated with this request. 
  4551.  
  4552.     Before calling WtkGetNextFile for the first time to search a given file 
  4553.     mask, the directory handle must be set to HDIR_CREATE. On subsequent calls, 
  4554.     the directory handle must not be modified. 
  4555.  
  4556.     IMPORTANT: 
  4557.  
  4558.         The directory handle will be automatically closed, when WtkGetNextFile 
  4559.          is being called, until it returns ERROR_NO_MORE_FILES. Otherwise the 
  4560.          caller must explicitely use DosFindClose to close the directory 
  4561.          handle. 
  4562.  
  4563.  pszNextFile (PSZ) - output 
  4564.     The address of a buffer, into which the name of the recently found file is 
  4565.     returned. 
  4566.  
  4567.  ulBuflen (ULONG) - input 
  4568.     The length, in bytes, of the buffer described by pszNextFile. 
  4569.  
  4570.  ulrc (APIRET) - returns 
  4571.     Return Code. 
  4572.  
  4573.     WtkGetNextFile returns one of the following return codes: 
  4574.  
  4575.     0         NO_ERROR 
  4576.     87        ERROR_INVALID_PARAMETER 
  4577.  
  4578.     or return codes of the following functions 
  4579.  
  4580.         DosFindFirst 
  4581.         DosFindNext 
  4582.  
  4583.  
  4584. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile Return Value - ulrc ΓòÉΓòÉΓòÉ
  4585.  
  4586. ulrc (APIRET) - returns 
  4587.     Return Code. 
  4588.  
  4589.     WtkGetNextFile returns one of the following return codes: 
  4590.  
  4591.     0         NO_ERROR 
  4592.     87        ERROR_INVALID_PARAMETER 
  4593.  
  4594.     or return codes of the following functions 
  4595.  
  4596.         DosFindFirst 
  4597.         DosFindNext 
  4598.  
  4599.  
  4600. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile - Remarks ΓòÉΓòÉΓòÉ
  4601.  
  4602. Before calling WtkGetNextFile for the first time to search a given file mask, 
  4603. the directory handle must be set to HDIR_CREATE. On subsequent calls, the 
  4604. directory handle must not be modified. 
  4605.  
  4606. IMPORTANT: 
  4607.  
  4608.      The directory handle will be automatically closed, when WtkGetNextFile is 
  4609.       being called, until it returns ERROR_NO_MORE_FILES. Otherwise the caller 
  4610.       must explicitely use DosFindClose to close the directory handle. 
  4611.  
  4612.  
  4613. ΓòÉΓòÉΓòÉ <hidden> WtkGetNextFile - Related functions ΓòÉΓòÉΓòÉ
  4614.  
  4615. Related Functions 
  4616.  
  4617. none 
  4618.  
  4619.  
  4620. ΓòÉΓòÉΓòÉ 8.37. WtkGetPackageFilename ΓòÉΓòÉΓòÉ
  4621.  
  4622. Select an item: 
  4623.  
  4624.      Syntax 
  4625.      Parameters 
  4626.      Returns 
  4627.      Remarks 
  4628.      Related Functions 
  4629.  
  4630.  
  4631. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Syntax ΓòÉΓòÉΓòÉ
  4632.  
  4633. This function determines a fully qualified pathname for a given filename or 
  4634. file extension corresponding to the name of the module / application executable 
  4635. containing a given function. 
  4636.  
  4637. #define INCL_WTKUTLMODULE
  4638. #include <wpstk.h>
  4639.  
  4640. PFN      pfn;           /* Address of the function.                                                   */
  4641. PSZ      pszSubdir;     /* Address of the ASCIIZ subdirectory name.                                   */
  4642. PSZ      pszFilename;   /* Address of the ASCIIZ file name.                                           */
  4643. PSZ      pszFileext;    /* Address of the ASCIIZ file extension without leading dot.                  */
  4644. PSZ      pszBuffer;     /* Address of a buffer, where the full qualified filename is being returned.  */
  4645. ULONG    ulBuflen;      /* The length, in bytes, of the buffer described by pszBuffer.                */
  4646. APIRET   ulrc;          /* Return Code.                                                               */
  4647.  
  4648. ulrc = WtkGetPackageFilename( pfn, pszSubdir, pszFilename, pszFileext, pszBuffer, ulBuflen);
  4649.  
  4650.  
  4651. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Parameter pfn ΓòÉΓòÉΓòÉ
  4652.  
  4653. pfn (PFN) - input 
  4654.     Address of the function. 
  4655.  
  4656.  
  4657. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Parameter pszSubdir ΓòÉΓòÉΓòÉ
  4658.  
  4659. pszSubdir (PSZ) - input 
  4660.     Address of the ASCIIZ subdirectory name. 
  4661.  
  4662.     If the required filename should point to a subdirectory, of where the 
  4663.     executable resides, specify it here. Otherwise, leave this parameter NULL. 
  4664.  
  4665.  
  4666. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Parameter pszFilename ΓòÉΓòÉΓòÉ
  4667.  
  4668. pszFilename (PSZ) - input 
  4669.     Address of the ASCIIZ file name. 
  4670.  
  4671.     If the filename should have a different name than the executable, specify 
  4672.     it here. Otherwise, leave this parameter NULL. 
  4673.  
  4674.     You can specify an extension either here or in pszFileExt. 
  4675.  
  4676.  
  4677. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Parameter pszFileext ΓòÉΓòÉΓòÉ
  4678.  
  4679. pszFileext (PSZ) - input 
  4680.     Address of the ASCIIZ file extension without leading dot. 
  4681.  
  4682.     If the filename should have a different extension than the executable, 
  4683.     specify it here. Otherwise, leave this parameter NULL. 
  4684.  
  4685.  
  4686. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  4687.  
  4688. pszBuffer (PSZ) - output 
  4689.     Address of a buffer, where the full qualified filename is being returned. 
  4690.  
  4691.  
  4692. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  4693.  
  4694. ulBuflen (ULONG) - input 
  4695.     The length, in bytes, of the buffer described by pszBuffer. 
  4696.  
  4697.  
  4698. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Parameters ΓòÉΓòÉΓòÉ
  4699.  
  4700. pfn (PFN) - input 
  4701.     Address of the function. 
  4702.  
  4703.  pszSubdir (PSZ) - input 
  4704.     Address of the ASCIIZ subdirectory name. 
  4705.  
  4706.     If the required filename should point to a subdirectory, of where the 
  4707.     executable resides, specify it here. Otherwise, leave this parameter NULL. 
  4708.  
  4709.  pszFilename (PSZ) - input 
  4710.     Address of the ASCIIZ file name. 
  4711.  
  4712.     If the filename should have a different name than the executable, specify 
  4713.     it here. Otherwise, leave this parameter NULL. 
  4714.  
  4715.     You can specify an extension either here or in pszFileExt. 
  4716.  
  4717.  pszFileext (PSZ) - input 
  4718.     Address of the ASCIIZ file extension without leading dot. 
  4719.  
  4720.     If the filename should have a different extension than the executable, 
  4721.     specify it here. Otherwise, leave this parameter NULL. 
  4722.  
  4723.  pszBuffer (PSZ) - output 
  4724.     Address of a buffer, where the full qualified filename is being returned. 
  4725.  
  4726.  ulBuflen (ULONG) - input 
  4727.     The length, in bytes, of the buffer described by pszBuffer. 
  4728.  
  4729.  ulrc (APIRET) - returns 
  4730.     Return Code. 
  4731.  
  4732.     WtkGetPackageFilename returns one of the following return codes: 
  4733.  
  4734.     0         NO_ERROR 
  4735.     87        ERROR_INVALID_PARAMETER 
  4736.     111       ERROR_BUFFER_OVERFLOW 
  4737.  
  4738.     or return codes of the following functions 
  4739.  
  4740.         DosQueryModuleName 
  4741.  
  4742.  
  4743. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename Return Value - ulrc ΓòÉΓòÉΓòÉ
  4744.  
  4745. ulrc (APIRET) - returns 
  4746.     Return Code. 
  4747.  
  4748.     WtkGetPackageFilename returns one of the following return codes: 
  4749.  
  4750.     0         NO_ERROR 
  4751.     87        ERROR_INVALID_PARAMETER 
  4752.     111       ERROR_BUFFER_OVERFLOW 
  4753.  
  4754.     or return codes of the following functions 
  4755.  
  4756.         DosQueryModuleName 
  4757.  
  4758.  
  4759. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Remarks ΓòÉΓòÉΓòÉ
  4760.  
  4761. This function is mostly used to determine names of INI files etc. residing e.g. 
  4762. in the same directory as the executable or in a subdirectory, of where the 
  4763. executable resides. 
  4764.  
  4765.  
  4766. ΓòÉΓòÉΓòÉ <hidden> WtkGetPackageFilename - Related functions ΓòÉΓòÉΓòÉ
  4767.  
  4768. Related Functions 
  4769.  
  4770. none 
  4771.  
  4772.  
  4773. ΓòÉΓòÉΓòÉ 8.38. WtkGetTextMessage ΓòÉΓòÉΓòÉ
  4774.  
  4775. Select an item: 
  4776.  
  4777.      Syntax 
  4778.      Parameters 
  4779.      Returns 
  4780.      Remarks 
  4781.      Related Functions 
  4782.  
  4783.  
  4784. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Syntax ΓòÉΓòÉΓòÉ
  4785.  
  4786. This function retrieves a message fro a text message file. It is quite similar 
  4787. to the DosGetMessage control program function, but with some important 
  4788. differences 
  4789.  
  4790. #define INCL_WTKTMF
  4791. #include <wpstk.h>
  4792.  
  4793. PCHAR   *pTable;           /* Pointer table.                                                                           */
  4794. ULONG    cTable;           /* Number of variable insertion text strings.                                               */
  4795. PBYTE    pbBuffer;         /* The address of the caller's buffer area where the system returns the requested message.  */
  4796. ULONG    cbBuffer;         /* The length, in bytes, of the caller's buffer area.                                       */
  4797. PSZ      pszMessageName;   /* Address of the ASCIIZ name of the message                                                */
  4798. PSZ      pszFile;          /* Address of the ASCIIZ name of the text message file.                                     */
  4799. PULONG   pcbMsg;           /* The address of a variable containing the length, in bytes, of the returned message.      */
  4800. APIRET   ulrc;             /* Return Code.                                                                             */
  4801.  
  4802. ulrc = WtkGetTextMessage( pTable, cTable, pbBuffer, cbBuffer, pszMessageName, pszFile, pcbMsg);
  4803.  
  4804.  
  4805. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Parameter pTable ΓòÉΓòÉΓòÉ
  4806.  
  4807. pTable (PCHAR*) - input 
  4808.     Pointer table. 
  4809.  
  4810.     Each doubleword pointer points to an ASCIIZ string or a double-byte 
  4811.     character-set (DBCS) string ending in nulls. A maximum of nine strings can 
  4812.     be present. 
  4813.  
  4814.  
  4815. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Parameter cTable ΓòÉΓòÉΓòÉ
  4816.  
  4817. cTable (ULONG) - input 
  4818.     Number of variable insertion text strings. 
  4819.  
  4820.     Possible values range from 0 to 9. If cTable is 0, pTable is ignored 
  4821.  
  4822.  
  4823. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Parameter pbBuffer ΓòÉΓòÉΓòÉ
  4824.  
  4825. pbBuffer (PBYTE) - output 
  4826.     The address of the caller's buffer area where the system returns the 
  4827.     requested message. 
  4828.  
  4829.     If the message is too long to fit in the caller's buffer, then as much of 
  4830.     the message text as possible is returned, with the appropriate error return 
  4831.     code. 
  4832.  
  4833.  
  4834. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Parameter cbBuffer ΓòÉΓòÉΓòÉ
  4835.  
  4836. cbBuffer (ULONG) - input 
  4837.     The length, in bytes, of the caller's buffer area. 
  4838.  
  4839.  
  4840. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Parameter pszMessageName ΓòÉΓòÉΓòÉ
  4841.  
  4842. pszMessageName (PSZ) - input 
  4843.     Address of the ASCIIZ name of the message 
  4844.  
  4845.  
  4846. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Parameter pszFile ΓòÉΓòÉΓòÉ
  4847.  
  4848. pszFile (PSZ) - input 
  4849.     Address of the ASCIIZ name of the text message file. 
  4850.  
  4851.     The path name may contain ?: for the drive in order to open the text 
  4852.     message file on the boot drive. 
  4853.  
  4854.     The name may not include wildcards. 
  4855.  
  4856.     It is recommended, but not enforced to use filenames with the extension tmf 
  4857.     to indicate that this is a text message file. 
  4858.  
  4859.  
  4860. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Parameter pcbMsg ΓòÉΓòÉΓòÉ
  4861.  
  4862. pcbMsg (PULONG) - output 
  4863.     The address of a variable containing the length, in bytes, of the returned 
  4864.     message. 
  4865.  
  4866.  
  4867. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Parameters ΓòÉΓòÉΓòÉ
  4868.  
  4869. pTable (PCHAR*) - input 
  4870.     Pointer table. 
  4871.  
  4872.     Each doubleword pointer points to an ASCIIZ string or a double-byte 
  4873.     character-set (DBCS) string ending in nulls. A maximum of nine strings can 
  4874.     be present. 
  4875.  
  4876.  cTable (ULONG) - input 
  4877.     Number of variable insertion text strings. 
  4878.  
  4879.     Possible values range from 0 to 9. If cTable is 0, pTable is ignored 
  4880.  
  4881.  pbBuffer (PBYTE) - output 
  4882.     The address of the caller's buffer area where the system returns the 
  4883.     requested message. 
  4884.  
  4885.     If the message is too long to fit in the caller's buffer, then as much of 
  4886.     the message text as possible is returned, with the appropriate error return 
  4887.     code. 
  4888.  
  4889.  cbBuffer (ULONG) - input 
  4890.     The length, in bytes, of the caller's buffer area. 
  4891.  
  4892.  pszMessageName (PSZ) - input 
  4893.     Address of the ASCIIZ name of the message 
  4894.  
  4895.  pszFile (PSZ) - input 
  4896.     Address of the ASCIIZ name of the text message file. 
  4897.  
  4898.     The path name may contain ?: for the drive in order to open the text 
  4899.     message file on the boot drive. 
  4900.  
  4901.     The name may not include wildcards. 
  4902.  
  4903.     It is recommended, but not enforced to use filenames with the extension tmf 
  4904.     to indicate that this is a text message file. 
  4905.  
  4906.  pcbMsg (PULONG) - output 
  4907.     The address of a variable containing the length, in bytes, of the returned 
  4908.     message. 
  4909.  
  4910.  ulrc (APIRET) - returns 
  4911.     Return Code. 
  4912.  
  4913.     WtkGetTextMessage returns one of the following return codes: 
  4914.  
  4915.     0         NO_ERROR 
  4916.     5         ERROR_ACCESS_DENIED 
  4917.     87        ERROR_INVALID_PARAMETER 
  4918.  
  4919.     or return codes of the following functions 
  4920.  
  4921.         DosSearchPath 
  4922.         DosOpen 
  4923.         DosQueryPathInfo 
  4924.  
  4925.  
  4926. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage Return Value - ulrc ΓòÉΓòÉΓòÉ
  4927.  
  4928. ulrc (APIRET) - returns 
  4929.     Return Code. 
  4930.  
  4931.     WtkGetTextMessage returns one of the following return codes: 
  4932.  
  4933.     0         NO_ERROR 
  4934.     5         ERROR_ACCESS_DENIED 
  4935.     87        ERROR_INVALID_PARAMETER 
  4936.  
  4937.     or return codes of the following functions 
  4938.  
  4939.         DosSearchPath 
  4940.         DosOpen 
  4941.         DosQueryPathInfo 
  4942.  
  4943.  
  4944. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Remarks ΓòÉΓòÉΓòÉ
  4945.  
  4946. The WtkGetTextMessage is different to DosGetMessage in the following concerns: 
  4947.  
  4948.      the message is not taken from a compiled OS/2 message file, but from an 
  4949.       editable text file. 
  4950.  
  4951.      a zero byte is appended to the message returned, so that it can be used 
  4952.       right away with standard C/C++ APIs 
  4953.  
  4954.      placeholders from %1 to %1 in the message text are replaced if values for 
  4955.       those are handed over to WtkGetTextMessage in the pointer table referred 
  4956.       to by the pTable parameter. 
  4957.       In opposite to the DosGetMessage call text replacement is performed even 
  4958.       if not enough parameters are supplied - where values are missing, the 
  4959.       placeholder remains unmodified within the message text. 
  4960.  
  4961.  
  4962. ΓòÉΓòÉΓòÉ <hidden> WtkGetTextMessage - Related functions ΓòÉΓòÉΓòÉ
  4963.  
  4964. Related Functions 
  4965.  
  4966. none 
  4967.  
  4968.  
  4969. ΓòÉΓòÉΓòÉ 8.39. WtkInitializeMmf ΓòÉΓòÉΓòÉ
  4970.  
  4971. Select an item: 
  4972.  
  4973.      Syntax 
  4974.      Parameters 
  4975.      Returns 
  4976.      Remarks 
  4977.      Related Functions 
  4978.  
  4979.  
  4980. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeMmf - Syntax ΓòÉΓòÉΓòÉ
  4981.  
  4982. This function initializes MMF support for the current thread. 
  4983.  
  4984. #define INCL_WTKMMF
  4985. #include <wpstk.h>
  4986.  
  4987. PHMMF    phmmf;         /* The address of a variable containing the handle to the MMF manager.  */
  4988. ULONG    ulMaxBuffer;   /* Number of memory mapped files to support for this thread.            */
  4989. APIRET   ulrc;          /* Return Code.                                                         */
  4990.  
  4991. ulrc = WtkInitializeMmf( phmmf, ulMaxBuffer);
  4992.  
  4993.  
  4994. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeMmf - Parameter phmmf ΓòÉΓòÉΓòÉ
  4995.  
  4996. phmmf (PHMMF) - output 
  4997.     The address of a variable containing the handle to the MMF manager. 
  4998.  
  4999.  
  5000. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeMmf - Parameter ulMaxBuffer ΓòÉΓòÉΓòÉ
  5001.  
  5002. ulMaxBuffer (ULONG) - input 
  5003.     Number of memory mapped files to support for this thread. 
  5004.  
  5005.  
  5006. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeMmf - Parameters ΓòÉΓòÉΓòÉ
  5007.  
  5008. phmmf (PHMMF) - output 
  5009.     The address of a variable containing the handle to the MMF manager. 
  5010.  
  5011.  ulMaxBuffer (ULONG) - input 
  5012.     Number of memory mapped files to support for this thread. 
  5013.  
  5014.  ulrc (APIRET) - returns 
  5015.     Return Code. 
  5016.  
  5017.     WtkInitializeMmf returns one of the following return codes: 
  5018.  
  5019.     0         NO_ERROR 
  5020.     5         ERROR_ACCESS_DENIED 
  5021.     87        ERROR_INVALID_PARAMETER 
  5022.  
  5023.  
  5024. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeMmf Return Value - ulrc ΓòÉΓòÉΓòÉ
  5025.  
  5026. ulrc (APIRET) - returns 
  5027.     Return Code. 
  5028.  
  5029.     WtkInitializeMmf returns one of the following return codes: 
  5030.  
  5031.     0         NO_ERROR 
  5032.     5         ERROR_ACCESS_DENIED 
  5033.     87        ERROR_INVALID_PARAMETER 
  5034.  
  5035.  
  5036. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeMmf - Remarks ΓòÉΓòÉΓòÉ
  5037.  
  5038. This function registers the MMF exception handler for to support memory mapped 
  5039. files. When leaving the function that called WtkInitializeMmf, WtkTerminateMmf 
  5040. must be called to deregister the exception handler again, especially if other 
  5041. exception handler are used beside the one for MMF support. Otherwise 
  5042. unpredictable results (most often simply protection violations may occurr). 
  5043.  
  5044.  
  5045. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeMmf - Related functions ΓòÉΓòÉΓòÉ
  5046.  
  5047. Related Functions 
  5048.  
  5049. none 
  5050.  
  5051.  
  5052. ΓòÉΓòÉΓòÉ 8.40. WtkInitializeNumSpinbuttonArray ΓòÉΓòÉΓòÉ
  5053.  
  5054. Select an item: 
  5055.  
  5056.      Syntax 
  5057.      Parameters 
  5058.      Returns 
  5059.      Remarks 
  5060.      Related Functions 
  5061.  
  5062.  
  5063. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray - Syntax ΓòÉΓòÉΓòÉ
  5064.  
  5065. This function initializes a spinbutton, which is to hold a range of numeric 
  5066. values with steps in between. 
  5067.  
  5068. #define INCL_WTKUTLCONTROL
  5069. #include <wpstk.h>
  5070.  
  5071. HWND    hwndSpinbutton;   /* Handle of the spinbutton window.           */
  5072. ULONG   ulMinValue;       /* The minimum value of the spinbutton.       */
  5073. ULONG   ulMaxValue;       /* The maximum value of the spinbutton.       */
  5074. ULONG   ulStep;           /* The step between the values in the range.  */
  5075. BOOL    fResult;          /* Success indicator.                         */
  5076.  
  5077. fResult = WtkInitializeNumSpinbuttonArray( hwndSpinbutton, ulMinValue, ulMaxValue, ulStep);
  5078.  
  5079.  
  5080. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray - Parameter hwndSpinbutton ΓòÉΓòÉΓòÉ
  5081.  
  5082. hwndSpinbutton (HWND) - input 
  5083.     Handle of the spinbutton window. 
  5084.  
  5085.  
  5086. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray - Parameter ulMinValue ΓòÉΓòÉΓòÉ
  5087.  
  5088. ulMinValue (ULONG) - input 
  5089.     The minimum value of the spinbutton. 
  5090.  
  5091.  
  5092. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray - Parameter ulMaxValue ΓòÉΓòÉΓòÉ
  5093.  
  5094. ulMaxValue (ULONG) - input 
  5095.     The maximum value of the spinbutton. 
  5096.  
  5097.  
  5098. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray - Parameter ulStep ΓòÉΓòÉΓòÉ
  5099.  
  5100. ulStep (ULONG) - input 
  5101.     The step between the values in the range. 
  5102.  
  5103.  
  5104. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray - Parameters ΓòÉΓòÉΓòÉ
  5105.  
  5106. hwndSpinbutton (HWND) - input 
  5107.     Handle of the spinbutton window. 
  5108.  
  5109.  ulMinValue (ULONG) - input 
  5110.     The minimum value of the spinbutton. 
  5111.  
  5112.  ulMaxValue (ULONG) - input 
  5113.     The maximum value of the spinbutton. 
  5114.  
  5115.  ulStep (ULONG) - input 
  5116.     The step between the values in the range. 
  5117.  
  5118.  fResult (BOOL) - returns 
  5119.     Success indicator. 
  5120.  
  5121.     TRUE 
  5122.               Successful. 
  5123.     FALSE 
  5124.               Not successful. 
  5125.  
  5126.     Extended error information can be obtained using 
  5127.     WinGetLastError/WinGetErrorInfo. 
  5128.  
  5129.  
  5130. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray Return Value - fResult ΓòÉΓòÉΓòÉ
  5131.  
  5132. fResult (BOOL) - returns 
  5133.     Success indicator. 
  5134.  
  5135.     TRUE 
  5136.               Successful. 
  5137.     FALSE 
  5138.               Not successful. 
  5139.  
  5140.     Extended error information can be obtained using 
  5141.     WinGetLastError/WinGetErrorInfo. 
  5142.  
  5143.  
  5144. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray - Remarks ΓòÉΓòÉΓòÉ
  5145.  
  5146. Unfortunately the OS/2 Presentation Manager provides numeric spinbuttons does 
  5147. not provide a parameter for steps in a numeric range, when setting up a 
  5148. spinbutton with numeric values. This forces you to either 
  5149.  
  5150.      to have a spinbutton, which gives access to all the values between the 
  5151.       minimum and maximum value, resulting in a very ineffective control when 
  5152.       using large ranges 
  5153.      to setup a temporary array of strings for initializing the spinbutton, 
  5154.       resulting in a numeric spinbutton having only as much as elements between 
  5155.       the minimum and maximum value, as useful. 
  5156.  
  5157.  WtkInitializeNumSpinbuttonArray aids you in the latter case. Use also 
  5158.  WtkQueryNumSpinbuttonIndex for an easy conversion from a numeric value of a 
  5159.  such initialized numeric spinbutton to an array index. You will need this one 
  5160.  to set the spinbutton to a desired value. 
  5161.  
  5162.  
  5163. ΓòÉΓòÉΓòÉ <hidden> WtkInitializeNumSpinbuttonArray - Related functions ΓòÉΓòÉΓòÉ
  5164.  
  5165. Related Functions 
  5166.  
  5167. none 
  5168.  
  5169.  
  5170. ΓòÉΓòÉΓòÉ 8.41. WtkIsDirectory ΓòÉΓòÉΓòÉ
  5171.  
  5172. Select an item: 
  5173.  
  5174.      Syntax 
  5175.      Parameters 
  5176.      Returns 
  5177.      Remarks 
  5178.      Related Functions 
  5179.  
  5180.  
  5181. ΓòÉΓòÉΓòÉ <hidden> WtkIsDirectory - Syntax ΓòÉΓòÉΓòÉ
  5182.  
  5183. This function checks, if a given name is the name of a directory. 
  5184.  
  5185. #define INCL_WTKUTLFILE
  5186. #include <wpstk.h>
  5187.  
  5188. PSZ    pszName;   /* Address of the ASCIIZ path name of the directory to be searched.  */
  5189. BOOL   fResult;   /* Success indicator.                                                */
  5190.  
  5191. fResult = WtkIsDirectory( pszName);
  5192.  
  5193.  
  5194. ΓòÉΓòÉΓòÉ <hidden> WtkIsDirectory - Parameter pszName ΓòÉΓòÉΓòÉ
  5195.  
  5196. pszName (PSZ) - input 
  5197.     Address of the ASCIIZ path name of the directory to be searched. 
  5198.  
  5199.     The path name may contain ?: for the drive in order to search the directory 
  5200.     on the boot drive. 
  5201.  
  5202.     The name may not include wildcards. 
  5203.  
  5204.  
  5205. ΓòÉΓòÉΓòÉ <hidden> WtkIsDirectory - Parameters ΓòÉΓòÉΓòÉ
  5206.  
  5207. pszName (PSZ) - input 
  5208.     Address of the ASCIIZ path name of the directory to be searched. 
  5209.  
  5210.     The path name may contain ?: for the drive in order to search the directory 
  5211.     on the boot drive. 
  5212.  
  5213.     The name may not include wildcards. 
  5214.  
  5215.  fResult (BOOL) - returns 
  5216.     Success indicator. 
  5217.  
  5218.     TRUE 
  5219.               Given name is an existing directory. 
  5220.     FALSE 
  5221.               Directory not found or given name is not a directory. 
  5222.  
  5223.  
  5224. ΓòÉΓòÉΓòÉ <hidden> WtkIsDirectory Return Value - fResult ΓòÉΓòÉΓòÉ
  5225.  
  5226. fResult (BOOL) - returns 
  5227.     Success indicator. 
  5228.  
  5229.     TRUE 
  5230.               Given name is an existing directory. 
  5231.     FALSE 
  5232.               Directory not found or given name is not a directory. 
  5233.  
  5234.  
  5235. ΓòÉΓòÉΓòÉ <hidden> WtkIsDirectory - Remarks ΓòÉΓòÉΓòÉ
  5236.  
  5237. This function is identical to WtkDirExists. 
  5238.  
  5239. This function supports boot drive recognition. Specify ?: for the drive in 
  5240. order to search the directory on the boot drive. 
  5241.  
  5242.  
  5243. ΓòÉΓòÉΓòÉ <hidden> WtkIsDirectory - Related functions ΓòÉΓòÉΓòÉ
  5244.  
  5245. Related Functions 
  5246.  
  5247. none 
  5248.  
  5249.  
  5250. ΓòÉΓòÉΓòÉ 8.42. WtkIsFile ΓòÉΓòÉΓòÉ
  5251.  
  5252. Select an item: 
  5253.  
  5254.      Syntax 
  5255.      Parameters 
  5256.      Returns 
  5257.      Remarks 
  5258.      Related Functions 
  5259.  
  5260.  
  5261. ΓòÉΓòÉΓòÉ <hidden> WtkIsFile - Syntax ΓòÉΓòÉΓòÉ
  5262.  
  5263. This function checks, if a given name is the name of a file. 
  5264.  
  5265. #define INCL_WTKUTLFILE
  5266. #include <wpstk.h>
  5267.  
  5268. PSZ    pszName;   /* Address of the ASCIIZ path name of the file to be searched.  */
  5269. BOOL   fResult;   /* Success indicator.                                           */
  5270.  
  5271. fResult = WtkIsFile( pszName);
  5272.  
  5273.  
  5274. ΓòÉΓòÉΓòÉ <hidden> WtkIsFile - Parameter pszName ΓòÉΓòÉΓòÉ
  5275.  
  5276. pszName (PSZ) - input 
  5277.     Address of the ASCIIZ path name of the file to be searched. 
  5278.  
  5279.     The path name may contain ?: for the drive in order to search the file on 
  5280.     the boot drive. 
  5281.  
  5282.     The name may not include wildcards. In order to search with wildcards, use 
  5283.     WtkFileMaskExists. 
  5284.  
  5285.  
  5286. ΓòÉΓòÉΓòÉ <hidden> WtkIsFile - Parameters ΓòÉΓòÉΓòÉ
  5287.  
  5288. pszName (PSZ) - input 
  5289.     Address of the ASCIIZ path name of the file to be searched. 
  5290.  
  5291.     The path name may contain ?: for the drive in order to search the file on 
  5292.     the boot drive. 
  5293.  
  5294.     The name may not include wildcards. In order to search with wildcards, use 
  5295.     WtkFileMaskExists. 
  5296.  
  5297.  fResult (BOOL) - returns 
  5298.     Success indicator. 
  5299.  
  5300.     TRUE 
  5301.               Given name is an existing file. 
  5302.     FALSE 
  5303.               File not found or given name is not a file. 
  5304.  
  5305.  
  5306. ΓòÉΓòÉΓòÉ <hidden> WtkIsFile Return Value - fResult ΓòÉΓòÉΓòÉ
  5307.  
  5308. fResult (BOOL) - returns 
  5309.     Success indicator. 
  5310.  
  5311.     TRUE 
  5312.               Given name is an existing file. 
  5313.     FALSE 
  5314.               File not found or given name is not a file. 
  5315.  
  5316.  
  5317. ΓòÉΓòÉΓòÉ <hidden> WtkIsFile - Remarks ΓòÉΓòÉΓòÉ
  5318.  
  5319. This function is identical to WtkFileExists. 
  5320.  
  5321. This function supports boot drive recognition. Specify ?: for the drive in 
  5322. order to search the file on the boot drive. 
  5323.  
  5324.  
  5325. ΓòÉΓòÉΓòÉ <hidden> WtkIsFile - Related functions ΓòÉΓòÉΓòÉ
  5326.  
  5327. Related Functions 
  5328.  
  5329. none 
  5330.  
  5331.  
  5332. ΓòÉΓòÉΓòÉ 8.43. WtkIsOfPublicPmClass ΓòÉΓòÉΓòÉ
  5333.  
  5334. Select an item: 
  5335.  
  5336.      Syntax 
  5337.      Parameters 
  5338.      Returns 
  5339.      Remarks 
  5340.      Related Functions 
  5341.  
  5342.  
  5343. ΓòÉΓòÉΓòÉ <hidden> WtkIsOfPublicPmClass - Syntax ΓòÉΓòÉΓòÉ
  5344.  
  5345. This function determines wether a given window is of a specific PM class and 
  5346. has the given primary style, thus is a specific kind of this class. 
  5347.  
  5348. #define INCL_WTKUTLCONTROL
  5349. #include <wpstk.h>
  5350.  
  5351. HWND    hwnd;                   /* Handle of the window to be examined.  */
  5352. PSZ     pszClassIndex;          /* Class index (like WC_*)               */
  5353. ULONG   ulPrimaryWindowStyle;   /* Primary window style.                 */
  5354. BOOL    fResult;                /* Class member indicator.               */
  5355.  
  5356. fResult = WtkIsOfPublicPmClass( hwnd, pszClassIndex, ulPrimaryWindowStyle);
  5357.  
  5358.  
  5359. ΓòÉΓòÉΓòÉ <hidden> WtkIsOfPublicPmClass - Parameter hwnd ΓòÉΓòÉΓòÉ
  5360.  
  5361. hwnd (HWND) - input 
  5362.     Handle of the window to be examined. 
  5363.  
  5364.  
  5365. ΓòÉΓòÉΓòÉ <hidden> WtkIsOfPublicPmClass - Parameter pszClassIndex ΓòÉΓòÉΓòÉ
  5366.  
  5367. pszClassIndex (PSZ) - input 
  5368.     Class index (like WC_*) 
  5369.  
  5370.     This value specifies, of what public PM class the window should be. Some 
  5371.     possible values are: 
  5372.  
  5373.         WC_FRAME 
  5374.         WC_COMBOBOX 
  5375.         WC_BUTTON 
  5376.         WC_MENU 
  5377.         WC_STATIC 
  5378.         WC_ENTRYFIELD 
  5379.         WC_LISTBOX 
  5380.         WC_SCROLLBAR 
  5381.         WC_TITLEBAR 
  5382.  
  5383.     These classes return "#n" as the PM class name, where n is a number. This 
  5384.     is a requirement for WtkIsOfPublicPmClass to identify a PM Class as public. 
  5385.     Your application may register PM classes compliant to that name scheme with 
  5386.     a high number, so that this function can be used anyway. 
  5387.  
  5388.  
  5389. ΓòÉΓòÉΓòÉ <hidden> WtkIsOfPublicPmClass - Parameter ulPrimaryWindowStyle ΓòÉΓòÉΓòÉ
  5390.  
  5391. ulPrimaryWindowStyle (ULONG) - input 
  5392.     Primary window style. 
  5393.  
  5394.     This style is specified to further specify, what characteristic the PM 
  5395.     class of the examined window should have. If that further specification is 
  5396.     not required, leave this parameter zero. 
  5397.  
  5398.     Before examining the window style of the given window, it is first masked 
  5399.     with BS_PRIMARYSTYLES (0x000fL). 
  5400.  
  5401.     Here are some examples of window styles, that make sense in conjunction 
  5402.     with their respective public PM class: 
  5403.  
  5404.     public PM class     primary window styles 
  5405.  
  5406.     WC_BUTTON           BS_PUSHBUTTON, BS_CHECKBOX, BS_AUTOCHECKBOX, 
  5407.                         BS_RADIOBUTTON, BS_AUTORADIOBUTTON, BS_3STATE, 
  5408.                         BS_3STATE 
  5409.  
  5410.     WC_STATIC           SS_TEXT, SS_GROUPBOX, SS_ICON, SS_BITMAP, 
  5411.                         SS_HALFTONERECT, SS_BKGNDRECT, SS_FGNDFRAME, 
  5412.                         SS_BKGNDFRAME, SS_SYSICON 
  5413.  
  5414.  
  5415. ΓòÉΓòÉΓòÉ <hidden> WtkIsOfPublicPmClass - Parameters ΓòÉΓòÉΓòÉ
  5416.  
  5417. hwnd (HWND) - input 
  5418.     Handle of the window to be examined. 
  5419.  
  5420.  pszClassIndex (PSZ) - input 
  5421.     Class index (like WC_*) 
  5422.  
  5423.     This value specifies, of what public PM class the window should be. Some 
  5424.     possible values are: 
  5425.  
  5426.         WC_FRAME 
  5427.         WC_COMBOBOX 
  5428.         WC_BUTTON 
  5429.         WC_MENU 
  5430.         WC_STATIC 
  5431.         WC_ENTRYFIELD 
  5432.         WC_LISTBOX 
  5433.         WC_SCROLLBAR 
  5434.         WC_TITLEBAR 
  5435.  
  5436.     These classes return "#n" as the PM class name, where n is a number. This 
  5437.     is a requirement for WtkIsOfPublicPmClass to identify a PM Class as public. 
  5438.     Your application may register PM classes compliant to that name scheme with 
  5439.     a high number, so that this function can be used anyway. 
  5440.  
  5441.  ulPrimaryWindowStyle (ULONG) - input 
  5442.     Primary window style. 
  5443.  
  5444.     This style is specified to further specify, what characteristic the PM 
  5445.     class of the examined window should have. If that further specification is 
  5446.     not required, leave this parameter zero. 
  5447.  
  5448.     Before examining the window style of the given window, it is first masked 
  5449.     with BS_PRIMARYSTYLES (0x000fL). 
  5450.  
  5451.     Here are some examples of window styles, that make sense in conjunction 
  5452.     with their respective public PM class: 
  5453.  
  5454.     public PM class     primary window styles 
  5455.  
  5456.     WC_BUTTON           BS_PUSHBUTTON, BS_CHECKBOX, BS_AUTOCHECKBOX, 
  5457.                         BS_RADIOBUTTON, BS_AUTORADIOBUTTON, BS_3STATE, 
  5458.                         BS_3STATE 
  5459.  
  5460.     WC_STATIC           SS_TEXT, SS_GROUPBOX, SS_ICON, SS_BITMAP, 
  5461.                         SS_HALFTONERECT, SS_BKGNDRECT, SS_FGNDFRAME, 
  5462.                         SS_BKGNDFRAME, SS_SYSICON 
  5463.  
  5464.  fResult (BOOL) - returns 
  5465.     Class member indicator. 
  5466.  
  5467.     TRUE 
  5468.               the class is of the given class and has the given primary window 
  5469.               style. 
  5470.  
  5471.     FALSE 
  5472.               the class is not of the given class or does not have the given 
  5473.               primary window style. 
  5474.  
  5475.     Extended error information can be obtained using 
  5476.     WinGetLastError/WinGetErrorInfo. 
  5477.  
  5478.  
  5479. ΓòÉΓòÉΓòÉ <hidden> WtkIsOfPublicPmClass Return Value - fResult ΓòÉΓòÉΓòÉ
  5480.  
  5481. fResult (BOOL) - returns 
  5482.     Class member indicator. 
  5483.  
  5484.     TRUE 
  5485.               the class is of the given class and has the given primary window 
  5486.               style. 
  5487.  
  5488.     FALSE 
  5489.               the class is not of the given class or does not have the given 
  5490.               primary window style. 
  5491.  
  5492.     Extended error information can be obtained using 
  5493.     WinGetLastError/WinGetErrorInfo. 
  5494.  
  5495.  
  5496. ΓòÉΓòÉΓòÉ <hidden> WtkIsOfPublicPmClass - Remarks ΓòÉΓòÉΓòÉ
  5497.  
  5498. Ths function can only handle windows of classes, that are public PM classes, 
  5499. that is, classes, that return "#n" as the PM class, where n is a number. Your 
  5500. application may register private PM classes compliant to that name scheme with 
  5501. an unused number, so that this function can be used anyway. 
  5502.  
  5503.  
  5504. ΓòÉΓòÉΓòÉ <hidden> WtkIsOfPublicPmClass - Related functions ΓòÉΓòÉΓòÉ
  5505.  
  5506. Related Functions 
  5507.  
  5508. none 
  5509.  
  5510.  
  5511. ΓòÉΓòÉΓòÉ 8.44. WtkIsWarp4 ΓòÉΓòÉΓòÉ
  5512.  
  5513. Select an item: 
  5514.  
  5515.      Syntax 
  5516.      Parameters 
  5517.      Returns 
  5518.      Remarks 
  5519.      Related Functions 
  5520.  
  5521.  
  5522. ΓòÉΓòÉΓòÉ <hidden> WtkIsWarp4 - Syntax ΓòÉΓòÉΓòÉ
  5523.  
  5524. This function tests, if the calling program is running under WARP 4 or greater. 
  5525.  
  5526. #define INCL_WTKUTLSYSTEM
  5527. #include <wpstk.h>
  5528.  
  5529. BOOL   fResult;   /* OS/2 WARP 4 indicator.  */
  5530.  
  5531. fResult = WtkIsWarp4();
  5532.  
  5533.  
  5534. ΓòÉΓòÉΓòÉ <hidden> WtkIsWarp4 - Parameters ΓòÉΓòÉΓòÉ
  5535.  
  5536. fResult (BOOL) - returns 
  5537.     OS/2 WARP 4 indicator. 
  5538.  
  5539.     TRUE 
  5540.               Program is running under OS/2 WARP 4 or greater. 
  5541.     FALSE 
  5542.               Program is running under OS/2 below WARP 4 
  5543.  
  5544.  
  5545. ΓòÉΓòÉΓòÉ <hidden> WtkIsWarp4 Return Value - fResult ΓòÉΓòÉΓòÉ
  5546.  
  5547. fResult (BOOL) - returns 
  5548.     OS/2 WARP 4 indicator. 
  5549.  
  5550.     TRUE 
  5551.               Program is running under OS/2 WARP 4 or greater. 
  5552.     FALSE 
  5553.               Program is running under OS/2 below WARP 4 
  5554.  
  5555.  
  5556. ΓòÉΓòÉΓòÉ <hidden> WtkIsWarp4 - Remarks ΓòÉΓòÉΓòÉ
  5557.  
  5558. This function is mostly needed to distinct between OS/2 WARP 3 and WARP 4 
  5559. because of the differences in 
  5560.  
  5561.      the layout of settings notebook pages of WPS objects, especially the 
  5562.       notebook buttons. 
  5563.  
  5564.       See also 
  5565.  
  5566.            WtkRelocateNotebookpageControls 
  5567.  
  5568.      font names and sizes being used in dialogs 
  5569.  
  5570.  
  5571. ΓòÉΓòÉΓòÉ <hidden> WtkIsWarp4 - Related functions ΓòÉΓòÉΓòÉ
  5572.  
  5573. Related Functions 
  5574.  
  5575. none 
  5576.  
  5577.  
  5578. ΓòÉΓòÉΓòÉ 8.45. WtkOpenDevice ΓòÉΓòÉΓòÉ
  5579.  
  5580. Select an item: 
  5581.  
  5582.      Syntax 
  5583.      Parameters 
  5584.      Returns 
  5585.      Remarks 
  5586.      Related Functions 
  5587.  
  5588.  
  5589. ΓòÉΓòÉΓòÉ <hidden> WtkOpenDevice - Syntax ΓòÉΓòÉΓòÉ
  5590.  
  5591. This function opens a device. 
  5592.  
  5593. #define INCL_WTKUTLIOCTRL
  5594. #include <wpstk.h>
  5595.  
  5596. PSZ      pszName;      /* Address of the ASCIIZ name of the device.                                     */
  5597. PHFILE   phdevice;     /* The address of a variable where the handle of the opened device is returned.  */
  5598. ULONG    ulOpenMode;   /* The mode, in which the device has to be opened.                               */
  5599. APIRET   ulrc;         /* Return Code.                                                                  */
  5600.  
  5601. ulrc = WtkOpenDevice( pszName, phdevice, ulOpenMode);
  5602.  
  5603.  
  5604. ΓòÉΓòÉΓòÉ <hidden> WtkOpenDevice - Parameter pszName ΓòÉΓòÉΓòÉ
  5605.  
  5606. pszName (PSZ) - input 
  5607.     Address of the ASCIIZ name of the device. 
  5608.  
  5609.     If the last character is a colon, the device is opened in block mode. 
  5610.  
  5611.  
  5612. ΓòÉΓòÉΓòÉ <hidden> WtkOpenDevice - Parameter phdevice ΓòÉΓòÉΓòÉ
  5613.  
  5614. phdevice (PHFILE) - output 
  5615.     The address of a variable where the handle of the opened device is 
  5616.     returned. 
  5617.  
  5618.  
  5619. ΓòÉΓòÉΓòÉ <hidden> WtkOpenDevice - Parameter ulOpenMode ΓòÉΓòÉΓòÉ
  5620.  
  5621. ulOpenMode (ULONG) - input 
  5622.     The mode, in which the device has to be opened. 
  5623.  
  5624.     WTK_OPENDEVICE_SHARED 
  5625.               opens the device in readonly and thus in shared mode 
  5626.  
  5627.     WTK_OPENDEVICE_EXCLUSIVE 
  5628.               opens the device in readwrite and thus in exlusive mode 
  5629.               (overrides WTK_OPENDEVICE_SHARED) 
  5630.  
  5631.     WTK_OPENDEVICE_NOCACHE 
  5632.               bypasses the cache, if block devices are opened 
  5633.  
  5634.     WTK_OPENDEVICE_BLOCKDEVICE 
  5635.               explicitely states, that the specified device is a block device. 
  5636.  
  5637.     Note:  If the last character is a colon, the device is opened in block 
  5638.     mode, even if WTK_OPENDEVICE_BLOCKDEVICE is not specified. 
  5639.  
  5640.  
  5641. ΓòÉΓòÉΓòÉ <hidden> WtkOpenDevice - Parameters ΓòÉΓòÉΓòÉ
  5642.  
  5643. pszName (PSZ) - input 
  5644.     Address of the ASCIIZ name of the device. 
  5645.  
  5646.     If the last character is a colon, the device is opened in block mode. 
  5647.  
  5648.  phdevice (PHFILE) - output 
  5649.     The address of a variable where the handle of the opened device is 
  5650.     returned. 
  5651.  
  5652.  ulOpenMode (ULONG) - input 
  5653.     The mode, in which the device has to be opened. 
  5654.  
  5655.     WTK_OPENDEVICE_SHARED 
  5656.               opens the device in readonly and thus in shared mode 
  5657.  
  5658.     WTK_OPENDEVICE_EXCLUSIVE 
  5659.               opens the device in readwrite and thus in exlusive mode 
  5660.               (overrides WTK_OPENDEVICE_SHARED) 
  5661.  
  5662.     WTK_OPENDEVICE_NOCACHE 
  5663.               bypasses the cache, if block devices are opened 
  5664.  
  5665.     WTK_OPENDEVICE_BLOCKDEVICE 
  5666.               explicitely states, that the specified device is a block device. 
  5667.  
  5668.     Note:  If the last character is a colon, the device is opened in block 
  5669.     mode, even if WTK_OPENDEVICE_BLOCKDEVICE is not specified. 
  5670.  
  5671.  ulrc (APIRET) - returns 
  5672.     Return Code. 
  5673.  
  5674.     WtkOpenDevice returns one of the following return codes: 
  5675.  
  5676.     0         NO_ERROR 
  5677.     87        ERROR_INVALID_PARAMETER 
  5678.  
  5679.     or return codes of the following functions 
  5680.  
  5681.         DosOpen 
  5682.  
  5683.  
  5684. ΓòÉΓòÉΓòÉ <hidden> WtkOpenDevice Return Value - ulrc ΓòÉΓòÉΓòÉ
  5685.  
  5686. ulrc (APIRET) - returns 
  5687.     Return Code. 
  5688.  
  5689.     WtkOpenDevice returns one of the following return codes: 
  5690.  
  5691.     0         NO_ERROR 
  5692.     87        ERROR_INVALID_PARAMETER 
  5693.  
  5694.     or return codes of the following functions 
  5695.  
  5696.         DosOpen 
  5697.  
  5698.  
  5699. ΓòÉΓòÉΓòÉ <hidden> WtkOpenDevice - Remarks ΓòÉΓòÉΓòÉ
  5700.  
  5701. A device opened with WtkOpenDevice must be closed by a call to DosClose. 
  5702.  
  5703. If the last character specified with pszName is a colon, the device is opened 
  5704. in block mode, even when WTK_OPENDEVICE_BLOCKDEVICE is not specified within 
  5705. ulOpenMode. 
  5706.  
  5707.  
  5708. ΓòÉΓòÉΓòÉ <hidden> WtkOpenDevice - Related functions ΓòÉΓòÉΓòÉ
  5709.  
  5710. Related Functions 
  5711.  
  5712. none 
  5713.  
  5714.  
  5715. ΓòÉΓòÉΓòÉ 8.46. WtkPutEaValue ΓòÉΓòÉΓòÉ
  5716.  
  5717. Select an item: 
  5718.  
  5719.      Syntax 
  5720.      Parameters 
  5721.      Returns 
  5722.      Remarks 
  5723.      Related Functions 
  5724.  
  5725.  
  5726. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Syntax ΓòÉΓòÉΓòÉ
  5727.  
  5728. This function appends a value to an extended attribute directly on disk. 
  5729.  
  5730. #define INCL_WTKEAS
  5731. #include <wpstk.h>
  5732.  
  5733. PSZ      pszName;       /* Address of the ASCIIZ path name of the file or directory.                      */
  5734. PSZ      pszEaName;     /* Address of the ASCIIZ name of the extended attribute.                          */
  5735. ULONG    ulMultiType;   /* Multitype of the value to be added to the extended attribute.                  */
  5736. ULONG    ulEaType;      /* Type of the value to be added to the extended attribute.                       */
  5737. PBYTE    pbValue;       /* The address of a buffer of the value to be written.                            */
  5738. ULONG    ulValuelen;    /* The length, in bytes, of the buffer described by pbValue.                      */
  5739. BOOL     fWriteThru;    /* A flag to bypass the cache and write the extended attribute directly to disk.  */
  5740. BYTE     fEA;           /* The flags to be set for this extended attribute flags.                         */
  5741. APIRET   ulrc;          /* Return Code.                                                                   */
  5742.  
  5743. ulrc = WtkPutEaValue( pszName, pszEaName, ulMultiType, ulEaType, pbValue, ulValuelen, fWriteThru, fEA);
  5744.  
  5745.  
  5746. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameter pszName ΓòÉΓòÉΓòÉ
  5747.  
  5748. pszName (PSZ) - input 
  5749.     Address of the ASCIIZ path name of the file or directory. 
  5750.  
  5751.     The path name may contain ?: for the drive in order to search the file or 
  5752.     directory on the boot drive. 
  5753.  
  5754.     The name may not include wildcards. 
  5755.  
  5756.  
  5757. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameter pszEaName ΓòÉΓòÉΓòÉ
  5758.  
  5759. pszEaName (PSZ) - input 
  5760.     Address of the ASCIIZ name of the extended attribute. 
  5761.  
  5762.  
  5763. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameter ulMultiType ΓòÉΓòÉΓòÉ
  5764.  
  5765. ulMultiType (ULONG) - input 
  5766.     Multitype of the value to be added to the extended attribute. 
  5767.  
  5768.     Specify 
  5769.  
  5770.     EAT_MVST 
  5771.               to add a value to a multi value, single type extended attribute. 
  5772.               This only works, if this is the first value being appended or the 
  5773.               existing extended attribute is already multi value, single type, 
  5774.               and ulEaType is of the same type as the existing value(s). 
  5775.     EAT_MVMT 
  5776.               to add a value to a multi value, multi type extended attribute. 
  5777.               This only works, if this is the first value being appended or the 
  5778.               existing extended attribute is already multi value, multi type. 
  5779.     Other EAT_* 
  5780.               to add a value to a single value, single type extended attribute 
  5781.               This only works, if this is the first value being appended, 
  5782.               otherwise it would not be single value, single type ... 
  5783.  
  5784.  
  5785. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameter ulEaType ΓòÉΓòÉΓòÉ
  5786.  
  5787. ulEaType (ULONG) - input 
  5788.     Type of the value to be added to the extended attribute. 
  5789.  
  5790.     Specify 
  5791.  
  5792.     EAT_ASCII 
  5793.               to add a string value 
  5794.     EAT_BINARY 
  5795.               to add a binary value 
  5796.     EAT_ICON 
  5797.               to add an icon 
  5798.     EAT_BITMAP 
  5799.               to add a bitmap 
  5800.     EAT_METAFILE 
  5801.               to add a meta file 
  5802.     EAT_EA 
  5803.               to add the name of an embedded extended attribute as an ASCII 
  5804.               string 
  5805.  
  5806.  
  5807. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameter pbValue ΓòÉΓòÉΓòÉ
  5808.  
  5809. pbValue (PBYTE) - input 
  5810.     The address of a buffer of the value to be written. 
  5811.  
  5812.  
  5813. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameter ulValuelen ΓòÉΓòÉΓòÉ
  5814.  
  5815. ulValuelen (ULONG) - input 
  5816.     The length, in bytes, of the buffer described by pbValue. 
  5817.  
  5818.  
  5819. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameter fWriteThru ΓòÉΓòÉΓòÉ
  5820.  
  5821. fWriteThru (BOOL) - input 
  5822.     A flag to bypass the cache and write the extended attribute directly to 
  5823.     disk. 
  5824.  
  5825.  
  5826. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameter fEA ΓòÉΓòÉΓòÉ
  5827.  
  5828. fEA (BYTE) - input 
  5829.     The flags to be set for this extended attribute flags. 
  5830.  
  5831.     Specify FEA_NEEDEDEA in order to mark the extended attribute as critical. 
  5832.     Otherwise set this parameter to zero. 
  5833.  
  5834.  
  5835. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Parameters ΓòÉΓòÉΓòÉ
  5836.  
  5837. pszName (PSZ) - input 
  5838.     Address of the ASCIIZ path name of the file or directory. 
  5839.  
  5840.     The path name may contain ?: for the drive in order to search the file or 
  5841.     directory on the boot drive. 
  5842.  
  5843.     The name may not include wildcards. 
  5844.  
  5845.  pszEaName (PSZ) - input 
  5846.     Address of the ASCIIZ name of the extended attribute. 
  5847.  
  5848.  ulMultiType (ULONG) - input 
  5849.     Multitype of the value to be added to the extended attribute. 
  5850.  
  5851.     Specify 
  5852.  
  5853.     EAT_MVST 
  5854.               to add a value to a multi value, single type extended attribute. 
  5855.               This only works, if this is the first value being appended or the 
  5856.               existing extended attribute is already multi value, single type, 
  5857.               and ulEaType is of the same type as the existing value(s). 
  5858.     EAT_MVMT 
  5859.               to add a value to a multi value, multi type extended attribute. 
  5860.               This only works, if this is the first value being appended or the 
  5861.               existing extended attribute is already multi value, multi type. 
  5862.     Other EAT_* 
  5863.               to add a value to a single value, single type extended attribute 
  5864.               This only works, if this is the first value being appended, 
  5865.               otherwise it would not be single value, single type ... 
  5866.  
  5867.  ulEaType (ULONG) - input 
  5868.     Type of the value to be added to the extended attribute. 
  5869.  
  5870.     Specify 
  5871.  
  5872.     EAT_ASCII 
  5873.               to add a string value 
  5874.     EAT_BINARY 
  5875.               to add a binary value 
  5876.     EAT_ICON 
  5877.               to add an icon 
  5878.     EAT_BITMAP 
  5879.               to add a bitmap 
  5880.     EAT_METAFILE 
  5881.               to add a meta file 
  5882.     EAT_EA 
  5883.               to add the name of an embedded extended attribute as an ASCII 
  5884.               string 
  5885.  
  5886.  pbValue (PBYTE) - input 
  5887.     The address of a buffer of the value to be written. 
  5888.  
  5889.  ulValuelen (ULONG) - input 
  5890.     The length, in bytes, of the buffer described by pbValue. 
  5891.  
  5892.  fWriteThru (BOOL) - input 
  5893.     A flag to bypass the cache and write the extended attribute directly to 
  5894.     disk. 
  5895.  
  5896.  fEA (BYTE) - input 
  5897.     The flags to be set for this extended attribute flags. 
  5898.  
  5899.     Specify FEA_NEEDEDEA in order to mark the extended attribute as critical. 
  5900.     Otherwise set this parameter to zero. 
  5901.  
  5902.  ulrc (APIRET) - returns 
  5903.     Return Code. 
  5904.  
  5905.     WtkPutEaValue returns one of the following return codes: 
  5906.  
  5907.     0         NO_ERROR 
  5908.     8         ERROR_NOT_ENOUGH_MEMORY 
  5909.     13        ERROR_INVALID_DATA 
  5910.     87        ERROR_INVALID_PARAMETER 
  5911.  
  5912.     or return codes of the following functions 
  5913.  
  5914.         DosSetPathInfo 
  5915.  
  5916.  
  5917. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue Return Value - ulrc ΓòÉΓòÉΓòÉ
  5918.  
  5919. ulrc (APIRET) - returns 
  5920.     Return Code. 
  5921.  
  5922.     WtkPutEaValue returns one of the following return codes: 
  5923.  
  5924.     0         NO_ERROR 
  5925.     8         ERROR_NOT_ENOUGH_MEMORY 
  5926.     13        ERROR_INVALID_DATA 
  5927.     87        ERROR_INVALID_PARAMETER 
  5928.  
  5929.     or return codes of the following functions 
  5930.  
  5931.         DosSetPathInfo 
  5932.  
  5933.  
  5934. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Remarks ΓòÉΓòÉΓòÉ
  5935.  
  5936. This function supports boot drive recognition. Specify ?: for the drive in 
  5937. order to open the file or directory on the boot drive. 
  5938.  
  5939. This function is meant to provide you with easy handling of extended 
  5940. attributes. Instead of calling WtkCreateEa / WtkReadEa / WtkAppendEaValue / 
  5941. WtkSaveEa / WtkCloseEa, you can directly append a value to an extended 
  5942. attribute by just calling WtkPutEaValue. 
  5943.  
  5944. The drawback is, that if you are required to append several values, each call 
  5945. needs to read the existing values for the given extended attribute again from 
  5946. disk in order to he list of values. 
  5947.  
  5948. This is not that important, if you do not query a lot of extended attributes of 
  5949. a lot of files at one time, as extended attributes can of course be cached, 
  5950. provided that you did not set fWriteThru to TRUE. In that case, from the second 
  5951. call of WtkPutEaValue this is most likely a in-memory operation. 
  5952.  
  5953. Nevertheless, if you handle very large lists of values for a given extended 
  5954. attribute, or you want to bypass the cache, it is faster to use the WtkCreateEa 
  5955. / WtkReadEa / WtkAppendEaValue / WtkSaveEa / WtkCloseEa functions and thus 
  5956. write to the disk only once. 
  5957.  
  5958.  
  5959. ΓòÉΓòÉΓòÉ <hidden> WtkPutEaValue - Related functions ΓòÉΓòÉΓòÉ
  5960.  
  5961. Related Functions 
  5962.  
  5963. none 
  5964.  
  5965.  
  5966. ΓòÉΓòÉΓòÉ 8.47. WtkQueryBootDrive ΓòÉΓòÉΓòÉ
  5967.  
  5968. Select an item: 
  5969.  
  5970.      Syntax 
  5971.      Parameters 
  5972.      Returns 
  5973.      Remarks 
  5974.      Related Functions 
  5975.  
  5976.  
  5977. ΓòÉΓòÉΓòÉ <hidden> WtkQueryBootDrive - Syntax ΓòÉΓòÉΓòÉ
  5978.  
  5979. This function returns the ASCII value of the drive, where the operating system 
  5980. was started from. 
  5981.  
  5982. #define INCL_WTKUTLSYSTEM
  5983. #include <wpstk.h>
  5984.  
  5985. CHAR   chResult;   /* ASCII value of the letter from the drive, where the operating system was started from.  */
  5986.  
  5987. chResult = WtkQueryBootDrive();
  5988.  
  5989.  
  5990. ΓòÉΓòÉΓòÉ <hidden> WtkQueryBootDrive - Parameters ΓòÉΓòÉΓòÉ
  5991.  
  5992. chResult (CHAR) - returns 
  5993.     ASCII value of the letter from the drive, where the operating system was 
  5994.     started from. 
  5995.  
  5996.  
  5997. ΓòÉΓòÉΓòÉ <hidden> WtkQueryBootDrive Return Value - chResult ΓòÉΓòÉΓòÉ
  5998.  
  5999. chResult (CHAR) - returns 
  6000.     ASCII value of the letter from the drive, where the operating system was 
  6001.     started from. 
  6002.  
  6003.  
  6004. ΓòÉΓòÉΓòÉ <hidden> WtkQueryBootDrive - Remarks ΓòÉΓòÉΓòÉ
  6005.  
  6006. This function is intended as an easier way to query the boot drive compared to 
  6007. the conventiuonal method using DosQuerySysValue Using WtkQueryBootDrive instead 
  6008. allows to embedd the query for a boot drive in another function call, like for 
  6009. example: 
  6010.  
  6011. sprintf( szSyslevelFilename, "?:\\OS2\\SYSTEM\\SYSLEVEL.OS2", WtkQueryBootDrive());
  6012.  
  6013. Note however that when using file related functions of the Workplace Shell 
  6014. Toolkit this is not required, as all of these allow to specify ?: as a 
  6015. placeholder for the boot drive within file- and/or pathname specifications. 
  6016.  
  6017.  
  6018. ΓòÉΓòÉΓòÉ <hidden> WtkQueryBootDrive - Related functions ΓòÉΓòÉΓòÉ
  6019.  
  6020. Related Functions 
  6021.  
  6022. none 
  6023.  
  6024.  
  6025. ΓòÉΓòÉΓòÉ 8.48. WtkQueryCDateTimeStamp ΓòÉΓòÉΓòÉ
  6026.  
  6027. Select an item: 
  6028.  
  6029.      Syntax 
  6030.      Parameters 
  6031.      Returns 
  6032.      Remarks 
  6033.      Related Functions 
  6034.  
  6035.  
  6036. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Syntax ΓòÉΓòÉΓòÉ
  6037.  
  6038. This function determines a timestamp according to the values of a CDATE and 
  6039. CTIME structure. 
  6040.  
  6041. #define INCL_WTKUTLTIME
  6042. #include <wpstk.h>
  6043.  
  6044. PCDATE   pcdate;        /* Address of the CDATE structure.                                                                                                   */
  6045. PCTIME   pctime;        /* Address of the CTIME structure.                                                                                                   */
  6046. ULONG    ulStampType;   /* Type of timestamp.                                                                                                                */
  6047. PSZ      pszBuffer;     /* The address of a buffer, into which the timestamp is returned.                                                                    */
  6048. ULONG    ulBuflen;      /* The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes.             */
  6049. APIRET   ulrc;          /* Return Code.                                                                                                                      */
  6050.  
  6051. ulrc = WtkQueryCDateTimeStamp( pcdate, pctime, ulStampType, pszBuffer, ulBuflen);
  6052.  
  6053.  
  6054. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Parameter pcdate ΓòÉΓòÉΓòÉ
  6055.  
  6056. pcdate (PCDATE) - input 
  6057.     Address of the CDATE structure. 
  6058.  
  6059.  
  6060. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Parameter pctime ΓòÉΓòÉΓòÉ
  6061.  
  6062. pctime (PCTIME) - input 
  6063.     Address of the CTIME structure. 
  6064.  
  6065.  
  6066. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Parameter ulStampType ΓòÉΓòÉΓòÉ
  6067.  
  6068. ulStampType (ULONG) - input 
  6069.     Type of timestamp. 
  6070.  
  6071.     WTK_TIMESTAMP_SORTEDDATETIME 
  6072.               returns a sorted date and timestamp in yyyymmddhhmmss 
  6073.  
  6074.     WTK_TIMESTAMP_SORTEDDATE 
  6075.               returns a sorted datestamp in yyyymmdd 
  6076.  
  6077.     WTK_TIMESTAMP_SORTEDTIME 
  6078.               returns a sorted timestamp in hhmmss 
  6079.  
  6080.     WTK_TIMESTAMP_NLSDATETIME 
  6081.               returns a NLS compliant date and timestamp 
  6082.  
  6083.     WTK_TIMESTAMP_NLSDATE 
  6084.               returns a NLS compliant datestamp 
  6085.  
  6086.     WTK_TIMESTAMP_NLSTIME 
  6087.               returns a NLS compliant timestamp 
  6088.  
  6089.  
  6090. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  6091.  
  6092. pszBuffer (PSZ) - output 
  6093.     The address of a buffer, into which the timestamp is returned. 
  6094.  
  6095.  
  6096. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  6097.  
  6098. ulBuflen (ULONG) - input 
  6099.     The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 
  6100.     bytes of size should fit for all purposes. 
  6101.  
  6102.  
  6103. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Parameters ΓòÉΓòÉΓòÉ
  6104.  
  6105. pcdate (PCDATE) - input 
  6106.     Address of the CDATE structure. 
  6107.  
  6108.  pctime (PCTIME) - input 
  6109.     Address of the CTIME structure. 
  6110.  
  6111.  ulStampType (ULONG) - input 
  6112.     Type of timestamp. 
  6113.  
  6114.     WTK_TIMESTAMP_SORTEDDATETIME 
  6115.               returns a sorted date and timestamp in yyyymmddhhmmss 
  6116.  
  6117.     WTK_TIMESTAMP_SORTEDDATE 
  6118.               returns a sorted datestamp in yyyymmdd 
  6119.  
  6120.     WTK_TIMESTAMP_SORTEDTIME 
  6121.               returns a sorted timestamp in hhmmss 
  6122.  
  6123.     WTK_TIMESTAMP_NLSDATETIME 
  6124.               returns a NLS compliant date and timestamp 
  6125.  
  6126.     WTK_TIMESTAMP_NLSDATE 
  6127.               returns a NLS compliant datestamp 
  6128.  
  6129.     WTK_TIMESTAMP_NLSTIME 
  6130.               returns a NLS compliant timestamp 
  6131.  
  6132.  pszBuffer (PSZ) - output 
  6133.     The address of a buffer, into which the timestamp is returned. 
  6134.  
  6135.  ulBuflen (ULONG) - input 
  6136.     The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 
  6137.     bytes of size should fit for all purposes. 
  6138.  
  6139.  ulrc (APIRET) - returns 
  6140.     Return Code. 
  6141.  
  6142.     WtkQueryCDateTimeStamp returns one of the following return codes: 
  6143.  
  6144.     0         NO_ERROR 
  6145.     87        ERROR_INVALID_PARAMETER 
  6146.     111       ERROR_BUFFER_OVERFLOW 
  6147.  
  6148.     or return codes of the following functions 
  6149.  
  6150.         DosQueryCtryInfo 
  6151.  
  6152.  
  6153. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp Return Value - ulrc ΓòÉΓòÉΓòÉ
  6154.  
  6155. ulrc (APIRET) - returns 
  6156.     Return Code. 
  6157.  
  6158.     WtkQueryCDateTimeStamp returns one of the following return codes: 
  6159.  
  6160.     0         NO_ERROR 
  6161.     87        ERROR_INVALID_PARAMETER 
  6162.     111       ERROR_BUFFER_OVERFLOW 
  6163.  
  6164.     or return codes of the following functions 
  6165.  
  6166.         DosQueryCtryInfo 
  6167.  
  6168.  
  6169. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Remarks ΓòÉΓòÉΓòÉ
  6170.  
  6171. none 
  6172.  
  6173.  
  6174. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCDateTimeStamp - Related functions ΓòÉΓòÉΓòÉ
  6175.  
  6176. Related Functions 
  6177.  
  6178. none 
  6179.  
  6180.  
  6181. ΓòÉΓòÉΓòÉ 8.49. WtkQueryClassDetailsInfo ΓòÉΓòÉΓòÉ
  6182.  
  6183. Select an item: 
  6184.  
  6185.      Syntax 
  6186.      Parameters 
  6187.      Returns 
  6188.      Remarks 
  6189.      Related Functions 
  6190.  
  6191.  
  6192. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo - Syntax ΓòÉΓòÉΓòÉ
  6193.  
  6194. This function is to be called by the override of the method 
  6195. _wpclsQueryDetailsInfo. 
  6196.  
  6197. #define INCL_WTKSETTINGS
  6198. #include <wpstk.h>
  6199.  
  6200. HSETTINGTABLE   hst;                /* Settingstable handle.                                                 */
  6201. PVOID          *ppClassFieldInfo;   /* Adress of the pointer variable to the details info.                   */
  6202. PULONG          pSize;              /* Adress of the size variable of details data.                          */
  6203. ULONG           ulParentColumns;    /* Number of parent columns being already inserted by the parent class.  */
  6204. ULONG           ulResult;           /* Number of total columns including the own ones.                       */
  6205.  
  6206. ulResult = WtkQueryClassDetailsInfo( hst, ppClassFieldInfo, pSize, ulParentColumns);
  6207.  
  6208.  
  6209. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo - Parameter hst ΓòÉΓòÉΓòÉ
  6210.  
  6211. hst (HSETTINGTABLE) - input 
  6212.     Settingstable handle. 
  6213.  
  6214.  
  6215. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo - Parameter ppClassFieldInfo ΓòÉΓòÉΓòÉ
  6216.  
  6217. ppClassFieldInfo (PVOID*) - input 
  6218.     Adress of the pointer variable to the details info. 
  6219.  
  6220.  
  6221. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo - Parameter pSize ΓòÉΓòÉΓòÉ
  6222.  
  6223. pSize (PULONG) - input 
  6224.     Adress of the size variable of details data. 
  6225.  
  6226.  
  6227. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo - Parameter ulParentColumns ΓòÉΓòÉΓòÉ
  6228.  
  6229. ulParentColumns (ULONG) - input 
  6230.     Number of parent columns being already inserted by the parent class. 
  6231.  
  6232.  
  6233. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo - Parameters ΓòÉΓòÉΓòÉ
  6234.  
  6235. hst (HSETTINGTABLE) - input 
  6236.     Settingstable handle. 
  6237.  
  6238.  ppClassFieldInfo (PVOID*) - input 
  6239.     Adress of the pointer variable to the details info. 
  6240.  
  6241.  pSize (PULONG) - input 
  6242.     Adress of the size variable of details data. 
  6243.  
  6244.  ulParentColumns (ULONG) - input 
  6245.     Number of parent columns being already inserted by the parent class. 
  6246.  
  6247.  ulResult (ULONG) - returns 
  6248.     Number of total columns including the own ones. 
  6249.  
  6250.  
  6251. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo Return Value - ulResult ΓòÉΓòÉΓòÉ
  6252.  
  6253. ulResult (ULONG) - returns 
  6254.     Number of total columns including the own ones. 
  6255.  
  6256.  
  6257. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo - Remarks ΓòÉΓòÉΓòÉ
  6258.  
  6259. This function can be called as follows during _wpclsQueryDetailsInfo to 
  6260. automatically setup the details info: 
  6261.  
  6262. return WtkQueryClassDetailsInfo(
  6263.    _hst,
  6264.    (PVOID) ppClassFieldInfo,
  6265.    pSize,
  6266.    M_<wps_class>_parent_M_<wps_parent_class>_wpclsQueryDetailsInfo(
  6267.       somSelf,
  6268.       ppClassFieldInfo,
  6269.       pSize));
  6270.  
  6271.  
  6272. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassDetailsInfo - Related functions ΓòÉΓòÉΓòÉ
  6273.  
  6274. Related Functions 
  6275.  
  6276. none 
  6277.  
  6278.  
  6279. ΓòÉΓòÉΓòÉ 8.50. WtkQueryClassIndex ΓòÉΓòÉΓòÉ
  6280.  
  6281. Select an item: 
  6282.  
  6283.      Syntax 
  6284.      Parameters 
  6285.      Returns 
  6286.      Remarks 
  6287.      Related Functions 
  6288.  
  6289.  
  6290. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassIndex - Syntax ΓòÉΓòÉΓòÉ
  6291.  
  6292. This function determines the class index (like WC_*) for public PM classes. 
  6293.  
  6294. #define INCL_WTKUTLCONTROL
  6295. #include <wpstk.h>
  6296.  
  6297. HWND   hwnd;        /* Handle of the window to be examined.  */
  6298. PSZ    pszResult;   /* Class index (like WC_*).              */
  6299.  
  6300. pszResult = WtkQueryClassIndex( hwnd);
  6301.  
  6302.  
  6303. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassIndex - Parameter hwnd ΓòÉΓòÉΓòÉ
  6304.  
  6305. hwnd (HWND) - input 
  6306.     Handle of the window to be examined. 
  6307.  
  6308.  
  6309. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassIndex - Parameters ΓòÉΓòÉΓòÉ
  6310.  
  6311. hwnd (HWND) - input 
  6312.     Handle of the window to be examined. 
  6313.  
  6314.  pszResult (PSZ) - returns 
  6315.     Class index (like WC_*). 
  6316.  
  6317.     NULLHANDLE 
  6318.               the class index could not be obtained or the class is not a 
  6319.               public PM class. 
  6320.  
  6321.     other 
  6322.               class index (like WC_*) 
  6323.  
  6324.     Extended error information can be obtained using 
  6325.     WinGetLastError/WinGetErrorInfo. 
  6326.  
  6327.  
  6328. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassIndex Return Value - pszResult ΓòÉΓòÉΓòÉ
  6329.  
  6330. pszResult (PSZ) - returns 
  6331.     Class index (like WC_*). 
  6332.  
  6333.     NULLHANDLE 
  6334.               the class index could not be obtained or the class is not a 
  6335.               public PM class. 
  6336.  
  6337.     other 
  6338.               class index (like WC_*) 
  6339.  
  6340.     Extended error information can be obtained using 
  6341.     WinGetLastError/WinGetErrorInfo. 
  6342.  
  6343.  
  6344. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassIndex - Remarks ΓòÉΓòÉΓòÉ
  6345.  
  6346. The class index can only be queried for public PM classes, that is, classes, 
  6347. that return "#n" as the PM class name, where n is a number. 
  6348. Your application may register private PM classes compliant to that name scheme 
  6349. with an unused number, so that this function can be used anyway. 
  6350.  
  6351. In order to use the resulting PSZ value in a switch statement, precede both the 
  6352. switch variable and the case values with (const). 
  6353.  
  6354.  
  6355. ΓòÉΓòÉΓòÉ <hidden> WtkQueryClassIndex - Related functions ΓòÉΓòÉΓòÉ
  6356.  
  6357. Related Functions 
  6358.  
  6359. none 
  6360.  
  6361.  
  6362. ΓòÉΓòÉΓòÉ 8.51. WtkQueryCurrentDir ΓòÉΓòÉΓòÉ
  6363.  
  6364. Select an item: 
  6365.  
  6366.      Syntax 
  6367.      Parameters 
  6368.      Returns 
  6369.      Remarks 
  6370.      Related Functions 
  6371.  
  6372.  
  6373. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCurrentDir - Syntax ΓòÉΓòÉΓòÉ
  6374.  
  6375. This function queries the current drive and directory for a given drive. 
  6376.  
  6377. #define INCL_WTKUTLFILE
  6378. #include <wpstk.h>
  6379.  
  6380. ULONG    ulDiskNum;   /* The drive number.                                                                                      */
  6381. PSZ      pszBuffer;   /* Address of a buffer, where the given drive and the current directory of that drive is being returned.  */
  6382. ULONG    ulBuflen;    /* The length, in bytes, of the buffer described by pszBuffer.                                            */
  6383. APIRET   ulrc;        /* Return Code.                                                                                           */
  6384.  
  6385. ulrc = WtkQueryCurrentDir( ulDiskNum, pszBuffer, ulBuflen);
  6386.  
  6387.  
  6388. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCurrentDir - Parameter ulDiskNum ΓòÉΓòÉΓòÉ
  6389.  
  6390. ulDiskNum (ULONG) - input 
  6391.     The drive number. 
  6392.  
  6393.     The value 0 means the current drive, 1 means drive A, 2 means drive B, 3 
  6394.     means drive C, and so on. The maximum possible value is 26, which 
  6395.     corresponds to drive Z. 
  6396.  
  6397.  
  6398. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCurrentDir - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  6399.  
  6400. pszBuffer (PSZ) - output 
  6401.     Address of a buffer, where the given drive and the current directory of 
  6402.     that drive is being returned. 
  6403.  
  6404.  
  6405. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCurrentDir - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  6406.  
  6407. ulBuflen (ULONG) - input 
  6408.     The length, in bytes, of the buffer described by pszBuffer. 
  6409.  
  6410.  
  6411. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCurrentDir - Parameters ΓòÉΓòÉΓòÉ
  6412.  
  6413. ulDiskNum (ULONG) - input 
  6414.     The drive number. 
  6415.  
  6416.     The value 0 means the current drive, 1 means drive A, 2 means drive B, 3 
  6417.     means drive C, and so on. The maximum possible value is 26, which 
  6418.     corresponds to drive Z. 
  6419.  
  6420.  pszBuffer (PSZ) - output 
  6421.     Address of a buffer, where the given drive and the current directory of 
  6422.     that drive is being returned. 
  6423.  
  6424.  ulBuflen (ULONG) - input 
  6425.     The length, in bytes, of the buffer described by pszBuffer. 
  6426.  
  6427.  ulrc (APIRET) - returns 
  6428.     Return Code. 
  6429.  
  6430.     WtkQueryCurrentDir returns one of the following return codes: 
  6431.  
  6432.     0         NO_ERROR 
  6433.     87        ERROR_INVALID_PARAMETER 
  6434.     111       ERROR_BUFFER_OVERFLOW 
  6435.  
  6436.     or return codes of the following functions 
  6437.  
  6438.         DosQueryCurrentDisk 
  6439.         DosQueryCurrentDir 
  6440.  
  6441.  
  6442. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCurrentDir Return Value - ulrc ΓòÉΓòÉΓòÉ
  6443.  
  6444. ulrc (APIRET) - returns 
  6445.     Return Code. 
  6446.  
  6447.     WtkQueryCurrentDir returns one of the following return codes: 
  6448.  
  6449.     0         NO_ERROR 
  6450.     87        ERROR_INVALID_PARAMETER 
  6451.     111       ERROR_BUFFER_OVERFLOW 
  6452.  
  6453.     or return codes of the following functions 
  6454.  
  6455.         DosQueryCurrentDisk 
  6456.         DosQueryCurrentDir 
  6457.  
  6458.  
  6459. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCurrentDir - Remarks ΓòÉΓòÉΓòÉ
  6460.  
  6461. In opposite to DosQueryCurrentDir, this function returns both the drive and 
  6462. directory, thus providing a full pathname. 
  6463.  
  6464.  
  6465. ΓòÉΓòÉΓòÉ <hidden> WtkQueryCurrentDir - Related functions ΓòÉΓòÉΓòÉ
  6466.  
  6467. Related Functions 
  6468.  
  6469. none 
  6470.  
  6471.  
  6472. ΓòÉΓòÉΓòÉ 8.52. WtkQueryDateTimeStamp ΓòÉΓòÉΓòÉ
  6473.  
  6474. Select an item: 
  6475.  
  6476.      Syntax 
  6477.      Parameters 
  6478.      Returns 
  6479.      Remarks 
  6480.      Related Functions 
  6481.  
  6482.  
  6483. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp - Syntax ΓòÉΓòÉΓòÉ
  6484.  
  6485. This function determines a timestamp according to the values of a DATETIME 
  6486. structure. 
  6487.  
  6488. #define INCL_WTKUTLTIME
  6489. #include <wpstk.h>
  6490.  
  6491. PDATETIME   pdt;           /* Address of the DATETIME structure.                                                                                                */
  6492. ULONG       ulStampType;   /* Type of timestamp.                                                                                                                */
  6493. PSZ         pszBuffer;     /* The address of a buffer, into which the timestamp is returned.                                                                    */
  6494. ULONG       ulBuflen;      /* The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes.             */
  6495. APIRET      ulrc;          /* Return Code.                                                                                                                      */
  6496.  
  6497. ulrc = WtkQueryDateTimeStamp( pdt, ulStampType, pszBuffer, ulBuflen);
  6498.  
  6499.  
  6500. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp - Parameter pdt ΓòÉΓòÉΓòÉ
  6501.  
  6502. pdt (PDATETIME) - input 
  6503.     Address of the DATETIME structure. 
  6504.  
  6505.  
  6506. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp - Parameter ulStampType ΓòÉΓòÉΓòÉ
  6507.  
  6508. ulStampType (ULONG) - input 
  6509.     Type of timestamp. 
  6510.  
  6511.     WTK_TIMESTAMP_SORTEDDATETIME 
  6512.               returns a sorted date and timestamp in yyyymmddhhmmss 
  6513.  
  6514.     WTK_TIMESTAMP_SORTEDDATE 
  6515.               returns a sorted datestamp in yyyymmdd 
  6516.  
  6517.     WTK_TIMESTAMP_SORTEDTIME 
  6518.               returns a sorted timestamp in hhmmss 
  6519.  
  6520.     WTK_TIMESTAMP_NLSDATETIME 
  6521.               returns a NLS compliant date and timestamp 
  6522.  
  6523.     WTK_TIMESTAMP_NLSDATE 
  6524.               returns a NLS compliant datestamp 
  6525.  
  6526.     WTK_TIMESTAMP_NLSTIME 
  6527.               returns a NLS compliant timestamp 
  6528.  
  6529.  
  6530. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  6531.  
  6532. pszBuffer (PSZ) - output 
  6533.     The address of a buffer, into which the timestamp is returned. 
  6534.  
  6535.  
  6536. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  6537.  
  6538. ulBuflen (ULONG) - input 
  6539.     The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 
  6540.     bytes of size should fit for all purposes. 
  6541.  
  6542.  
  6543. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp - Parameters ΓòÉΓòÉΓòÉ
  6544.  
  6545. pdt (PDATETIME) - input 
  6546.     Address of the DATETIME structure. 
  6547.  
  6548.  ulStampType (ULONG) - input 
  6549.     Type of timestamp. 
  6550.  
  6551.     WTK_TIMESTAMP_SORTEDDATETIME 
  6552.               returns a sorted date and timestamp in yyyymmddhhmmss 
  6553.  
  6554.     WTK_TIMESTAMP_SORTEDDATE 
  6555.               returns a sorted datestamp in yyyymmdd 
  6556.  
  6557.     WTK_TIMESTAMP_SORTEDTIME 
  6558.               returns a sorted timestamp in hhmmss 
  6559.  
  6560.     WTK_TIMESTAMP_NLSDATETIME 
  6561.               returns a NLS compliant date and timestamp 
  6562.  
  6563.     WTK_TIMESTAMP_NLSDATE 
  6564.               returns a NLS compliant datestamp 
  6565.  
  6566.     WTK_TIMESTAMP_NLSTIME 
  6567.               returns a NLS compliant timestamp 
  6568.  
  6569.  pszBuffer (PSZ) - output 
  6570.     The address of a buffer, into which the timestamp is returned. 
  6571.  
  6572.  ulBuflen (ULONG) - input 
  6573.     The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 
  6574.     bytes of size should fit for all purposes. 
  6575.  
  6576.  ulrc (APIRET) - returns 
  6577.     Return Code. 
  6578.  
  6579.     WtkQueryDateTimeStamp returns one of the following return codes: 
  6580.  
  6581.     0         NO_ERROR 
  6582.     87        ERROR_INVALID_PARAMETER 
  6583.     111       ERROR_BUFFER_OVERFLOW 
  6584.  
  6585.     or return codes of the following functions 
  6586.  
  6587.         DosQueryCtryInfo 
  6588.  
  6589.  
  6590. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp Return Value - ulrc ΓòÉΓòÉΓòÉ
  6591.  
  6592. ulrc (APIRET) - returns 
  6593.     Return Code. 
  6594.  
  6595.     WtkQueryDateTimeStamp returns one of the following return codes: 
  6596.  
  6597.     0         NO_ERROR 
  6598.     87        ERROR_INVALID_PARAMETER 
  6599.     111       ERROR_BUFFER_OVERFLOW 
  6600.  
  6601.     or return codes of the following functions 
  6602.  
  6603.         DosQueryCtryInfo 
  6604.  
  6605.  
  6606. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp - Remarks ΓòÉΓòÉΓòÉ
  6607.  
  6608. none 
  6609.  
  6610.  
  6611. ΓòÉΓòÉΓòÉ <hidden> WtkQueryDateTimeStamp - Related functions ΓòÉΓòÉΓòÉ
  6612.  
  6613. Related Functions 
  6614.  
  6615. none 
  6616.  
  6617.  
  6618. ΓòÉΓòÉΓòÉ 8.53. WtkQueryEaSize ΓòÉΓòÉΓòÉ
  6619.  
  6620. Select an item: 
  6621.  
  6622.      Syntax 
  6623.      Parameters 
  6624.      Returns 
  6625.      Remarks 
  6626.      Related Functions 
  6627.  
  6628.  
  6629. ΓòÉΓòÉΓòÉ <hidden> WtkQueryEaSize - Syntax ΓòÉΓòÉΓòÉ
  6630.  
  6631. This function determines the size of a given extended attribute of a file or 
  6632. directory. 
  6633.  
  6634. #define INCL_WTKEAS
  6635. #include <wpstk.h>
  6636.  
  6637. PSZ      pszName;     /* Address of the ASCIIZ path name of the file or directory.                   */
  6638. PSZ      pszEaName;   /* Address of the ASCIIZ name of the extended attribute.                       */
  6639. PULONG   pulSize;     /* The address of a variable containing the length of the extended attribute.  */
  6640. APIRET   ulrc;        /* Return Code.                                                                */
  6641.  
  6642. ulrc = WtkQueryEaSize( pszName, pszEaName, pulSize);
  6643.  
  6644.  
  6645. ΓòÉΓòÉΓòÉ <hidden> WtkQueryEaSize - Parameter pszName ΓòÉΓòÉΓòÉ
  6646.  
  6647. pszName (PSZ) - input 
  6648.     Address of the ASCIIZ path name of the file or directory. 
  6649.  
  6650.     The path name may contain ?: for the drive in order to open the file or 
  6651.     directory on the boot drive. 
  6652.  
  6653.     The name may not include wildcards. 
  6654.  
  6655.  
  6656. ΓòÉΓòÉΓòÉ <hidden> WtkQueryEaSize - Parameter pszEaName ΓòÉΓòÉΓòÉ
  6657.  
  6658. pszEaName (PSZ) - input 
  6659.     Address of the ASCIIZ name of the extended attribute. 
  6660.  
  6661.  
  6662. ΓòÉΓòÉΓòÉ <hidden> WtkQueryEaSize - Parameter pulSize ΓòÉΓòÉΓòÉ
  6663.  
  6664. pulSize (PULONG) - output 
  6665.     The address of a variable containing the length of the extended attribute. 
  6666.  
  6667.  
  6668. ΓòÉΓòÉΓòÉ <hidden> WtkQueryEaSize - Parameters ΓòÉΓòÉΓòÉ
  6669.  
  6670. pszName (PSZ) - input 
  6671.     Address of the ASCIIZ path name of the file or directory. 
  6672.  
  6673.     The path name may contain ?: for the drive in order to open the file or 
  6674.     directory on the boot drive. 
  6675.  
  6676.     The name may not include wildcards. 
  6677.  
  6678.  pszEaName (PSZ) - input 
  6679.     Address of the ASCIIZ name of the extended attribute. 
  6680.  
  6681.  pulSize (PULONG) - output 
  6682.     The address of a variable containing the length of the extended attribute. 
  6683.  
  6684.  ulrc (APIRET) - returns 
  6685.     Return Code. 
  6686.  
  6687.     WtkQueryEaSize returns one of the following return codes: 
  6688.  
  6689.     0         NO_ERROR 
  6690.     87        ERROR_INVALID_PARAMETER 
  6691.  
  6692.     or return codes of the following functions 
  6693.  
  6694.         DosQueryPathInfo 
  6695.  
  6696.  
  6697. ΓòÉΓòÉΓòÉ <hidden> WtkQueryEaSize Return Value - ulrc ΓòÉΓòÉΓòÉ
  6698.  
  6699. ulrc (APIRET) - returns 
  6700.     Return Code. 
  6701.  
  6702.     WtkQueryEaSize returns one of the following return codes: 
  6703.  
  6704.     0         NO_ERROR 
  6705.     87        ERROR_INVALID_PARAMETER 
  6706.  
  6707.     or return codes of the following functions 
  6708.  
  6709.         DosQueryPathInfo 
  6710.  
  6711.  
  6712. ΓòÉΓòÉΓòÉ <hidden> WtkQueryEaSize - Remarks ΓòÉΓòÉΓòÉ
  6713.  
  6714. This function supports boot drive recognition. Specify ?: for the drive in 
  6715. order to open the file or directory on the boot drive. 
  6716.  
  6717.  
  6718. ΓòÉΓòÉΓòÉ <hidden> WtkQueryEaSize - Related functions ΓòÉΓòÉΓòÉ
  6719.  
  6720. Related Functions 
  6721.  
  6722. none 
  6723.  
  6724.  
  6725. ΓòÉΓòÉΓòÉ 8.54. WtkQueryFDateTimeStamp ΓòÉΓòÉΓòÉ
  6726.  
  6727. Select an item: 
  6728.  
  6729.      Syntax 
  6730.      Parameters 
  6731.      Returns 
  6732.      Remarks 
  6733.      Related Functions 
  6734.  
  6735.  
  6736. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Syntax ΓòÉΓòÉΓòÉ
  6737.  
  6738. This function determines a timestamp according to the values of a FDATE and 
  6739. FTIME structure. 
  6740.  
  6741. #define INCL_WTKUTLTIME
  6742. #include <wpstk.h>
  6743.  
  6744. PFDATE   pfdate;        /* Address of the FDATE structure.                                                                                                   */
  6745. PFTIME   pftime;        /* Address of the FTIME structure.                                                                                                   */
  6746. ULONG    ulStampType;   /* Type of timestamp.                                                                                                                */
  6747. PSZ      pszBuffer;     /* The address of a buffer, into which the timestamp is returned.                                                                    */
  6748. ULONG    ulBuflen;      /* The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 bytes of size should fit for all purposes.             */
  6749. APIRET   ulrc;          /* Return Code.                                                                                                                      */
  6750.  
  6751. ulrc = WtkQueryFDateTimeStamp( pfdate, pftime, ulStampType, pszBuffer, ulBuflen);
  6752.  
  6753.  
  6754. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Parameter pfdate ΓòÉΓòÉΓòÉ
  6755.  
  6756. pfdate (PFDATE) - input 
  6757.     Address of the FDATE structure. 
  6758.  
  6759.  
  6760. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Parameter pftime ΓòÉΓòÉΓòÉ
  6761.  
  6762. pftime (PFTIME) - input 
  6763.     Address of the FTIME structure. 
  6764.  
  6765.  
  6766. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Parameter ulStampType ΓòÉΓòÉΓòÉ
  6767.  
  6768. ulStampType (ULONG) - input 
  6769.     Type of timestamp. 
  6770.  
  6771.     WTK_TIMESTAMP_SORTEDDATETIME 
  6772.               returns a sorted date and timestamp in yyyymmddhhmmss 
  6773.  
  6774.     WTK_TIMESTAMP_SORTEDDATE 
  6775.               returns a sorted datestamp in yyyymmdd 
  6776.  
  6777.     WTK_TIMESTAMP_SORTEDTIME 
  6778.               returns a sorted timestamp in hhmmss 
  6779.  
  6780.     WTK_TIMESTAMP_NLSDATETIME 
  6781.               returns a NLS compliant date and timestamp 
  6782.  
  6783.     WTK_TIMESTAMP_NLSDATE 
  6784.               returns a NLS compliant datestamp 
  6785.  
  6786.     WTK_TIMESTAMP_NLSTIME 
  6787.               returns a NLS compliant timestamp 
  6788.  
  6789.  
  6790. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  6791.  
  6792. pszBuffer (PSZ) - output 
  6793.     The address of a buffer, into which the timestamp is returned. 
  6794.  
  6795.  
  6796. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  6797.  
  6798. ulBuflen (ULONG) - input 
  6799.     The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 
  6800.     bytes of size should fit for all purposes. 
  6801.  
  6802.  
  6803. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Parameters ΓòÉΓòÉΓòÉ
  6804.  
  6805. pfdate (PFDATE) - input 
  6806.     Address of the FDATE structure. 
  6807.  
  6808.  pftime (PFTIME) - input 
  6809.     Address of the FTIME structure. 
  6810.  
  6811.  ulStampType (ULONG) - input 
  6812.     Type of timestamp. 
  6813.  
  6814.     WTK_TIMESTAMP_SORTEDDATETIME 
  6815.               returns a sorted date and timestamp in yyyymmddhhmmss 
  6816.  
  6817.     WTK_TIMESTAMP_SORTEDDATE 
  6818.               returns a sorted datestamp in yyyymmdd 
  6819.  
  6820.     WTK_TIMESTAMP_SORTEDTIME 
  6821.               returns a sorted timestamp in hhmmss 
  6822.  
  6823.     WTK_TIMESTAMP_NLSDATETIME 
  6824.               returns a NLS compliant date and timestamp 
  6825.  
  6826.     WTK_TIMESTAMP_NLSDATE 
  6827.               returns a NLS compliant datestamp 
  6828.  
  6829.     WTK_TIMESTAMP_NLSTIME 
  6830.               returns a NLS compliant timestamp 
  6831.  
  6832.  pszBuffer (PSZ) - output 
  6833.     The address of a buffer, into which the timestamp is returned. 
  6834.  
  6835.  ulBuflen (ULONG) - input 
  6836.     The length, in bytes, of the buffer described by pszBuffer. A buffer of 32 
  6837.     bytes of size should fit for all purposes. 
  6838.  
  6839.  ulrc (APIRET) - returns 
  6840.     Return Code. 
  6841.  
  6842.     WtkQueryFDateTimeStamp returns one of the following return codes: 
  6843.  
  6844.     0         NO_ERROR 
  6845.     87        ERROR_INVALID_PARAMETER 
  6846.     111       ERROR_BUFFER_OVERFLOW 
  6847.  
  6848.     or return codes of the following functions 
  6849.  
  6850.         DosQueryCtryInfo 
  6851.  
  6852.  
  6853. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp Return Value - ulrc ΓòÉΓòÉΓòÉ
  6854.  
  6855. ulrc (APIRET) - returns 
  6856.     Return Code. 
  6857.  
  6858.     WtkQueryFDateTimeStamp returns one of the following return codes: 
  6859.  
  6860.     0         NO_ERROR 
  6861.     87        ERROR_INVALID_PARAMETER 
  6862.     111       ERROR_BUFFER_OVERFLOW 
  6863.  
  6864.     or return codes of the following functions 
  6865.  
  6866.         DosQueryCtryInfo 
  6867.  
  6868.  
  6869. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Remarks ΓòÉΓòÉΓòÉ
  6870.  
  6871. none 
  6872.  
  6873.  
  6874. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFDateTimeStamp - Related functions ΓòÉΓòÉΓòÉ
  6875.  
  6876. Related Functions 
  6877.  
  6878. none 
  6879.  
  6880.  
  6881. ΓòÉΓòÉΓòÉ 8.55. WtkQueryFileCDateTime ΓòÉΓòÉΓòÉ
  6882.  
  6883. Select an item: 
  6884.  
  6885.      Syntax 
  6886.      Parameters 
  6887.      Returns 
  6888.      Remarks 
  6889.      Related Functions 
  6890.  
  6891.  
  6892. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileCDateTime - Syntax ΓòÉΓòÉΓòÉ
  6893.  
  6894. This function stores the last write date and time info of a file or directory 
  6895. in a CDATE and CTIME structure. 
  6896.  
  6897. #define INCL_WTKUTLTIME
  6898. #include <wpstk.h>
  6899.  
  6900. PCDATE   pcdate;    /* Address of the CDATE structure to setup.                     */
  6901. PCTIME   pctime;    /* Address of the CTIME structure to setup.                     */
  6902. PSZ      pszName;   /* Address of the ASCIIZ path name of the file to be examined.  */
  6903. APIRET   ulrc;      /* Return Code.                                                 */
  6904.  
  6905. ulrc = WtkQueryFileCDateTime( pcdate, pctime, pszName);
  6906.  
  6907.  
  6908. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileCDateTime - Parameter pcdate ΓòÉΓòÉΓòÉ
  6909.  
  6910. pcdate (PCDATE) - output 
  6911.     Address of the CDATE structure to setup. 
  6912.  
  6913.  
  6914. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileCDateTime - Parameter pctime ΓòÉΓòÉΓòÉ
  6915.  
  6916. pctime (PCTIME) - output 
  6917.     Address of the CTIME structure to setup. 
  6918.  
  6919.  
  6920. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileCDateTime - Parameter pszName ΓòÉΓòÉΓòÉ
  6921.  
  6922. pszName (PSZ) - input 
  6923.     Address of the ASCIIZ path name of the file to be examined. 
  6924.  
  6925.     The path name may contain ?: for the drive in order to open the file or 
  6926.     directory on the boot drive. 
  6927.  
  6928.  
  6929. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileCDateTime - Parameters ΓòÉΓòÉΓòÉ
  6930.  
  6931. pcdate (PCDATE) - output 
  6932.     Address of the CDATE structure to setup. 
  6933.  
  6934.  pctime (PCTIME) - output 
  6935.     Address of the CTIME structure to setup. 
  6936.  
  6937.  pszName (PSZ) - input 
  6938.     Address of the ASCIIZ path name of the file to be examined. 
  6939.  
  6940.     The path name may contain ?: for the drive in order to open the file or 
  6941.     directory on the boot drive. 
  6942.  
  6943.  ulrc (APIRET) - returns 
  6944.     Return Code. 
  6945.  
  6946.     WtkQueryFileCDateTime returns one of the following return codes: 
  6947.  
  6948.     0         NO_ERROR 
  6949.     87        ERROR_INVALID_PARAMETER 
  6950.  
  6951.     or return codes of the following functions 
  6952.  
  6953.         DosQueryPathInfo 
  6954.  
  6955.  
  6956. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileCDateTime Return Value - ulrc ΓòÉΓòÉΓòÉ
  6957.  
  6958. ulrc (APIRET) - returns 
  6959.     Return Code. 
  6960.  
  6961.     WtkQueryFileCDateTime returns one of the following return codes: 
  6962.  
  6963.     0         NO_ERROR 
  6964.     87        ERROR_INVALID_PARAMETER 
  6965.  
  6966.     or return codes of the following functions 
  6967.  
  6968.         DosQueryPathInfo 
  6969.  
  6970.  
  6971. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileCDateTime - Remarks ΓòÉΓòÉΓòÉ
  6972.  
  6973. This function supports boot drive recognition. Specify ?: for the drive in 
  6974. order to open the file or directory on the boot drive. 
  6975.  
  6976.  
  6977. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileCDateTime - Related functions ΓòÉΓòÉΓòÉ
  6978.  
  6979. Related Functions 
  6980.  
  6981. none 
  6982.  
  6983.  
  6984. ΓòÉΓòÉΓòÉ 8.56. WtkQueryFileDateTime ΓòÉΓòÉΓòÉ
  6985.  
  6986. Select an item: 
  6987.  
  6988.      Syntax 
  6989.      Parameters 
  6990.      Returns 
  6991.      Remarks 
  6992.      Related Functions 
  6993.  
  6994.  
  6995. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileDateTime - Syntax ΓòÉΓòÉΓòÉ
  6996.  
  6997. This function stores the last write date and time info of a file or directory 
  6998. in a DATETIME structure. 
  6999.  
  7000. #define INCL_WTKUTLTIME
  7001. #include <wpstk.h>
  7002.  
  7003. PDATETIME   pdt;       /* Address of the DATETIME structure to setup.                  */
  7004. PSZ         pszName;   /* Address of the ASCIIZ path name of the file to be examined.  */
  7005. APIRET      ulrc;      /* Return Code.                                                 */
  7006.  
  7007. ulrc = WtkQueryFileDateTime( pdt, pszName);
  7008.  
  7009.  
  7010. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileDateTime - Parameter pdt ΓòÉΓòÉΓòÉ
  7011.  
  7012. pdt (PDATETIME) - output 
  7013.     Address of the DATETIME structure to setup. 
  7014.  
  7015.  
  7016. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileDateTime - Parameter pszName ΓòÉΓòÉΓòÉ
  7017.  
  7018. pszName (PSZ) - input 
  7019.     Address of the ASCIIZ path name of the file to be examined. 
  7020.  
  7021.     The path name may contain ?: for the drive in order to open the file or 
  7022.     directory on the boot drive. 
  7023.  
  7024.  
  7025. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileDateTime - Parameters ΓòÉΓòÉΓòÉ
  7026.  
  7027. pdt (PDATETIME) - output 
  7028.     Address of the DATETIME structure to setup. 
  7029.  
  7030.  pszName (PSZ) - input 
  7031.     Address of the ASCIIZ path name of the file to be examined. 
  7032.  
  7033.     The path name may contain ?: for the drive in order to open the file or 
  7034.     directory on the boot drive. 
  7035.  
  7036.  ulrc (APIRET) - returns 
  7037.     Return Code. 
  7038.  
  7039.     WtkQueryFileDateTime returns one of the following return codes: 
  7040.  
  7041.     0         NO_ERROR 
  7042.     87        ERROR_INVALID_PARAMETER 
  7043.  
  7044.     or return codes of the following functions 
  7045.  
  7046.         DosQueryPathInfo 
  7047.  
  7048.  
  7049. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileDateTime Return Value - ulrc ΓòÉΓòÉΓòÉ
  7050.  
  7051. ulrc (APIRET) - returns 
  7052.     Return Code. 
  7053.  
  7054.     WtkQueryFileDateTime returns one of the following return codes: 
  7055.  
  7056.     0         NO_ERROR 
  7057.     87        ERROR_INVALID_PARAMETER 
  7058.  
  7059.     or return codes of the following functions 
  7060.  
  7061.         DosQueryPathInfo 
  7062.  
  7063.  
  7064. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileDateTime - Remarks ΓòÉΓòÉΓòÉ
  7065.  
  7066. This function supports boot drive recognition. Specify ?: for the drive in 
  7067. order to open the file or directory on the boot drive. 
  7068.  
  7069.  
  7070. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileDateTime - Related functions ΓòÉΓòÉΓòÉ
  7071.  
  7072. Related Functions 
  7073.  
  7074. none 
  7075.  
  7076.  
  7077. ΓòÉΓòÉΓòÉ 8.57. WtkQueryFileFDateTime ΓòÉΓòÉΓòÉ
  7078.  
  7079. Select an item: 
  7080.  
  7081.      Syntax 
  7082.      Parameters 
  7083.      Returns 
  7084.      Remarks 
  7085.      Related Functions 
  7086.  
  7087.  
  7088. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileFDateTime - Syntax ΓòÉΓòÉΓòÉ
  7089.  
  7090. This function stores the last write date and time info of a file or directory 
  7091. in a FDATE and FTIME structure. 
  7092.  
  7093. #define INCL_WTKUTLTIME
  7094. #include <wpstk.h>
  7095.  
  7096. PFDATE   pfdate;    /* Address of the FDATE structure to setup.                     */
  7097. PFTIME   pftime;    /* Address of the FTIME structure to setup.                     */
  7098. PSZ      pszName;   /* Address of the ASCIIZ path name of the file to be examined.  */
  7099. APIRET   ulrc;      /* Return Code.                                                 */
  7100.  
  7101. ulrc = WtkQueryFileFDateTime( pfdate, pftime, pszName);
  7102.  
  7103.  
  7104. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileFDateTime - Parameter pfdate ΓòÉΓòÉΓòÉ
  7105.  
  7106. pfdate (PFDATE) - output 
  7107.     Address of the FDATE structure to setup. 
  7108.  
  7109.  
  7110. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileFDateTime - Parameter pftime ΓòÉΓòÉΓòÉ
  7111.  
  7112. pftime (PFTIME) - output 
  7113.     Address of the FTIME structure to setup. 
  7114.  
  7115.  
  7116. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileFDateTime - Parameter pszName ΓòÉΓòÉΓòÉ
  7117.  
  7118. pszName (PSZ) - input 
  7119.     Address of the ASCIIZ path name of the file to be examined. 
  7120.  
  7121.     The path name may contain ?: for the drive in order to open the file or 
  7122.     directory on the boot drive. 
  7123.  
  7124.  
  7125. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileFDateTime - Parameters ΓòÉΓòÉΓòÉ
  7126.  
  7127. pfdate (PFDATE) - output 
  7128.     Address of the FDATE structure to setup. 
  7129.  
  7130.  pftime (PFTIME) - output 
  7131.     Address of the FTIME structure to setup. 
  7132.  
  7133.  pszName (PSZ) - input 
  7134.     Address of the ASCIIZ path name of the file to be examined. 
  7135.  
  7136.     The path name may contain ?: for the drive in order to open the file or 
  7137.     directory on the boot drive. 
  7138.  
  7139.  ulrc (APIRET) - returns 
  7140.     Return Code. 
  7141.  
  7142.     WtkQueryFileFDateTime returns one of the following return codes: 
  7143.  
  7144.     0         NO_ERROR 
  7145.     87        ERROR_INVALID_PARAMETER 
  7146.  
  7147.     or return codes of the following functions 
  7148.  
  7149.         DosQueryPathInfo 
  7150.  
  7151.  
  7152. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileFDateTime Return Value - ulrc ΓòÉΓòÉΓòÉ
  7153.  
  7154. ulrc (APIRET) - returns 
  7155.     Return Code. 
  7156.  
  7157.     WtkQueryFileFDateTime returns one of the following return codes: 
  7158.  
  7159.     0         NO_ERROR 
  7160.     87        ERROR_INVALID_PARAMETER 
  7161.  
  7162.     or return codes of the following functions 
  7163.  
  7164.         DosQueryPathInfo 
  7165.  
  7166.  
  7167. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileFDateTime - Remarks ΓòÉΓòÉΓòÉ
  7168.  
  7169. This function supports boot drive recognition. Specify ?: for the drive in 
  7170. order to open the file or directory on the boot drive. 
  7171.  
  7172.  
  7173. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileFDateTime - Related functions ΓòÉΓòÉΓòÉ
  7174.  
  7175. Related Functions 
  7176.  
  7177. none 
  7178.  
  7179.  
  7180. ΓòÉΓòÉΓòÉ 8.58. WtkQueryFileSize ΓòÉΓòÉΓòÉ
  7181.  
  7182. Select an item: 
  7183.  
  7184.      Syntax 
  7185.      Parameters 
  7186.      Returns 
  7187.      Remarks 
  7188.      Related Functions 
  7189.  
  7190.  
  7191. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileSize - Syntax ΓòÉΓòÉΓòÉ
  7192.  
  7193. This function returns the size of a given file. 
  7194.  
  7195. #define INCL_WTKUTLFILE
  7196. #include <wpstk.h>
  7197.  
  7198. PSZ     pszName;    /* Address of the ASCIIZ path name of the file or directory, which size is to be returned.  */
  7199. ULONG   ulResult;   /* Length of file.                                                                          */
  7200.  
  7201. ulResult = WtkQueryFileSize( pszName);
  7202.  
  7203.  
  7204. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileSize - Parameter pszName ΓòÉΓòÉΓòÉ
  7205.  
  7206. pszName (PSZ) - input 
  7207.     Address of the ASCIIZ path name of the file or directory, which size is to 
  7208.     be returned. 
  7209.  
  7210.     The path name may contain ?: for the drive in order to search the file on 
  7211.     the boot drive. 
  7212.  
  7213.  
  7214. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileSize - Parameters ΓòÉΓòÉΓòÉ
  7215.  
  7216. pszName (PSZ) - input 
  7217.     Address of the ASCIIZ path name of the file or directory, which size is to 
  7218.     be returned. 
  7219.  
  7220.     The path name may contain ?: for the drive in order to search the file on 
  7221.     the boot drive. 
  7222.  
  7223.  ulResult (ULONG) - returns 
  7224.     Length of file. 
  7225.  
  7226.     Zero 
  7227.               File is of zero length or does not exist. 
  7228.     Other 
  7229.               Size of the file. 
  7230.  
  7231.  
  7232. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileSize Return Value - ulResult ΓòÉΓòÉΓòÉ
  7233.  
  7234. ulResult (ULONG) - returns 
  7235.     Length of file. 
  7236.  
  7237.     Zero 
  7238.               File is of zero length or does not exist. 
  7239.     Other 
  7240.               Size of the file. 
  7241.  
  7242.  
  7243. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileSize - Remarks ΓòÉΓòÉΓòÉ
  7244.  
  7245. This function supports boot drive recognition. Specify ?: for the drive in 
  7246. order to search the file on the boot drive. 
  7247.  
  7248.  
  7249. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFileSize - Related functions ΓòÉΓòÉΓòÉ
  7250.  
  7251. Related Functions 
  7252.  
  7253. none 
  7254.  
  7255.  
  7256. ΓòÉΓòÉΓòÉ 8.59. WtkQueryFullname ΓòÉΓòÉΓòÉ
  7257.  
  7258. Select an item: 
  7259.  
  7260.      Syntax 
  7261.      Parameters 
  7262.      Returns 
  7263.      Remarks 
  7264.      Related Functions 
  7265.  
  7266.  
  7267. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFullname - Syntax ΓòÉΓòÉΓòÉ
  7268.  
  7269. This function queries the full name of a file or directory. 
  7270.  
  7271. #define INCL_WTKUTLFILE
  7272. #include <wpstk.h>
  7273.  
  7274. PSZ      pszName;     /* Address of the ASCIIZ path name of the file or direcory.                                         */
  7275. PSZ      pszBuffer;   /* The address of a buffer in into which the full name of the given file or directory is returned.  */
  7276. ULONG    ulBuflen;    /* The length, in bytes, of the buffer described by pszBuffer.                                      */
  7277. APIRET   ulrc;        /* Return Code.                                                                                     */
  7278.  
  7279. ulrc = WtkQueryFullname( pszName, pszBuffer, ulBuflen);
  7280.  
  7281.  
  7282. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFullname - Parameter pszName ΓòÉΓòÉΓòÉ
  7283.  
  7284. pszName (PSZ) - input 
  7285.     Address of the ASCIIZ path name of the file or direcory. 
  7286.  
  7287.     The path name may contain ?: for the drive in order to search the file on 
  7288.     the boot drive. 
  7289.  
  7290.     The name may include wildcards. 
  7291.  
  7292.  
  7293. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFullname - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  7294.  
  7295. pszBuffer (PSZ) - output 
  7296.     The address of a buffer in into which the full name of the given file or 
  7297.     directory is returned. 
  7298.  
  7299.  
  7300. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFullname - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  7301.  
  7302. ulBuflen (ULONG) - input 
  7303.     The length, in bytes, of the buffer described by pszBuffer. 
  7304.  
  7305.  
  7306. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFullname - Parameters ΓòÉΓòÉΓòÉ
  7307.  
  7308. pszName (PSZ) - input 
  7309.     Address of the ASCIIZ path name of the file or direcory. 
  7310.  
  7311.     The path name may contain ?: for the drive in order to search the file on 
  7312.     the boot drive. 
  7313.  
  7314.     The name may include wildcards. 
  7315.  
  7316.  pszBuffer (PSZ) - output 
  7317.     The address of a buffer in into which the full name of the given file or 
  7318.     directory is returned. 
  7319.  
  7320.  ulBuflen (ULONG) - input 
  7321.     The length, in bytes, of the buffer described by pszBuffer. 
  7322.  
  7323.  ulrc (APIRET) - returns 
  7324.     Return Code. 
  7325.  
  7326.     WtkQueryFullname returns one of the following return codes: 
  7327.  
  7328.     0         NO_ERROR 
  7329.     87        ERROR_INVALID_PARAMETER 
  7330.     111       ERROR_BUFFER_OVERFLOW 
  7331.  
  7332.     or return codes of the following functions 
  7333.  
  7334.         DosQueryPathInfo 
  7335.  
  7336.  
  7337. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFullname Return Value - ulrc ΓòÉΓòÉΓòÉ
  7338.  
  7339. ulrc (APIRET) - returns 
  7340.     Return Code. 
  7341.  
  7342.     WtkQueryFullname returns one of the following return codes: 
  7343.  
  7344.     0         NO_ERROR 
  7345.     87        ERROR_INVALID_PARAMETER 
  7346.     111       ERROR_BUFFER_OVERFLOW 
  7347.  
  7348.     or return codes of the following functions 
  7349.  
  7350.         DosQueryPathInfo 
  7351.  
  7352.  
  7353. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFullname - Remarks ΓòÉΓòÉΓòÉ
  7354.  
  7355. This function supports boot drive recognition. Specify ?: for the drive in 
  7356. order to search the file on the boot drive. 
  7357.  
  7358.  
  7359. ΓòÉΓòÉΓòÉ <hidden> WtkQueryFullname - Related functions ΓòÉΓòÉΓòÉ
  7360.  
  7361. Related Functions 
  7362.  
  7363. none 
  7364.  
  7365.  
  7366. ΓòÉΓòÉΓòÉ 8.60. WtkQueryGUIControlsChanged ΓòÉΓòÉΓòÉ
  7367.  
  7368. Select an item: 
  7369.  
  7370.      Syntax 
  7371.      Parameters 
  7372.      Returns 
  7373.      Remarks 
  7374.      Related Functions 
  7375.  
  7376.  
  7377. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Syntax ΓòÉΓòÉΓòÉ
  7378.  
  7379. This function checks a GUI controls of a dialog for changes by examining the 
  7380. parameters of WM_CONTROL messages. 
  7381.  
  7382. #define INCL_WTKSETTINGS
  7383. #include <wpstk.h>
  7384.  
  7385. HVALUETABLE   hvt;          /* Valuetable handle.                                                                       */
  7386. HWND          hwnd;         /* Dialog handle of the settings notebook page.                                             */
  7387. MPARAM        mp1;          /* The message parameter 1 of the WM_CONTROL message.                                       */
  7388. MPARAM        mp2;          /* The message parameter 2 of the WM_CONTROL message.                                       */
  7389. PBOOL         pfOrgValue;   /* Adress of a flag variable indicating if all controls of the dialog have the undo value.  */
  7390. BOOL          fResult;      /* Change indicator.                                                                        */
  7391.  
  7392. fResult = WtkQueryGUIControlsChanged( hvt, hwnd, mp1, mp2, pfOrgValue);
  7393.  
  7394.  
  7395. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Parameter hvt ΓòÉΓòÉΓòÉ
  7396.  
  7397. hvt (HVALUETABLE) - input 
  7398.     Valuetable handle. 
  7399.  
  7400.  
  7401. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Parameter hwnd ΓòÉΓòÉΓòÉ
  7402.  
  7403. hwnd (HWND) - input 
  7404.     Dialog handle of the settings notebook page. 
  7405.  
  7406.  
  7407. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Parameter mp1 ΓòÉΓòÉΓòÉ
  7408.  
  7409. mp1 (MPARAM) - input 
  7410.     The message parameter 1 of the WM_CONTROL message. 
  7411.  
  7412.  
  7413. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Parameter mp2 ΓòÉΓòÉΓòÉ
  7414.  
  7415. mp2 (MPARAM) - input 
  7416.     The message parameter 2 of the WM_CONTROL message. 
  7417.  
  7418.  
  7419. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Parameter pfOrgValue ΓòÉΓòÉΓòÉ
  7420.  
  7421. pfOrgValue (PBOOL) - output 
  7422.     Adress of a flag variable indicating if all controls of the dialog have the 
  7423.     undo value. 
  7424.  
  7425.  
  7426. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Parameters ΓòÉΓòÉΓòÉ
  7427.  
  7428. hvt (HVALUETABLE) - input 
  7429.     Valuetable handle. 
  7430.  
  7431.  hwnd (HWND) - input 
  7432.     Dialog handle of the settings notebook page. 
  7433.  
  7434.  mp1 (MPARAM) - input 
  7435.     The message parameter 1 of the WM_CONTROL message. 
  7436.  
  7437.  mp2 (MPARAM) - input 
  7438.     The message parameter 2 of the WM_CONTROL message. 
  7439.  
  7440.  pfOrgValue (PBOOL) - output 
  7441.     Adress of a flag variable indicating if all controls of the dialog have the 
  7442.     undo value. 
  7443.  
  7444.  fResult (BOOL) - returns 
  7445.     Change indicator. 
  7446.  
  7447.     TRUE 
  7448.               Value has changed 
  7449.     FALSE 
  7450.               Value has not changed 
  7451.  
  7452.  
  7453. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged Return Value - fResult ΓòÉΓòÉΓòÉ
  7454.  
  7455. fResult (BOOL) - returns 
  7456.     Change indicator. 
  7457.  
  7458.     TRUE 
  7459.               Value has changed 
  7460.     FALSE 
  7461.               Value has not changed 
  7462.  
  7463.  
  7464. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Remarks ΓòÉΓòÉΓòÉ
  7465.  
  7466. This function is to be called during WM_CONTROL handling in order to determine 
  7467. wether a GUI control registered with the Settings Manager has changed. 
  7468.  
  7469.  
  7470. ΓòÉΓòÉΓòÉ <hidden> WtkQueryGUIControlsChanged - Related functions ΓòÉΓòÉΓòÉ
  7471.  
  7472. Related Functions 
  7473.  
  7474. none 
  7475.  
  7476.  
  7477. ΓòÉΓòÉΓòÉ 8.61. WtkQueryMmfSize ΓòÉΓòÉΓòÉ
  7478.  
  7479. Select an item: 
  7480.  
  7481.      Syntax 
  7482.      Parameters 
  7483.      Returns 
  7484.      Remarks 
  7485.      Related Functions 
  7486.  
  7487.  
  7488. ΓòÉΓòÉΓòÉ <hidden> WtkQueryMmfSize - Syntax ΓòÉΓòÉΓòÉ
  7489.  
  7490. This function queries the current size of a dynamic memory buffer. 
  7491.  
  7492. #define INCL_WTKMMF
  7493. #include <wpstk.h>
  7494.  
  7495. HMMF     hmmf;      /* Handle to the MMF manager.                                                       */
  7496. PVOID    pvData;    /* Pointer to the allocated address space to be queried.                            */
  7497. PULONG   pulSize;   /* Address of a variable to receive the current size of the dynamic memory buffer.  */
  7498. APIRET   ulrc;      /* Return Code.                                                                     */
  7499.  
  7500. ulrc = WtkQueryMmfSize( hmmf, pvData, pulSize);
  7501.  
  7502.  
  7503. ΓòÉΓòÉΓòÉ <hidden> WtkQueryMmfSize - Parameter hmmf ΓòÉΓòÉΓòÉ
  7504.  
  7505. hmmf (HMMF) - input 
  7506.     Handle to the MMF manager. 
  7507.  
  7508.  
  7509. ΓòÉΓòÉΓòÉ <hidden> WtkQueryMmfSize - Parameter pvData ΓòÉΓòÉΓòÉ
  7510.  
  7511. pvData (PVOID) - input 
  7512.     Pointer to the allocated address space to be queried. 
  7513.  
  7514.  
  7515. ΓòÉΓòÉΓòÉ <hidden> WtkQueryMmfSize - Parameter pulSize ΓòÉΓòÉΓòÉ
  7516.  
  7517. pulSize (PULONG) - output 
  7518.     Address of a variable to receive the current size of the dynamic memory 
  7519.     buffer. 
  7520.  
  7521.  
  7522. ΓòÉΓòÉΓòÉ <hidden> WtkQueryMmfSize - Parameters ΓòÉΓòÉΓòÉ
  7523.  
  7524. hmmf (HMMF) - input 
  7525.     Handle to the MMF manager. 
  7526.  
  7527.  pvData (PVOID) - input 
  7528.     Pointer to the allocated address space to be queried. 
  7529.  
  7530.  pulSize (PULONG) - output 
  7531.     Address of a variable to receive the current size of the dynamic memory 
  7532.     buffer. 
  7533.  
  7534.  ulrc (APIRET) - returns 
  7535.     Return Code. 
  7536.  
  7537.     WtkQueryMmfSize returns one of the following return codes: 
  7538.  
  7539.     0         NO_ERROR 
  7540.     5         ERROR_INVALID_HANDLE 
  7541.     87        ERROR_INVALID_PARAMETER 
  7542.  
  7543.  
  7544. ΓòÉΓòÉΓòÉ <hidden> WtkQueryMmfSize Return Value - ulrc ΓòÉΓòÉΓòÉ
  7545.  
  7546. ulrc (APIRET) - returns 
  7547.     Return Code. 
  7548.  
  7549.     WtkQueryMmfSize returns one of the following return codes: 
  7550.  
  7551.     0         NO_ERROR 
  7552.     5         ERROR_INVALID_HANDLE 
  7553.     87        ERROR_INVALID_PARAMETER 
  7554.  
  7555.  
  7556. ΓòÉΓòÉΓòÉ <hidden> WtkQueryMmfSize - Remarks ΓòÉΓòÉΓòÉ
  7557.  
  7558. This function will return the size of the memory buffer including the last read 
  7559. or written byte. 
  7560.  
  7561.  
  7562. ΓòÉΓòÉΓòÉ <hidden> WtkQueryMmfSize - Related functions ΓòÉΓòÉΓòÉ
  7563.  
  7564. Related Functions 
  7565.  
  7566. none 
  7567.  
  7568.  
  7569. ΓòÉΓòÉΓòÉ 8.62. WtkQueryNumSpinbuttonIndex ΓòÉΓòÉΓòÉ
  7570.  
  7571. Select an item: 
  7572.  
  7573.      Syntax 
  7574.      Parameters 
  7575.      Returns 
  7576.      Remarks 
  7577.      Related Functions 
  7578.  
  7579.  
  7580. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Syntax ΓòÉΓòÉΓòÉ
  7581.  
  7582. This function calculates the array index for a given value for a numeric 
  7583. spinbutton  being initialized with WtkInitializeNumSpinbuttonArray. 
  7584.  
  7585. #define INCL_WTKUTLCONTROL
  7586. #include <wpstk.h>
  7587.  
  7588. HWND    hwndSpinbutton;   /* Handle of the spinbutton window.                     */
  7589. ULONG   ulMinValue;       /* The minimum value of the spinbutton.                 */
  7590. ULONG   ulMaxValue;       /* The maximum value of the spinbutton.                 */
  7591. ULONG   ulStep;           /* The step between the values in the range.            */
  7592. ULONG   ulValue;          /* The value, for which the index shall be calculated.  */
  7593. LONG    lResult;          /* Array Index.                                         */
  7594.  
  7595. lResult = WtkQueryNumSpinbuttonIndex( hwndSpinbutton, ulMinValue, ulMaxValue, ulStep, ulValue);
  7596.  
  7597.  
  7598. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Parameter hwndSpinbutton ΓòÉΓòÉΓòÉ
  7599.  
  7600. hwndSpinbutton (HWND) - input 
  7601.     Handle of the spinbutton window. 
  7602.  
  7603.  
  7604. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Parameter ulMinValue ΓòÉΓòÉΓòÉ
  7605.  
  7606. ulMinValue (ULONG) - input 
  7607.     The minimum value of the spinbutton. 
  7608.  
  7609.     It is required, that the same minimum value is specified here, as it was 
  7610.     when initializing the numeric spinbutton with 
  7611.     WtkInitializeNumSpinbuttonArray, otherwise the array value will be 
  7612.     incorrect. 
  7613.  
  7614.  
  7615. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Parameter ulMaxValue ΓòÉΓòÉΓòÉ
  7616.  
  7617. ulMaxValue (ULONG) - input 
  7618.     The maximum value of the spinbutton. 
  7619.  
  7620.     It is required, that the same maximum value is specified here, as it was 
  7621.     when initializing the numeric spinbutton with 
  7622.     WtkInitializeNumSpinbuttonArray, otherwise the array value will be 
  7623.     incorrect. 
  7624.  
  7625.  
  7626. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Parameter ulStep ΓòÉΓòÉΓòÉ
  7627.  
  7628. ulStep (ULONG) - input 
  7629.     The step between the values in the range. 
  7630.  
  7631.     It is required, that the same step value is specified here, as it was when 
  7632.     initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, 
  7633.     otherwise the array value will be incorrect. 
  7634.  
  7635.  
  7636. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Parameter ulValue ΓòÉΓòÉΓòÉ
  7637.  
  7638. ulValue (ULONG) - input 
  7639.     The value, for which the index shall be calculated. 
  7640.  
  7641.     It is required, that the same maximum value is specified here, as it was 
  7642.     when initializing the numeric spinbutton with 
  7643.     WtkInitializeNumSpinbuttonArray, otherwise the array value will be 
  7644.     incorrect. 
  7645.  
  7646.  
  7647. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Parameters ΓòÉΓòÉΓòÉ
  7648.  
  7649. hwndSpinbutton (HWND) - input 
  7650.     Handle of the spinbutton window. 
  7651.  
  7652.  ulMinValue (ULONG) - input 
  7653.     The minimum value of the spinbutton. 
  7654.  
  7655.     It is required, that the same minimum value is specified here, as it was 
  7656.     when initializing the numeric spinbutton with 
  7657.     WtkInitializeNumSpinbuttonArray, otherwise the array value will be 
  7658.     incorrect. 
  7659.  
  7660.  ulMaxValue (ULONG) - input 
  7661.     The maximum value of the spinbutton. 
  7662.  
  7663.     It is required, that the same maximum value is specified here, as it was 
  7664.     when initializing the numeric spinbutton with 
  7665.     WtkInitializeNumSpinbuttonArray, otherwise the array value will be 
  7666.     incorrect. 
  7667.  
  7668.  ulStep (ULONG) - input 
  7669.     The step between the values in the range. 
  7670.  
  7671.     It is required, that the same step value is specified here, as it was when 
  7672.     initializing the numeric spinbutton with WtkInitializeNumSpinbuttonArray, 
  7673.     otherwise the array value will be incorrect. 
  7674.  
  7675.  ulValue (ULONG) - input 
  7676.     The value, for which the index shall be calculated. 
  7677.  
  7678.     It is required, that the same maximum value is specified here, as it was 
  7679.     when initializing the numeric spinbutton with 
  7680.     WtkInitializeNumSpinbuttonArray, otherwise the array value will be 
  7681.     incorrect. 
  7682.  
  7683.  lResult (LONG) - returns 
  7684.     Array Index. 
  7685.  
  7686.     -1 
  7687.               Array Index could not be calculated or the window is not an array 
  7688.               spinbutton control. 
  7689.     Other 
  7690.               Array index corresponding to the given value. 
  7691.  
  7692.     Extended error information can be obtained using 
  7693.     WinGetLastError/WinGetErrorInfo. 
  7694.  
  7695.  
  7696. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex Return Value - lResult ΓòÉΓòÉΓòÉ
  7697.  
  7698. lResult (LONG) - returns 
  7699.     Array Index. 
  7700.  
  7701.     -1 
  7702.               Array Index could not be calculated or the window is not an array 
  7703.               spinbutton control. 
  7704.     Other 
  7705.               Array index corresponding to the given value. 
  7706.  
  7707.     Extended error information can be obtained using 
  7708.     WinGetLastError/WinGetErrorInfo. 
  7709.  
  7710.  
  7711. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Remarks ΓòÉΓòÉΓòÉ
  7712.  
  7713. This function checks the given window and calculates the index with the 
  7714. following formula: 
  7715.  
  7716. lResult = (ulValue  - ulMinValue ) / ulStep;
  7717.  
  7718. If calculation of the index is performed frequently (whic is mostly not the 
  7719. case), you might want not to use WtkQueryNumSpinbuttonIndex because of 
  7720. performance reasons, but skip the validation and calculate the index yourself. 
  7721.  
  7722.  
  7723. ΓòÉΓòÉΓòÉ <hidden> WtkQueryNumSpinbuttonIndex - Related functions ΓòÉΓòÉΓòÉ
  7724.  
  7725. Related Functions 
  7726.  
  7727. none 
  7728.  
  7729.  
  7730. ΓòÉΓòÉΓòÉ 8.63. WtkQueryObjectDetailsData ΓòÉΓòÉΓòÉ
  7731.  
  7732. Select an item: 
  7733.  
  7734.      Syntax 
  7735.      Parameters 
  7736.      Returns 
  7737.      Remarks 
  7738.      Related Functions 
  7739.  
  7740.  
  7741. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectDetailsData - Syntax ΓòÉΓòÉΓòÉ
  7742.  
  7743. This function is to be called by the override of the method _wpQueryDetailsData 
  7744. to automatically setup the details data. 
  7745.  
  7746. #define INCL_WTKSETTINGS
  7747. #include <wpstk.h>
  7748.  
  7749. HVALUETABLE   hvt;             /* Valuetable handle.                                   */
  7750. PVOID        *ppDetailsData;   /* Adress of the pointer variable to the details data.  */
  7751. PULONG        pcp;             /* Adress of the size variable of details data.         */
  7752. ULONG         ulResult;        /* Success indicator.                                   */
  7753.  
  7754. ulResult = WtkQueryObjectDetailsData( hvt, ppDetailsData, pcp);
  7755.  
  7756.  
  7757. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectDetailsData - Parameter hvt ΓòÉΓòÉΓòÉ
  7758.  
  7759. hvt (HVALUETABLE) - input 
  7760.     Valuetable handle. 
  7761.  
  7762.  
  7763. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectDetailsData - Parameter ppDetailsData ΓòÉΓòÉΓòÉ
  7764.  
  7765. ppDetailsData (PVOID*) - input 
  7766.     Adress of the pointer variable to the details data. 
  7767.  
  7768.  
  7769. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectDetailsData - Parameter pcp ΓòÉΓòÉΓòÉ
  7770.  
  7771. pcp (PULONG) - input 
  7772.     Adress of the size variable of details data. 
  7773.  
  7774.  
  7775. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectDetailsData - Parameters ΓòÉΓòÉΓòÉ
  7776.  
  7777. hvt (HVALUETABLE) - input 
  7778.     Valuetable handle. 
  7779.  
  7780.  ppDetailsData (PVOID*) - input 
  7781.     Adress of the pointer variable to the details data. 
  7782.  
  7783.  pcp (PULONG) - input 
  7784.     Adress of the size variable of details data. 
  7785.  
  7786.  ulResult (ULONG) - returns 
  7787.     Success indicator. 
  7788.  
  7789.     TRUE 
  7790.               Successful completion. 
  7791.     FALSE 
  7792.               An error occurred. 
  7793.  
  7794.  
  7795. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectDetailsData Return Value - ulResult ΓòÉΓòÉΓòÉ
  7796.  
  7797. ulResult (ULONG) - returns 
  7798.     Success indicator. 
  7799.  
  7800.     TRUE 
  7801.               Successful completion. 
  7802.     FALSE 
  7803.               An error occurred. 
  7804.  
  7805.  
  7806. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectDetailsData - Remarks ΓòÉΓòÉΓòÉ
  7807.  
  7808. This function can be called as follows during _wpQueryDetailsData to 
  7809. automatically setup the details data: 
  7810.  
  7811. <wps_class>_parent_<wps_parent_class>_wpQueryDetailsData(somSelf,
  7812.                                                          ppDetailsData,
  7813.                                                          pcp);
  7814.  
  7815. return WtkQueryObjectDetailsData( _hvt, ppDetailsData, pcp);
  7816.  
  7817.  
  7818. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectDetailsData - Related functions ΓòÉΓòÉΓòÉ
  7819.  
  7820. Related Functions 
  7821.  
  7822. none 
  7823.  
  7824.  
  7825. ΓòÉΓòÉΓòÉ 8.64. WtkQueryObjectSettings ΓòÉΓòÉΓòÉ
  7826.  
  7827. Select an item: 
  7828.  
  7829.      Syntax 
  7830.      Parameters 
  7831.      Returns 
  7832.      Remarks 
  7833.      Related Functions 
  7834.  
  7835.  
  7836. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectSettings - Syntax ΓòÉΓòÉΓòÉ
  7837.  
  7838. This function queries the current settings of an object being implented by the 
  7839. WPS class. 
  7840.  
  7841. #define INCL_WTKSETTINGS
  7842. #include <wpstk.h>
  7843.  
  7844. HVALUETABLE   hvt;         /* Valuetable handle.                                                                                    */
  7845. PSZ           pszBuffer;   /* The address of a buffer in into which the resulting settings string is returned.                      */
  7846. PULONG        pulMaxlen;   /* The address of a variable for the length, in bytes, of the buffer described by pszBuffer.             */
  7847. BOOL          fResult;     /* Success indicator.                                                                                    */
  7848.  
  7849. fResult = WtkQueryObjectSettings( hvt, pszBuffer, pulMaxlen);
  7850.  
  7851.  
  7852. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectSettings - Parameter hvt ΓòÉΓòÉΓòÉ
  7853.  
  7854. hvt (HVALUETABLE) - input 
  7855.     Valuetable handle. 
  7856.  
  7857.  
  7858. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectSettings - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  7859.  
  7860. pszBuffer (PSZ) - output 
  7861.     The address of a buffer in into which the resulting settings string is 
  7862.     returned. 
  7863.  
  7864.     In order to only query the length of this string, leave this parameter 
  7865.     NULL. 
  7866.  
  7867.  
  7868. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectSettings - Parameter pulMaxlen ΓòÉΓòÉΓòÉ
  7869.  
  7870. pulMaxlen (PULONG) - input/output 
  7871.     The address of a variable for the length, in bytes, of the buffer described 
  7872.     by pszBuffer. 
  7873.  
  7874.  
  7875. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectSettings - Parameters ΓòÉΓòÉΓòÉ
  7876.  
  7877. hvt (HVALUETABLE) - input 
  7878.     Valuetable handle. 
  7879.  
  7880.  pszBuffer (PSZ) - output 
  7881.     The address of a buffer in into which the resulting settings string is 
  7882.     returned. 
  7883.  
  7884.     In order to only query the length of this string, leave this parameter 
  7885.     NULL. 
  7886.  
  7887.  pulMaxlen (PULONG) - input/output 
  7888.     The address of a variable for the length, in bytes, of the buffer described 
  7889.     by pszBuffer. 
  7890.  
  7891.  fResult (BOOL) - returns 
  7892.     Success indicator. 
  7893.  
  7894.     TRUE 
  7895.               String could be queried 
  7896.     FALSE 
  7897.               An error occurred. 
  7898.  
  7899.  
  7900. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectSettings Return Value - fResult ΓòÉΓòÉΓòÉ
  7901.  
  7902. fResult (BOOL) - returns 
  7903.     Success indicator. 
  7904.  
  7905.     TRUE 
  7906.               String could be queried 
  7907.     FALSE 
  7908.               An error occurred. 
  7909.  
  7910.  
  7911. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectSettings - Remarks ΓòÉΓòÉΓòÉ
  7912.  
  7913. This function is to be called during _wpSaveState in order to save the current 
  7914. settings implemented by the WPS class. 
  7915.  
  7916. Note:  Doing this, you still must call _wpSaveState of the parent class, as 
  7917. WtkQueryObjectSettings will only return and thus you can only save the settings 
  7918. being implemented by your WPS class ! 
  7919.  
  7920.  
  7921. ΓòÉΓòÉΓòÉ <hidden> WtkQueryObjectSettings - Related functions ΓòÉΓòÉΓòÉ
  7922.  
  7923. Related Functions 
  7924.  
  7925. none 
  7926.  
  7927.  
  7928. ΓòÉΓòÉΓòÉ 8.65. WtkQuerySysLanguage ΓòÉΓòÉΓòÉ
  7929.  
  7930. Select an item: 
  7931.  
  7932.      Syntax 
  7933.      Parameters 
  7934.      Returns 
  7935.      Remarks 
  7936.      Related Functions 
  7937.  
  7938.  
  7939. ΓòÉΓòÉΓòÉ <hidden> WtkQuerySysLanguage - Syntax ΓòÉΓòÉΓòÉ
  7940.  
  7941. This function returns a pointer to the ASSICZ three letter ISO language 
  7942. identifier according to the language of your operation system. 
  7943.  
  7944. For this the OS/2 syslevel file is uses, whereas the COUNTRY or locale settings 
  7945. are not used (as they may certainly differ from the language of the operation 
  7946. system). 
  7947.  
  7948. #define INCL_WTKUTLSYSTEM
  7949. #include <wpstk.h>
  7950.  
  7951. PSZ   pszResult;   /* Pointer to the ASSICZ three letter ISO language identifier according to the language of your operation system.  */
  7952.  
  7953. pszResult = WtkQuerySysLanguage();
  7954.  
  7955.  
  7956. ΓòÉΓòÉΓòÉ <hidden> WtkQuerySysLanguage - Parameters ΓòÉΓòÉΓòÉ
  7957.  
  7958. pszResult (PSZ) - returns 
  7959.     Pointer to the ASSICZ three letter ISO language identifier according to the 
  7960.     language of your operation system. 
  7961.  
  7962.     When for any reason the language cannot be determined properly, eng is 
  7963.     returned for the english language as default. 
  7964.  
  7965.  
  7966. ΓòÉΓòÉΓòÉ <hidden> WtkQuerySysLanguage Return Value - pszResult ΓòÉΓòÉΓòÉ
  7967.  
  7968. pszResult (PSZ) - returns 
  7969.     Pointer to the ASSICZ three letter ISO language identifier according to the 
  7970.     language of your operation system. 
  7971.  
  7972.     When for any reason the language cannot be determined properly, eng is 
  7973.     returned for the english language as default. 
  7974.  
  7975.  
  7976. ΓòÉΓòÉΓòÉ <hidden> WtkQuerySysLanguage - Remarks ΓòÉΓòÉΓòÉ
  7977.  
  7978. This function determines the language from the OS/2 syslevel file of your 
  7979. operating system by reading the language character of the CSD identifier. As 
  7980. the language is coded in one character only within CSD ids and this character 
  7981. must not necessarily be unique to one language, this function in some cases 
  7982. also checks the OS/2 system message file in order to uniquely identify the 
  7983. language of the operating system. 
  7984.  
  7985. The following language identifiers are currently supported: 
  7986.  
  7987.  eng   us/uk english 
  7988.  dan   danish 
  7989.  deu   german 
  7990.  esp   spanish 
  7991.  fin   finnish 
  7992.  fra   french 
  7993.  frc   canadian french 
  7994.  ita   italian 
  7995.  jpn   japanese 
  7996.  kor   korean 
  7997.  ndl   dutch 
  7998.  nor   norwegian 
  7999.  pol   polish 
  8000.  ptb   brazilian portugese 
  8001.  ptg   portugese 
  8002.  swe   swedish 
  8003.  twn   taiwanese 
  8004.  
  8005.  Note that neither the COUNTRY setting nor the variable LANG is used, as they 
  8006.  may differ from the language of the operation system. Moreover, if the user 
  8007.  applied a fixpak of another language, the syslevel file may well reflect the 
  8008.  language of the fixpak instead of the base operating system. In such a case of 
  8009.  course the identifier for this language is returned, but the system will then 
  8010.  use this language for many dialogs anyway, so this won't hurt much. 
  8011.  
  8012.  
  8013. ΓòÉΓòÉΓòÉ <hidden> WtkQuerySysLanguage - Related functions ΓòÉΓòÉΓòÉ
  8014.  
  8015. Related Functions 
  8016.  
  8017. none 
  8018.  
  8019.  
  8020. ΓòÉΓòÉΓòÉ 8.66. WtkQueryVersion ΓòÉΓòÉΓòÉ
  8021.  
  8022. Select an item: 
  8023.  
  8024.      Syntax 
  8025.      Parameters 
  8026.      Returns 
  8027.      Remarks 
  8028.      Related Functions 
  8029.  
  8030.  
  8031. ΓòÉΓòÉΓòÉ <hidden> WtkQueryVersion - Syntax ΓòÉΓòÉΓòÉ
  8032.  
  8033. This function creates a settings table for a meta class. 
  8034.  
  8035. #define INCL_WTKVERSION
  8036. #include <wpstk.h>
  8037.  
  8038. PSZ     pszBuffer;   /* The address of a buffer in into which the version string is returned.   */
  8039. ULONG   ulBuflen;    /* The length, in bytes, of the buffer described by pszBuffer.             */
  8040. ULONG   ulResult;    /* Return Code.                                                            */
  8041.  
  8042. ulResult = WtkQueryVersion( pszBuffer, ulBuflen);
  8043.  
  8044.  
  8045. ΓòÉΓòÉΓòÉ <hidden> WtkQueryVersion - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  8046.  
  8047. pszBuffer (PSZ) - output 
  8048.     The address of a buffer in into which the version string is returned. 
  8049.  
  8050.  
  8051. ΓòÉΓòÉΓòÉ <hidden> WtkQueryVersion - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  8052.  
  8053. ulBuflen (ULONG) - input 
  8054.     The length, in bytes, of the buffer described by pszBuffer. 
  8055.  
  8056.  
  8057. ΓòÉΓòÉΓòÉ <hidden> WtkQueryVersion - Parameters ΓòÉΓòÉΓòÉ
  8058.  
  8059. pszBuffer (PSZ) - output 
  8060.     The address of a buffer in into which the version string is returned. 
  8061.  
  8062.  ulBuflen (ULONG) - input 
  8063.     The length, in bytes, of the buffer described by pszBuffer. 
  8064.  
  8065.  ulResult (ULONG) - returns 
  8066.     Return Code. 
  8067.  
  8068.     WtkQueryVersion returns one of the following return codes: 
  8069.  
  8070.     0         NO_ERROR 
  8071.     87        ERROR_INVALID_PARAMETER 
  8072.     111       ERROR_BUFFER_OVERFLOW 
  8073.  
  8074.  
  8075. ΓòÉΓòÉΓòÉ <hidden> WtkQueryVersion Return Value - ulResult ΓòÉΓòÉΓòÉ
  8076.  
  8077. ulResult (ULONG) - returns 
  8078.     Return Code. 
  8079.  
  8080.     WtkQueryVersion returns one of the following return codes: 
  8081.  
  8082.     0         NO_ERROR 
  8083.     87        ERROR_INVALID_PARAMETER 
  8084.     111       ERROR_BUFFER_OVERFLOW 
  8085.  
  8086.  
  8087. ΓòÉΓòÉΓòÉ <hidden> WtkQueryVersion - Remarks ΓòÉΓòÉΓòÉ
  8088.  
  8089. This function enables to ensure, that the WPS class is using the same version 
  8090. of the WPS toolkit API, that it was compiled with. This is normally not 
  8091. required for WPS class DLLs or applications, where the WPS toolkit functions 
  8092. are statically linked to, but may be important, where they are linked as a DLL. 
  8093. (Note, that the WPS toolkit is not yet available as a DLL). 
  8094.  
  8095. In order to ensure, that your WPS DLL is using the same WPS Toolkit API, as it 
  8096. was compiled with, compare the resulting string with the value WPSTK_VERSION. 
  8097.  
  8098.  
  8099. ΓòÉΓòÉΓòÉ <hidden> WtkQueryVersion - Related functions ΓòÉΓòÉΓòÉ
  8100.  
  8101. Related Functions 
  8102.  
  8103. none 
  8104.  
  8105.  
  8106. ΓòÉΓòÉΓòÉ 8.67. WtkReadEa ΓòÉΓòÉΓòÉ
  8107.  
  8108. Select an item: 
  8109.  
  8110.      Syntax 
  8111.      Parameters 
  8112.      Returns 
  8113.      Remarks 
  8114.      Related Functions 
  8115.  
  8116.  
  8117. ΓòÉΓòÉΓòÉ <hidden> WtkReadEa - Syntax ΓòÉΓòÉΓòÉ
  8118.  
  8119. This function reads an extended attribute of a given file or directory. 
  8120.  
  8121. #define INCL_WTKEAS
  8122. #include <wpstk.h>
  8123.  
  8124. PSZ      pszName;     /* Address of the ASCIIZ path name of the file or directory.                  */
  8125. PSZ      pszEaName;   /* Address of the ASCIIZ name of the extended attribute.                      */
  8126. PHEA     phea;        /* The address of a variable containing the handle to the extended attribute  */
  8127. APIRET   ulrc;        /* Return Code.                                                               */
  8128.  
  8129. ulrc = WtkReadEa( pszName, pszEaName, phea);
  8130.  
  8131.  
  8132. ΓòÉΓòÉΓòÉ <hidden> WtkReadEa - Parameter pszName ΓòÉΓòÉΓòÉ
  8133.  
  8134. pszName (PSZ) - input 
  8135.     Address of the ASCIIZ path name of the file or directory. 
  8136.  
  8137.     The path name may contain ?: for the drive in order to open the file or 
  8138.     directory on the boot drive. 
  8139.  
  8140.     The name may not include wildcards. 
  8141.  
  8142.  
  8143. ΓòÉΓòÉΓòÉ <hidden> WtkReadEa - Parameter pszEaName ΓòÉΓòÉΓòÉ
  8144.  
  8145. pszEaName (PSZ) - input 
  8146.     Address of the ASCIIZ name of the extended attribute. 
  8147.  
  8148.  
  8149. ΓòÉΓòÉΓòÉ <hidden> WtkReadEa - Parameter phea ΓòÉΓòÉΓòÉ
  8150.  
  8151. phea (PHEA) - output 
  8152.     The address of a variable containing the handle to the extended attribute 
  8153.  
  8154.  
  8155. ΓòÉΓòÉΓòÉ <hidden> WtkReadEa - Parameters ΓòÉΓòÉΓòÉ
  8156.  
  8157. pszName (PSZ) - input 
  8158.     Address of the ASCIIZ path name of the file or directory. 
  8159.  
  8160.     The path name may contain ?: for the drive in order to open the file or 
  8161.     directory on the boot drive. 
  8162.  
  8163.     The name may not include wildcards. 
  8164.  
  8165.  pszEaName (PSZ) - input 
  8166.     Address of the ASCIIZ name of the extended attribute. 
  8167.  
  8168.  phea (PHEA) - output 
  8169.     The address of a variable containing the handle to the extended attribute 
  8170.  
  8171.  ulrc (APIRET) - returns 
  8172.     Return Code. 
  8173.  
  8174.     WtkReadEa returns one of the following return codes: 
  8175.  
  8176.     0         NO_ERROR 
  8177.     8         ERROR_NOT_ENOUGH_MEMORY 
  8178.     87        ERROR_INVALID_PARAMETER 
  8179.  
  8180.     or return codes of the following functions 
  8181.  
  8182.         DosQueryPathInfo 
  8183.  
  8184.  
  8185. ΓòÉΓòÉΓòÉ <hidden> WtkReadEa Return Value - ulrc ΓòÉΓòÉΓòÉ
  8186.  
  8187. ulrc (APIRET) - returns 
  8188.     Return Code. 
  8189.  
  8190.     WtkReadEa returns one of the following return codes: 
  8191.  
  8192.     0         NO_ERROR 
  8193.     8         ERROR_NOT_ENOUGH_MEMORY 
  8194.     87        ERROR_INVALID_PARAMETER 
  8195.  
  8196.     or return codes of the following functions 
  8197.  
  8198.         DosQueryPathInfo 
  8199.  
  8200.  
  8201. ΓòÉΓòÉΓòÉ <hidden> WtkReadEa - Remarks ΓòÉΓòÉΓòÉ
  8202.  
  8203. This function allocates resources for handling the value of the given extended 
  8204. attribute, which must be freeed by calling WtkCloseEa, when not longer needed. 
  8205.  
  8206. This function supports boot drive recognition. Specify ?: for the drive in 
  8207. order to open the file or directory on the boot drive. 
  8208.  
  8209.  
  8210. ΓòÉΓòÉΓòÉ <hidden> WtkReadEa - Related functions ΓòÉΓòÉΓòÉ
  8211.  
  8212. Related Functions 
  8213.  
  8214. none 
  8215.  
  8216.  
  8217. ΓòÉΓòÉΓòÉ 8.68. WtkReadFile ΓòÉΓòÉΓòÉ
  8218.  
  8219. Select an item: 
  8220.  
  8221.      Syntax 
  8222.      Parameters 
  8223.      Returns 
  8224.      Remarks 
  8225.      Related Functions 
  8226.  
  8227.  
  8228. ΓòÉΓòÉΓòÉ <hidden> WtkReadFile - Syntax ΓòÉΓòÉΓòÉ
  8229.  
  8230. This function reads a file completely into memory. 
  8231.  
  8232. #define INCL_WTKUTLFILE
  8233. #include <wpstk.h>
  8234.  
  8235. PSZ      pszName;      /* Address of the ASCIIZ pathname, which is to be read into memory.                                                                                                           */
  8236. 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().  */
  8237. PULONG   pulBuflen;    /* The address of a variable containing the length of the file, and thus the buffer.                                                                                          */
  8238. APIRET   ulrc;         /* Return Code.                                                                                                                                                               */
  8239.  
  8240. ulrc = WtkReadFile( pszName, ppszBuffer, pulBuflen);
  8241.  
  8242.  
  8243. ΓòÉΓòÉΓòÉ <hidden> WtkReadFile - Parameter pszName ΓòÉΓòÉΓòÉ
  8244.  
  8245. pszName (PSZ) - input 
  8246.     Address of the ASCIIZ pathname, which is to be read into memory. 
  8247.  
  8248.     The path name may contain ?: for the drive in order to read the file from 
  8249.     the boot drive. 
  8250.  
  8251.  
  8252. ΓòÉΓòÉΓòÉ <hidden> WtkReadFile - Parameter ppszBuffer ΓòÉΓòÉΓòÉ
  8253.  
  8254. ppszBuffer (PSZ*) - output 
  8255.     The address of a pointer variable to a buffer, into which the full file is 
  8256.     being read into. The memory allocated by WtkReadFile must be freed by the 
  8257.     caller using free(). 
  8258.  
  8259.  
  8260. ΓòÉΓòÉΓòÉ <hidden> WtkReadFile - Parameter pulBuflen ΓòÉΓòÉΓòÉ
  8261.  
  8262. pulBuflen (PULONG) - output 
  8263.     The address of a variable containing the length of the file, and thus the 
  8264.     buffer. 
  8265.  
  8266.  
  8267. ΓòÉΓòÉΓòÉ <hidden> WtkReadFile - Parameters ΓòÉΓòÉΓòÉ
  8268.  
  8269. pszName (PSZ) - input 
  8270.     Address of the ASCIIZ pathname, which is to be read into memory. 
  8271.  
  8272.     The path name may contain ?: for the drive in order to read the file from 
  8273.     the boot drive. 
  8274.  
  8275.  ppszBuffer (PSZ*) - output 
  8276.     The address of a pointer variable to a buffer, into which the full file is 
  8277.     being read into. The memory allocated by WtkReadFile must be freed by the 
  8278.     caller using free(). 
  8279.  
  8280.  pulBuflen (PULONG) - output 
  8281.     The address of a variable containing the length of the file, and thus the 
  8282.     buffer. 
  8283.  
  8284.  ulrc (APIRET) - returns 
  8285.     Return Code. 
  8286.  
  8287.     WtkReadFile returns one of the following return codes: 
  8288.  
  8289.     0         NO_ERROR 
  8290.     8         ERROR_NOT_ENOUGH_MEMORY 
  8291.     87        ERROR_INVALID_PARAMETER 
  8292.  
  8293.     or return codes of the following functions 
  8294.  
  8295.         DosOpen 
  8296.         DosRead 
  8297.  
  8298.  
  8299. ΓòÉΓòÉΓòÉ <hidden> WtkReadFile Return Value - ulrc ΓòÉΓòÉΓòÉ
  8300.  
  8301. ulrc (APIRET) - returns 
  8302.     Return Code. 
  8303.  
  8304.     WtkReadFile returns one of the following return codes: 
  8305.  
  8306.     0         NO_ERROR 
  8307.     8         ERROR_NOT_ENOUGH_MEMORY 
  8308.     87        ERROR_INVALID_PARAMETER 
  8309.  
  8310.     or return codes of the following functions 
  8311.  
  8312.         DosOpen 
  8313.         DosRead 
  8314.  
  8315.  
  8316. ΓòÉΓòÉΓòÉ <hidden> WtkReadFile - Remarks ΓòÉΓòÉΓòÉ
  8317.  
  8318. The memory allocated by WtkReadFile must be freed by the caller using free(). 
  8319.  
  8320. This function supports boot drive recognition. Specify ?: for the drive in 
  8321. order to read the file from the boot drive. 
  8322.  
  8323.  
  8324. ΓòÉΓòÉΓòÉ <hidden> WtkReadFile - Related functions ΓòÉΓòÉΓòÉ
  8325.  
  8326. Related Functions 
  8327.  
  8328. none 
  8329.  
  8330.  
  8331. ΓòÉΓòÉΓòÉ 8.69. WtkReadObjectValueTable ΓòÉΓòÉΓòÉ
  8332.  
  8333. Select an item: 
  8334.  
  8335.      Syntax 
  8336.      Parameters 
  8337.      Returns 
  8338.      Remarks 
  8339.      Related Functions 
  8340.  
  8341.  
  8342. ΓòÉΓòÉΓòÉ <hidden> WtkReadObjectValueTable - Syntax ΓòÉΓòÉΓòÉ
  8343.  
  8344. This function reads the object valuetable and transfers them to the GUI 
  8345. controls of a given settings notebookpage. 
  8346.  
  8347. #define INCL_WTKSETTINGS
  8348. #include <wpstk.h>
  8349.  
  8350. HVALUETABLE   hvt;          /* Valuetable handle.                            */
  8351. HWND          hwndDialog;   /* Dialog handle of the settings notebook page.  */
  8352. BOOL          fResult;      /* Success indicator.                            */
  8353.  
  8354. fResult = WtkReadObjectValueTable( hvt, hwndDialog);
  8355.  
  8356.  
  8357. ΓòÉΓòÉΓòÉ <hidden> WtkReadObjectValueTable - Parameter hvt ΓòÉΓòÉΓòÉ
  8358.  
  8359. hvt (HVALUETABLE) - input 
  8360.     Valuetable handle. 
  8361.  
  8362.  
  8363. ΓòÉΓòÉΓòÉ <hidden> WtkReadObjectValueTable - Parameter hwndDialog ΓòÉΓòÉΓòÉ
  8364.  
  8365. hwndDialog (HWND) - input 
  8366.     Dialog handle of the settings notebook page. 
  8367.  
  8368.  
  8369. ΓòÉΓòÉΓòÉ <hidden> WtkReadObjectValueTable - Parameters ΓòÉΓòÉΓòÉ
  8370.  
  8371. hvt (HVALUETABLE) - input 
  8372.     Valuetable handle. 
  8373.  
  8374.  hwndDialog (HWND) - input 
  8375.     Dialog handle of the settings notebook page. 
  8376.  
  8377.  fResult (BOOL) - returns 
  8378.     Success indicator. 
  8379.  
  8380.     TRUE 
  8381.               Values could be transferred to the notebook page dialog. 
  8382.     FALSE 
  8383.               An error occurred. 
  8384.  
  8385.  
  8386. ΓòÉΓòÉΓòÉ <hidden> WtkReadObjectValueTable Return Value - fResult ΓòÉΓòÉΓòÉ
  8387.  
  8388. fResult (BOOL) - returns 
  8389.     Success indicator. 
  8390.  
  8391.     TRUE 
  8392.               Values could be transferred to the notebook page dialog. 
  8393.     FALSE 
  8394.               An error occurred. 
  8395.  
  8396.  
  8397. ΓòÉΓòÉΓòÉ <hidden> WtkReadObjectValueTable - Remarks ΓòÉΓòÉΓòÉ
  8398.  
  8399. This function is to be called in the message handling of the window procedure 
  8400. being used for the settings notebookpages. 
  8401.  
  8402. It should be called when handling the WM_INITDLG message and the WM_COMMAND 
  8403. message for the undo button in order to transfer the current object settings 
  8404. values to the notebook settings page. 
  8405.  
  8406.  
  8407. ΓòÉΓòÉΓòÉ <hidden> WtkReadObjectValueTable - Related functions ΓòÉΓòÉΓòÉ
  8408.  
  8409. Related Functions 
  8410.  
  8411. none 
  8412.  
  8413.  
  8414. ΓòÉΓòÉΓòÉ 8.70. WtkReadStringEa ΓòÉΓòÉΓòÉ
  8415.  
  8416. Select an item: 
  8417.  
  8418.      Syntax 
  8419.      Parameters 
  8420.      Returns 
  8421.      Remarks 
  8422.      Related Functions 
  8423.  
  8424.  
  8425. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa - Syntax ΓòÉΓòÉΓòÉ
  8426.  
  8427. This function queries a string extended attribute of a file or directory. 
  8428.  
  8429. #define INCL_WTKEAS
  8430. #include <wpstk.h>
  8431.  
  8432. PSZ      pszName;      /* Address of the ASCIIZ path name of the file or directory.                                                     */
  8433. PSZ      pszEaName;    /* Address of the ASCIIZ name of the extended attribute.                                                         */
  8434. PSZ      pszEaValue;   /* The address of a buffer in into which the value of the given extended attribute is returned.                  */
  8435. PULONG   pulBuflen;    /* The address of a variable containing the length, in bytes, of the buffer described by pszEaValue.             */
  8436. APIRET   ulrc;         /* Return Code.                                                                                                  */
  8437.  
  8438. ulrc = WtkReadStringEa( pszName, pszEaName, pszEaValue, pulBuflen);
  8439.  
  8440.  
  8441. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa - Parameter pszName ΓòÉΓòÉΓòÉ
  8442.  
  8443. pszName (PSZ) - input 
  8444.     Address of the ASCIIZ path name of the file or directory. 
  8445.  
  8446.     The path name may contain ?: for the drive in order to search the file or 
  8447.     directory on the boot drive. 
  8448.  
  8449.     The name may not include wildcards. 
  8450.  
  8451.  
  8452. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa - Parameter pszEaName ΓòÉΓòÉΓòÉ
  8453.  
  8454. pszEaName (PSZ) - input 
  8455.     Address of the ASCIIZ name of the extended attribute. 
  8456.  
  8457.     If multiple values and/or types for the specified extended attribute are 
  8458.     attached to the file or directory, the first string attribute is returned. 
  8459.  
  8460.  
  8461. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa - Parameter pszEaValue ΓòÉΓòÉΓòÉ
  8462.  
  8463. pszEaValue (PSZ) - output 
  8464.     The address of a buffer in into which the value of the given extended 
  8465.     attribute is returned. 
  8466.  
  8467.  
  8468. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa - Parameter pulBuflen ΓòÉΓòÉΓòÉ
  8469.  
  8470. pulBuflen (PULONG) - input/output 
  8471.     The address of a variable containing the length, in bytes, of the buffer 
  8472.     described by pszEaValue. 
  8473.  
  8474.  
  8475. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa - Parameters ΓòÉΓòÉΓòÉ
  8476.  
  8477. pszName (PSZ) - input 
  8478.     Address of the ASCIIZ path name of the file or directory. 
  8479.  
  8480.     The path name may contain ?: for the drive in order to search the file or 
  8481.     directory on the boot drive. 
  8482.  
  8483.     The name may not include wildcards. 
  8484.  
  8485.  pszEaName (PSZ) - input 
  8486.     Address of the ASCIIZ name of the extended attribute. 
  8487.  
  8488.     If multiple values and/or types for the specified extended attribute are 
  8489.     attached to the file or directory, the first string attribute is returned. 
  8490.  
  8491.  pszEaValue (PSZ) - output 
  8492.     The address of a buffer in into which the value of the given extended 
  8493.     attribute is returned. 
  8494.  
  8495.  pulBuflen (PULONG) - input/output 
  8496.     The address of a variable containing the length, in bytes, of the buffer 
  8497.     described by pszEaValue. 
  8498.  
  8499.  ulrc (APIRET) - returns 
  8500.     Return Code. 
  8501.  
  8502.     WtkReadStringEa returns one of the following return codes: 
  8503.  
  8504.     0         NO_ERROR 
  8505.     6         ERROR_INVALID_HANDLE 
  8506.     8         ERROR_NOT_ENOUGH_MEMORY 
  8507.     13        ERROR_INVALID_DATA 
  8508.     87        ERROR_INVALID_PARAMETER 
  8509.  
  8510.     or return codes of the following functions 
  8511.  
  8512.         DosSetPathInfo 
  8513.  
  8514.  
  8515. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa Return Value - ulrc ΓòÉΓòÉΓòÉ
  8516.  
  8517. ulrc (APIRET) - returns 
  8518.     Return Code. 
  8519.  
  8520.     WtkReadStringEa returns one of the following return codes: 
  8521.  
  8522.     0         NO_ERROR 
  8523.     6         ERROR_INVALID_HANDLE 
  8524.     8         ERROR_NOT_ENOUGH_MEMORY 
  8525.     13        ERROR_INVALID_DATA 
  8526.     87        ERROR_INVALID_PARAMETER 
  8527.  
  8528.     or return codes of the following functions 
  8529.  
  8530.         DosSetPathInfo 
  8531.  
  8532.  
  8533. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa - Remarks ΓòÉΓòÉΓòÉ
  8534.  
  8535. This function supports boot drive recognition. Specify ?: for the drive in 
  8536. order to open the file or directory on the boot drive. 
  8537.  
  8538. This function is meant to provide you with easy handling of string extended 
  8539. attributes. The drawback is that for simplicity you cannot 
  8540.  
  8541.      read more than one value from the string extended attribute (but that is 
  8542.       what is needed for most cases anyway) 
  8543.  
  8544.  If these limitations does not meet your requirements, use the move flexible 
  8545.  call WtkPutEaValue instead. 
  8546.  
  8547.  
  8548. ΓòÉΓòÉΓòÉ <hidden> WtkReadStringEa - Related functions ΓòÉΓòÉΓòÉ
  8549.  
  8550. Related Functions 
  8551.  
  8552. none 
  8553.  
  8554.  
  8555. ΓòÉΓòÉΓòÉ 8.71. WtkRegisterSettingsDialog ΓòÉΓòÉΓòÉ
  8556.  
  8557. Select an item: 
  8558.  
  8559.      Syntax 
  8560.      Parameters 
  8561.      Returns 
  8562.      Remarks 
  8563.      Related Functions 
  8564.  
  8565.  
  8566. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsDialog - Syntax ΓòÉΓòÉΓòÉ
  8567.  
  8568. This function reqisters a dialog of a settings notebookpage for automatic 
  8569. update and restore of the GUI dialog to and from the valuetable of the WPS 
  8570. object. 
  8571.  
  8572. #define INCL_WTKSETTINGS
  8573. #include <wpstk.h>
  8574.  
  8575. HVALUETABLE   hvt;          /* Valuetable handle.                            */
  8576. HWND          hwndDialog;   /* Dialog handle of the settings notebook page.  */
  8577. BOOL          fResult;      /* Success indicator.                            */
  8578.  
  8579. fResult = WtkRegisterSettingsDialog( hvt, hwndDialog);
  8580.  
  8581.  
  8582. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsDialog - Parameter hvt ΓòÉΓòÉΓòÉ
  8583.  
  8584. hvt (HVALUETABLE) - input 
  8585.     Valuetable handle. 
  8586.  
  8587.  
  8588. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsDialog - Parameter hwndDialog ΓòÉΓòÉΓòÉ
  8589.  
  8590. hwndDialog (HWND) - input 
  8591.     Dialog handle of the settings notebook page. 
  8592.  
  8593.  
  8594. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsDialog - Parameters ΓòÉΓòÉΓòÉ
  8595.  
  8596. hvt (HVALUETABLE) - input 
  8597.     Valuetable handle. 
  8598.  
  8599.  hwndDialog (HWND) - input 
  8600.     Dialog handle of the settings notebook page. 
  8601.  
  8602.  fResult (BOOL) - returns 
  8603.     Success indicator. 
  8604.  
  8605.     TRUE 
  8606.               Dialog could be registered. 
  8607.     FALSE 
  8608.               An error occurred. 
  8609.  
  8610.  
  8611. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsDialog Return Value - fResult ΓòÉΓòÉΓòÉ
  8612.  
  8613. fResult (BOOL) - returns 
  8614.     Success indicator. 
  8615.  
  8616.     TRUE 
  8617.               Dialog could be registered. 
  8618.     FALSE 
  8619.               An error occurred. 
  8620.  
  8621.  
  8622. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsDialog - Remarks ΓòÉΓòÉΓòÉ
  8623.  
  8624. This function is to be called in the WM_INITDLG message handling of the window 
  8625. procedure being used for the settings notebookpages. 
  8626.  
  8627.  
  8628. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsDialog - Related functions ΓòÉΓòÉΓòÉ
  8629.  
  8630. Related Functions 
  8631.  
  8632. none 
  8633.  
  8634.  
  8635. ΓòÉΓòÉΓòÉ 8.72. WtkRegisterSettingsNotebook ΓòÉΓòÉΓòÉ
  8636.  
  8637. Select an item: 
  8638.  
  8639.      Syntax 
  8640.      Parameters 
  8641.      Returns 
  8642.      Remarks 
  8643.      Related Functions 
  8644.  
  8645.  
  8646. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsNotebook - Syntax ΓòÉΓòÉΓòÉ
  8647.  
  8648. This function reqisters the notebook for automatic validation of all registered 
  8649. settings notebookpages, when the notebook is closed. 
  8650.  
  8651. #define INCL_WTKSETTINGS
  8652. #include <wpstk.h>
  8653.  
  8654. HVALUETABLE   hvt;            /* Valuetable handle.  */
  8655. HWND          hwndNotebook;   /* Notebook handle.    */
  8656. BOOL          fResult;        /* Success indicator.  */
  8657.  
  8658. fResult = WtkRegisterSettingsNotebook( hvt, hwndNotebook);
  8659.  
  8660.  
  8661. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsNotebook - Parameter hvt ΓòÉΓòÉΓòÉ
  8662.  
  8663. hvt (HVALUETABLE) - input 
  8664.     Valuetable handle. 
  8665.  
  8666.  
  8667. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsNotebook - Parameter hwndNotebook ΓòÉΓòÉΓòÉ
  8668.  
  8669. hwndNotebook (HWND) - input 
  8670.     Notebook handle. 
  8671.  
  8672.  
  8673. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsNotebook - Parameters ΓòÉΓòÉΓòÉ
  8674.  
  8675. hvt (HVALUETABLE) - input 
  8676.     Valuetable handle. 
  8677.  
  8678.  hwndNotebook (HWND) - input 
  8679.     Notebook handle. 
  8680.  
  8681.  fResult (BOOL) - returns 
  8682.     Success indicator. 
  8683.  
  8684.     TRUE 
  8685.               Notebook could be registered. 
  8686.     FALSE 
  8687.               An error occurred. 
  8688.  
  8689.  
  8690. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsNotebook Return Value - fResult ΓòÉΓòÉΓòÉ
  8691.  
  8692. fResult (BOOL) - returns 
  8693.     Success indicator. 
  8694.  
  8695.     TRUE 
  8696.               Notebook could be registered. 
  8697.     FALSE 
  8698.               An error occurred. 
  8699.  
  8700.  
  8701. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsNotebook - Remarks ΓòÉΓòÉΓòÉ
  8702.  
  8703. This function is to be called in _wpAddSettingsPages, after the WPS class added 
  8704. all settings notebook pages. 
  8705.  
  8706. When the notebook is closed, all values of the objects valuetable are checked. 
  8707. If the settings notebookpage containing the GUI control for a value has been 
  8708. registerd (thus become active) 
  8709.  
  8710.      the value of this control is validated 
  8711.      if requested from the WPS class, on validation error 
  8712.         -  the notebook page of the errant GUI control is brought to top 
  8713.         -  the errant GUI receives focus 
  8714.         -  the WPS class is being notified of the error, so that it can take 
  8715.            the appropriate action 
  8716.         -  the close request is ignored 
  8717.  
  8718.  
  8719. ΓòÉΓòÉΓòÉ <hidden> WtkRegisterSettingsNotebook - Related functions ΓòÉΓòÉΓòÉ
  8720.  
  8721. Related Functions 
  8722.  
  8723. none 
  8724.  
  8725.  
  8726. ΓòÉΓòÉΓòÉ 8.73. WtkRelocateNotebookpageControls ΓòÉΓòÉΓòÉ
  8727.  
  8728. Select an item: 
  8729.  
  8730.      Syntax 
  8731.      Parameters 
  8732.      Returns 
  8733.      Remarks 
  8734.      Related Functions 
  8735.  
  8736.  
  8737. ΓòÉΓòÉΓòÉ <hidden> WtkRelocateNotebookpageControls - Syntax ΓòÉΓòÉΓòÉ
  8738.  
  8739. This function makes certain pushbuttons a notebook pushbutton and relocates all 
  8740. other controls of a settings notebook page, when the WPS class is being run 
  8741. under OS/2 WARP 4. This allows to use the same dialog template under OS/2 WARP 
  8742. 3 and WARP 4. 
  8743.  
  8744. #define INCL_WTKSETTINGS
  8745. #include <wpstk.h>
  8746.  
  8747. HWND   hwndDialog;   /* Dialog handle of the settings notebookpage.  */
  8748. BOOL   fResult;      /* Success indicator.                           */
  8749.  
  8750. fResult = WtkRelocateNotebookpageControls( hwndDialog);
  8751.  
  8752.  
  8753. ΓòÉΓòÉΓòÉ <hidden> WtkRelocateNotebookpageControls - Parameter hwndDialog ΓòÉΓòÉΓòÉ
  8754.  
  8755. hwndDialog (HWND) - input 
  8756.     Dialog handle of the settings notebookpage. 
  8757.  
  8758.  
  8759. ΓòÉΓòÉΓòÉ <hidden> WtkRelocateNotebookpageControls - Parameters ΓòÉΓòÉΓòÉ
  8760.  
  8761. hwndDialog (HWND) - input 
  8762.     Dialog handle of the settings notebookpage. 
  8763.  
  8764.  fResult (BOOL) - returns 
  8765.     Success indicator. 
  8766.  
  8767.     TRUE 
  8768.               Relocation successful or not OS/2 Warp 4 running. 
  8769.     FALSE 
  8770.               A validation error occurred. 
  8771.  
  8772.  
  8773. ΓòÉΓòÉΓòÉ <hidden> WtkRelocateNotebookpageControls Return Value - fResult ΓòÉΓòÉΓòÉ
  8774.  
  8775. fResult (BOOL) - returns 
  8776.     Success indicator. 
  8777.  
  8778.     TRUE 
  8779.               Relocation successful or not OS/2 Warp 4 running. 
  8780.     FALSE 
  8781.               A validation error occurred. 
  8782.  
  8783.  
  8784. ΓòÉΓòÉΓòÉ <hidden> WtkRelocateNotebookpageControls - Remarks ΓòÉΓòÉΓòÉ
  8785.  
  8786. This function first of all determines, if OS/2 WARP 4 is running. If not, it 
  8787. aborts with no error. Otherwise 
  8788.  
  8789.      the layout of all groupboxes is examined and the lowest groupbox (nearest 
  8790.       to y-coordinate 0) is determined. 
  8791.      all pushbuttons below the lowest groupbox are made notebook buttons, thus 
  8792.       being moved out of the dialog. 
  8793.      all other controls are moved downwards, so that the gap of the now 
  8794.       missing pusbuttons is closed. 
  8795.  
  8796.  
  8797. ΓòÉΓòÉΓòÉ <hidden> WtkRelocateNotebookpageControls - Related functions ΓòÉΓòÉΓòÉ
  8798.  
  8799. Related Functions 
  8800.  
  8801. none 
  8802.  
  8803.  
  8804. ΓòÉΓòÉΓòÉ 8.74. WtkRestoreObjectSettings ΓòÉΓòÉΓòÉ
  8805.  
  8806. Select an item: 
  8807.  
  8808.      Syntax 
  8809.      Parameters 
  8810.      Returns 
  8811.      Remarks 
  8812.      Related Functions 
  8813.  
  8814.  
  8815. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings - Syntax ΓòÉΓòÉΓòÉ
  8816.  
  8817. This function restores the settings being previously saved with 
  8818. WtkSaveObjectSettings.. Both the settings valuetable and currently active GUI 
  8819. controls corresponding to the restored values are updated. 
  8820.  
  8821. #define INCL_WTKSETTINGS
  8822. #include <wpstk.h>
  8823.  
  8824. HVALUETABLE   hvt;           /* Valuetable handle.                                                         */
  8825. PSZ           pszFilename;   /* Address of the ASCIIZ filename of the INI file to read the settings from.  */
  8826. PSZ           pszApp;        /* Name of the INI application name.                                          */
  8827. PSZ           pszKey;        /* Name of the INI application key.                                           */
  8828. BOOL          fResult;       /* Success indicator.                                                         */
  8829.  
  8830. fResult = WtkRestoreObjectSettings( hvt, pszFilename, pszApp, pszKey);
  8831.  
  8832.  
  8833. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings - Parameter hvt ΓòÉΓòÉΓòÉ
  8834.  
  8835. hvt (HVALUETABLE) - input 
  8836.     Valuetable handle. 
  8837.  
  8838.  
  8839. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings - Parameter pszFilename ΓòÉΓòÉΓòÉ
  8840.  
  8841. pszFilename (PSZ) - input 
  8842.     Address of the ASCIIZ filename of the INI file to read the settings from. 
  8843.  
  8844.     The following names are reserved to read from the user or system ini: 
  8845.  
  8846.     Name 
  8847.               INI file 
  8848.  
  8849.     USER 
  8850.               write to the user ini file using HINI_USER(PROFILE) 
  8851.  
  8852.     SYSTEM 
  8853.               write to the systemr ini file using HINI_SYSTEM(PROFILE) 
  8854.  
  8855.  
  8856. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings - Parameter pszApp ΓòÉΓòÉΓòÉ
  8857.  
  8858. pszApp (PSZ) - input 
  8859.     Name of the INI application name. 
  8860.  
  8861.     Note:  This application name should identify the WPS class in order not to 
  8862.     mix up with settings of other WPS classes using this function, if writing 
  8863.     to the same INI file ! 
  8864.  
  8865.  
  8866. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings - Parameter pszKey ΓòÉΓòÉΓòÉ
  8867.  
  8868. pszKey (PSZ) - input 
  8869.     Name of the INI application key. 
  8870.  
  8871.     This parameter can be left NULL, then the persistent WPS object handle is 
  8872.     being used to generate a unique key id. 
  8873.  
  8874.     Note:  If the WPS class specifies a key, it is its responsability to make 
  8875.     sure, that the key is unique in order to not mix up with settings of 
  8876.     another object of the same class. 
  8877.  
  8878.  
  8879. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings - Parameters ΓòÉΓòÉΓòÉ
  8880.  
  8881. hvt (HVALUETABLE) - input 
  8882.     Valuetable handle. 
  8883.  
  8884.  pszFilename (PSZ) - input 
  8885.     Address of the ASCIIZ filename of the INI file to read the settings from. 
  8886.  
  8887.     The following names are reserved to read from the user or system ini: 
  8888.  
  8889.     Name 
  8890.               INI file 
  8891.  
  8892.     USER 
  8893.               write to the user ini file using HINI_USER(PROFILE) 
  8894.  
  8895.     SYSTEM 
  8896.               write to the systemr ini file using HINI_SYSTEM(PROFILE) 
  8897.  
  8898.  pszApp (PSZ) - input 
  8899.     Name of the INI application name. 
  8900.  
  8901.     Note:  This application name should identify the WPS class in order not to 
  8902.     mix up with settings of other WPS classes using this function, if writing 
  8903.     to the same INI file ! 
  8904.  
  8905.  pszKey (PSZ) - input 
  8906.     Name of the INI application key. 
  8907.  
  8908.     This parameter can be left NULL, then the persistent WPS object handle is 
  8909.     being used to generate a unique key id. 
  8910.  
  8911.     Note:  If the WPS class specifies a key, it is its responsability to make 
  8912.     sure, that the key is unique in order to not mix up with settings of 
  8913.     another object of the same class. 
  8914.  
  8915.  fResult (BOOL) - returns 
  8916.     Success indicator. 
  8917.  
  8918.     TRUE 
  8919.               Settings could be restored and updated. 
  8920.     FALSE 
  8921.               A validation error occurred. 
  8922.  
  8923.  
  8924. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings Return Value - fResult ΓòÉΓòÉΓòÉ
  8925.  
  8926. fResult (BOOL) - returns 
  8927.     Success indicator. 
  8928.  
  8929.     TRUE 
  8930.               Settings could be restored and updated. 
  8931.     FALSE 
  8932.               A validation error occurred. 
  8933.  
  8934.  
  8935. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings - Remarks ΓòÉΓòÉΓòÉ
  8936.  
  8937. This function is to be called during _wpRestoreState, if the settings have been 
  8938. saved externally before as a settings string. 
  8939.  
  8940. This function restores the settings being previously saved with 
  8941. WtkSaveObjectSettings.. 
  8942.  
  8943.  
  8944. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectSettings - Related functions ΓòÉΓòÉΓòÉ
  8945.  
  8946. Related Functions 
  8947.  
  8948. none 
  8949.  
  8950.  
  8951. ΓòÉΓòÉΓòÉ 8.75. WtkRestoreObjectState ΓòÉΓòÉΓòÉ
  8952.  
  8953. Select an item: 
  8954.  
  8955.      Syntax 
  8956.      Parameters 
  8957.      Returns 
  8958.      Remarks 
  8959.      Related Functions 
  8960.  
  8961.  
  8962. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectState - Syntax ΓòÉΓòÉΓòÉ
  8963.  
  8964. This function restores the settings of an object instance being previously 
  8965. saved with WtkSaveState. Both the settings valuetable and currently active GUI 
  8966. controls corresponding to the restored values are updated. 
  8967.  
  8968. #define INCL_WTKSETTINGS
  8969. #include <wpstk.h>
  8970.  
  8971. HVALUETABLE   hvt;        /* Valuetable handle.                  */
  8972. PSZ           pszClass;   /* Address of a unique ASCIIZ string.  */
  8973. BOOL          fResult;    /* Success indicator.                  */
  8974.  
  8975. fResult = WtkRestoreObjectState( hvt, pszClass);
  8976.  
  8977.  
  8978. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectState - Parameter hvt ΓòÉΓòÉΓòÉ
  8979.  
  8980. hvt (HVALUETABLE) - input 
  8981.     Valuetable handle. 
  8982.  
  8983.  
  8984. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectState - Parameter pszClass ΓòÉΓòÉΓòÉ
  8985.  
  8986. pszClass (PSZ) - input 
  8987.     Address of a unique ASCIIZ string. 
  8988.  
  8989.     The class name is recommended, but not enforced. 
  8990.  
  8991.  
  8992. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectState - Parameters ΓòÉΓòÉΓòÉ
  8993.  
  8994. hvt (HVALUETABLE) - input 
  8995.     Valuetable handle. 
  8996.  
  8997.  pszClass (PSZ) - input 
  8998.     Address of a unique ASCIIZ string. 
  8999.  
  9000.     The class name is recommended, but not enforced. 
  9001.  
  9002.  fResult (BOOL) - returns 
  9003.     Success indicator. 
  9004.  
  9005.     TRUE 
  9006.               Settings could be restored and updated. 
  9007.     FALSE 
  9008.               A validation error occurred. 
  9009.  
  9010.  
  9011. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectState Return Value - fResult ΓòÉΓòÉΓòÉ
  9012.  
  9013. fResult (BOOL) - returns 
  9014.     Success indicator. 
  9015.  
  9016.     TRUE 
  9017.               Settings could be restored and updated. 
  9018.     FALSE 
  9019.               A validation error occurred. 
  9020.  
  9021.  
  9022. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectState - Remarks ΓòÉΓòÉΓòÉ
  9023.  
  9024. This function is to be called during _wpRestoreState to restore all current 
  9025. settings values handled by Settings and Details Manager. 
  9026.  
  9027. You need to specify unique settings ids in order to have settings values stored 
  9028. with this API. 
  9029.  
  9030. This function restores the settings being previously saved with 
  9031. WtkSaveObjectState. 
  9032.  
  9033.  
  9034. ΓòÉΓòÉΓòÉ <hidden> WtkRestoreObjectState - Related functions ΓòÉΓòÉΓòÉ
  9035.  
  9036. Related Functions 
  9037.  
  9038. none 
  9039.  
  9040.  
  9041. ΓòÉΓòÉΓòÉ 8.76. WtkSaveEa ΓòÉΓòÉΓòÉ
  9042.  
  9043. Select an item: 
  9044.  
  9045.      Syntax 
  9046.      Parameters 
  9047.      Returns 
  9048.      Remarks 
  9049.      Related Functions 
  9050.  
  9051.  
  9052. ΓòÉΓòÉΓòÉ <hidden> WtkSaveEa - Syntax ΓòÉΓòÉΓòÉ
  9053.  
  9054. This function writes an extended attribute from memory to disk. 
  9055.  
  9056. #define INCL_WTKEAS
  9057. #include <wpstk.h>
  9058.  
  9059. HEA      hea;          /* Handle to the extended attribute.                                              */
  9060. BOOL     fWriteThru;   /* A flag to bypass the cache and write the extended attribute directly to disk.  */
  9061. BYTE     fEA;          /* The flags to be set for this extended attribute flags.                         */
  9062. APIRET   ulrc;         /* Return Code.                                                                   */
  9063.  
  9064. ulrc = WtkSaveEa( hea, fWriteThru, fEA);
  9065.  
  9066.  
  9067. ΓòÉΓòÉΓòÉ <hidden> WtkSaveEa - Parameter hea ΓòÉΓòÉΓòÉ
  9068.  
  9069. hea (HEA) - input 
  9070.     Handle to the extended attribute. 
  9071.  
  9072.  
  9073. ΓòÉΓòÉΓòÉ <hidden> WtkSaveEa - Parameter fWriteThru ΓòÉΓòÉΓòÉ
  9074.  
  9075. fWriteThru (BOOL) - input 
  9076.     A flag to bypass the cache and write the extended attribute directly to 
  9077.     disk. 
  9078.  
  9079.  
  9080. ΓòÉΓòÉΓòÉ <hidden> WtkSaveEa - Parameter fEA ΓòÉΓòÉΓòÉ
  9081.  
  9082. fEA (BYTE) - input 
  9083.     The flags to be set for this extended attribute flags. 
  9084.  
  9085.     Specify FEA_NEEDEDEA in order to mark the extended attribute as critical. 
  9086.     Otherwise set this parameter to zero. 
  9087.  
  9088.  
  9089. ΓòÉΓòÉΓòÉ <hidden> WtkSaveEa - Parameters ΓòÉΓòÉΓòÉ
  9090.  
  9091. hea (HEA) - input 
  9092.     Handle to the extended attribute. 
  9093.  
  9094.  fWriteThru (BOOL) - input 
  9095.     A flag to bypass the cache and write the extended attribute directly to 
  9096.     disk. 
  9097.  
  9098.  fEA (BYTE) - input 
  9099.     The flags to be set for this extended attribute flags. 
  9100.  
  9101.     Specify FEA_NEEDEDEA in order to mark the extended attribute as critical. 
  9102.     Otherwise set this parameter to zero. 
  9103.  
  9104.  ulrc (APIRET) - returns 
  9105.     Return Code. 
  9106.  
  9107.     WtkSaveEa returns one of the following return codes: 
  9108.  
  9109.     0         NO_ERROR 
  9110.     6         ERROR_INVALID_HANDLE 
  9111.  
  9112.     or return codes of the following functions 
  9113.  
  9114.         DosSetPathInfo 
  9115.  
  9116.  
  9117. ΓòÉΓòÉΓòÉ <hidden> WtkSaveEa Return Value - ulrc ΓòÉΓòÉΓòÉ
  9118.  
  9119. ulrc (APIRET) - returns 
  9120.     Return Code. 
  9121.  
  9122.     WtkSaveEa returns one of the following return codes: 
  9123.  
  9124.     0         NO_ERROR 
  9125.     6         ERROR_INVALID_HANDLE 
  9126.  
  9127.     or return codes of the following functions 
  9128.  
  9129.         DosSetPathInfo 
  9130.  
  9131.  
  9132. ΓòÉΓòÉΓòÉ <hidden> WtkSaveEa - Remarks ΓòÉΓòÉΓòÉ
  9133.  
  9134. This function does not deallocate resources for handling the value of the given 
  9135. extended attribute. They must be freeed by calling WtkCloseEa, when not longer 
  9136. needed. 
  9137.  
  9138.  
  9139. ΓòÉΓòÉΓòÉ <hidden> WtkSaveEa - Related functions ΓòÉΓòÉΓòÉ
  9140.  
  9141. Related Functions 
  9142.  
  9143. none 
  9144.  
  9145.  
  9146. ΓòÉΓòÉΓòÉ 8.77. WtkSaveObjectSettings ΓòÉΓòÉΓòÉ
  9147.  
  9148. Select an item: 
  9149.  
  9150.      Syntax 
  9151.      Parameters 
  9152.      Returns 
  9153.      Remarks 
  9154.      Related Functions 
  9155.  
  9156.  
  9157. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings - Syntax ΓòÉΓòÉΓòÉ
  9158.  
  9159. This saves the current settings of an object instance values externally in an 
  9160. INI file of choice. Use WtkSaveState instead to save the settings within the 
  9161. WPS repository as usual. 
  9162.  
  9163. #define INCL_WTKSETTINGS
  9164. #include <wpstk.h>
  9165.  
  9166. HVALUETABLE   hvt;           /* Valuetable handle.                                                        */
  9167. PSZ           pszFilename;   /* Address of the ASCIIZ filename of the INI file to write the settings to.  */
  9168. PSZ           pszApp;        /* Name of the INI application name.                                         */
  9169. PSZ           pszKey;        /* Name of the INI application key.                                          */
  9170. BOOL          fResult;       /* Success indicator.                                                        */
  9171.  
  9172. fResult = WtkSaveObjectSettings( hvt, pszFilename, pszApp, pszKey);
  9173.  
  9174.  
  9175. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings - Parameter hvt ΓòÉΓòÉΓòÉ
  9176.  
  9177. hvt (HVALUETABLE) - input 
  9178.     Valuetable handle. 
  9179.  
  9180.  
  9181. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings - Parameter pszFilename ΓòÉΓòÉΓòÉ
  9182.  
  9183. pszFilename (PSZ) - input 
  9184.     Address of the ASCIIZ filename of the INI file to write the settings to. 
  9185.  
  9186.     The following names are reserved to write to the user or system ini: 
  9187.  
  9188.     Name      INI file 
  9189.  
  9190.     USER      write to the user ini file using HINI_USER(PROFILE) 
  9191.  
  9192.     SYSTEM    write to the systemr ini file using HINI_SYSTEM(PROFILE) 
  9193.  
  9194.  
  9195. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings - Parameter pszApp ΓòÉΓòÉΓòÉ
  9196.  
  9197. pszApp (PSZ) - input 
  9198.     Name of the INI application name. 
  9199.  
  9200.     Note:  This application name should identify the WPS class in order not to 
  9201.     mix up with settings of other WPS classes using this function, if writing 
  9202.     to the same INI file ! 
  9203.  
  9204.  
  9205. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings - Parameter pszKey ΓòÉΓòÉΓòÉ
  9206.  
  9207. pszKey (PSZ) - input 
  9208.     Name of the INI application key. 
  9209.  
  9210.     This parameter can be left NULL, then the persistent WPS object handle is 
  9211.     being used to generate a unique key id. 
  9212.  
  9213.     Note:  If the WPS class specifies a key, it is its responsability to make 
  9214.     sure, that the key is unique in order to not mix up with settings of 
  9215.     another object of the same class. 
  9216.  
  9217.  
  9218. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings - Parameters ΓòÉΓòÉΓòÉ
  9219.  
  9220. hvt (HVALUETABLE) - input 
  9221.     Valuetable handle. 
  9222.  
  9223.  pszFilename (PSZ) - input 
  9224.     Address of the ASCIIZ filename of the INI file to write the settings to. 
  9225.  
  9226.     The following names are reserved to write to the user or system ini: 
  9227.  
  9228.     Name      INI file 
  9229.  
  9230.     USER      write to the user ini file using HINI_USER(PROFILE) 
  9231.  
  9232.     SYSTEM    write to the systemr ini file using HINI_SYSTEM(PROFILE) 
  9233.  
  9234.  pszApp (PSZ) - input 
  9235.     Name of the INI application name. 
  9236.  
  9237.     Note:  This application name should identify the WPS class in order not to 
  9238.     mix up with settings of other WPS classes using this function, if writing 
  9239.     to the same INI file ! 
  9240.  
  9241.  pszKey (PSZ) - input 
  9242.     Name of the INI application key. 
  9243.  
  9244.     This parameter can be left NULL, then the persistent WPS object handle is 
  9245.     being used to generate a unique key id. 
  9246.  
  9247.     Note:  If the WPS class specifies a key, it is its responsability to make 
  9248.     sure, that the key is unique in order to not mix up with settings of 
  9249.     another object of the same class. 
  9250.  
  9251.  fResult (BOOL) - returns 
  9252.     Success indicator. 
  9253.  
  9254.     TRUE 
  9255.               Settings could be saved. 
  9256.     FALSE 
  9257.               A validation error occurred. 
  9258.  
  9259.  
  9260. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings Return Value - fResult ΓòÉΓòÉΓòÉ
  9261.  
  9262. fResult (BOOL) - returns 
  9263.     Success indicator. 
  9264.  
  9265.     TRUE 
  9266.               Settings could be saved. 
  9267.     FALSE 
  9268.               A validation error occurred. 
  9269.  
  9270.  
  9271. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings - Remarks ΓòÉΓòÉΓòÉ
  9272.  
  9273. This function is to be called during _wpSaveState, if the settings are to be 
  9274. saved externally as a settings string. 
  9275.  
  9276. While the settings of general WPS classes can only be stored in the OS/2 INI 
  9277. file, this function saves the object settings being handled by this settings 
  9278. manager API in an INI file of choice. 
  9279.  
  9280. The settings can be restored by using WtkRestoreObjectSettings.. 
  9281.  
  9282.  
  9283. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectSettings - Related functions ΓòÉΓòÉΓòÉ
  9284.  
  9285. Related Functions 
  9286.  
  9287. none 
  9288.  
  9289.  
  9290. ΓòÉΓòÉΓòÉ 8.78. WtkSaveObjectState ΓòÉΓòÉΓòÉ
  9291.  
  9292. Select an item: 
  9293.  
  9294.      Syntax 
  9295.      Parameters 
  9296.      Returns 
  9297.      Remarks 
  9298.      Related Functions 
  9299.  
  9300.  
  9301. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectState - Syntax ΓòÉΓòÉΓòÉ
  9302.  
  9303. This saves the current settings values of an object instance within the WPS 
  9304. repository. 
  9305.  
  9306. #define INCL_WTKSETTINGS
  9307. #include <wpstk.h>
  9308.  
  9309. HVALUETABLE   hvt;        /* Valuetable handle.                  */
  9310. PSZ           pszClass;   /* Address of a unique ASCIIZ string.  */
  9311. BOOL          fResult;    /* Success indicator.                  */
  9312.  
  9313. fResult = WtkSaveObjectState( hvt, pszClass);
  9314.  
  9315.  
  9316. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectState - Parameter hvt ΓòÉΓòÉΓòÉ
  9317.  
  9318. hvt (HVALUETABLE) - input 
  9319.     Valuetable handle. 
  9320.  
  9321.  
  9322. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectState - Parameter pszClass ΓòÉΓòÉΓòÉ
  9323.  
  9324. pszClass (PSZ) - input 
  9325.     Address of a unique ASCIIZ string. 
  9326.  
  9327.     The class name is recommended, but not enforced. 
  9328.  
  9329.  
  9330. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectState - Parameters ΓòÉΓòÉΓòÉ
  9331.  
  9332. hvt (HVALUETABLE) - input 
  9333.     Valuetable handle. 
  9334.  
  9335.  pszClass (PSZ) - input 
  9336.     Address of a unique ASCIIZ string. 
  9337.  
  9338.     The class name is recommended, but not enforced. 
  9339.  
  9340.  fResult (BOOL) - returns 
  9341.     Success indicator. 
  9342.  
  9343.     TRUE 
  9344.               Settings could be saved. 
  9345.     FALSE 
  9346.               A validation error occurred. 
  9347.  
  9348.  
  9349. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectState Return Value - fResult ΓòÉΓòÉΓòÉ
  9350.  
  9351. fResult (BOOL) - returns 
  9352.     Success indicator. 
  9353.  
  9354.     TRUE 
  9355.               Settings could be saved. 
  9356.     FALSE 
  9357.               A validation error occurred. 
  9358.  
  9359.  
  9360. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectState - Remarks ΓòÉΓòÉΓòÉ
  9361.  
  9362. This function is to be called during _wpSaveState to save all current settings 
  9363. values handled by Settings and Details Manager. 
  9364.  
  9365. You need to specify unique settings ids in order to have settings values stored 
  9366. with this API. 
  9367.  
  9368. The settings can be restored by using WtkRestoreObjectState.. 
  9369.  
  9370.  
  9371. ΓòÉΓòÉΓòÉ <hidden> WtkSaveObjectState - Related functions ΓòÉΓòÉΓòÉ
  9372.  
  9373. Related Functions 
  9374.  
  9375. none 
  9376.  
  9377.  
  9378. ΓòÉΓòÉΓòÉ 8.79. WtkSetCDateTime ΓòÉΓòÉΓòÉ
  9379.  
  9380. Select an item: 
  9381.  
  9382.      Syntax 
  9383.      Parameters 
  9384.      Returns 
  9385.      Remarks 
  9386.      Related Functions 
  9387.  
  9388.  
  9389. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Syntax ΓòÉΓòÉΓòÉ
  9390.  
  9391. This function sets up a CDATE and/or CTIME structure in a single API call. 
  9392.  
  9393. #define INCL_WTKUTLTIME
  9394. #include <wpstk.h>
  9395.  
  9396. UCHAR    uchDay;       /* Day of the month, using values 1 through 31.   */
  9397. UCHAR    uchMonth;     /* Month of the year, using values 1 through 12.  */
  9398. USHORT   usYear;       /* Year, using values in a four digit format.     */
  9399. UCHAR    uchHours;     /* Hour, using values 0 through 23.               */
  9400. UCHAR    uchMinutes;   /* Minute, using values 0 through 59.             */
  9401. UCHAR    uchSeconds;   /* Second, using values 0 through 59.             */
  9402. PCDATE   pcdate;       /* Address of the CDATE structure to set up.      */
  9403. PCTIME   pctime;       /* Address of the CTIME structure to set up.      */
  9404. BOOL     fResult;      /* Success indicator.                             */
  9405.  
  9406. fResult = WtkSetCDateTime( uchDay, uchMonth, usYear, uchHours, uchMinutes, uchSeconds, pcdate, pctime);
  9407.  
  9408.  
  9409. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameter uchDay ΓòÉΓòÉΓòÉ
  9410.  
  9411. uchDay (UCHAR) - input 
  9412.     Day of the month, using values 1 through 31. 
  9413.  
  9414.  
  9415. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameter uchMonth ΓòÉΓòÉΓòÉ
  9416.  
  9417. uchMonth (UCHAR) - input 
  9418.     Month of the year, using values 1 through 12. 
  9419.  
  9420.  
  9421. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameter usYear ΓòÉΓòÉΓòÉ
  9422.  
  9423. usYear (USHORT) - input 
  9424.     Year, using values in a four digit format. 
  9425.  
  9426.  
  9427. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameter uchHours ΓòÉΓòÉΓòÉ
  9428.  
  9429. uchHours (UCHAR) - input 
  9430.     Hour, using values 0 through 23. 
  9431.  
  9432.  
  9433. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameter uchMinutes ΓòÉΓòÉΓòÉ
  9434.  
  9435. uchMinutes (UCHAR) - input 
  9436.     Minute, using values 0 through 59. 
  9437.  
  9438.  
  9439. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameter uchSeconds ΓòÉΓòÉΓòÉ
  9440.  
  9441. uchSeconds (UCHAR) - input 
  9442.     Second, using values 0 through 59. 
  9443.  
  9444.  
  9445. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameter pcdate ΓòÉΓòÉΓòÉ
  9446.  
  9447. pcdate (PCDATE) - input 
  9448.     Address of the CDATE structure to set up. 
  9449.  
  9450.     If the setup of a CDATE structure is not required, leave this parameter 
  9451.     NULL. 
  9452.  
  9453.  
  9454. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameter pctime ΓòÉΓòÉΓòÉ
  9455.  
  9456. pctime (PCTIME) - input 
  9457.     Address of the CTIME structure to set up. 
  9458.  
  9459.     If the setup of a CTIME structure is not required, leave this parameter 
  9460.     NULL. 
  9461.  
  9462.  
  9463. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Parameters ΓòÉΓòÉΓòÉ
  9464.  
  9465. uchDay (UCHAR) - input 
  9466.     Day of the month, using values 1 through 31. 
  9467.  
  9468.  uchMonth (UCHAR) - input 
  9469.     Month of the year, using values 1 through 12. 
  9470.  
  9471.  usYear (USHORT) - input 
  9472.     Year, using values in a four digit format. 
  9473.  
  9474.  uchHours (UCHAR) - input 
  9475.     Hour, using values 0 through 23. 
  9476.  
  9477.  uchMinutes (UCHAR) - input 
  9478.     Minute, using values 0 through 59. 
  9479.  
  9480.  uchSeconds (UCHAR) - input 
  9481.     Second, using values 0 through 59. 
  9482.  
  9483.  pcdate (PCDATE) - input 
  9484.     Address of the CDATE structure to set up. 
  9485.  
  9486.     If the setup of a CDATE structure is not required, leave this parameter 
  9487.     NULL. 
  9488.  
  9489.  pctime (PCTIME) - input 
  9490.     Address of the CTIME structure to set up. 
  9491.  
  9492.     If the setup of a CTIME structure is not required, leave this parameter 
  9493.     NULL. 
  9494.  
  9495.  fResult (BOOL) - returns 
  9496.     Success indicator. 
  9497.  
  9498.     TRUE 
  9499.               Conversion successful. 
  9500.     FALSE 
  9501.               Conversion not successful or invalid parameters. 
  9502.  
  9503.  
  9504. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime Return Value - fResult ΓòÉΓòÉΓòÉ
  9505.  
  9506. fResult (BOOL) - returns 
  9507.     Success indicator. 
  9508.  
  9509.     TRUE 
  9510.               Conversion successful. 
  9511.     FALSE 
  9512.               Conversion not successful or invalid parameters. 
  9513.  
  9514.  
  9515. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Remarks ΓòÉΓòÉΓòÉ
  9516.  
  9517. This function does not check any of the date or time values. It only fails, if 
  9518. both pointers to the CDATE and CTIME structure are NULL. 
  9519.  
  9520.  
  9521. ΓòÉΓòÉΓòÉ <hidden> WtkSetCDateTime - Related functions ΓòÉΓòÉΓòÉ
  9522.  
  9523. Related Functions 
  9524.  
  9525. none 
  9526.  
  9527.  
  9528. ΓòÉΓòÉΓòÉ 8.80. WtkSetCurrentDir ΓòÉΓòÉΓòÉ
  9529.  
  9530. Select an item: 
  9531.  
  9532.      Syntax 
  9533.      Parameters 
  9534.      Returns 
  9535.      Remarks 
  9536.      Related Functions 
  9537.  
  9538.  
  9539. ΓòÉΓòÉΓòÉ <hidden> WtkSetCurrentDir - Syntax ΓòÉΓòÉΓòÉ
  9540.  
  9541. This function sets the current drive and the directory for a given drive. If a 
  9542. drive is not given, the current drive is being assumed. 
  9543.  
  9544. #define INCL_WTKUTLFILE
  9545. #include <wpstk.h>
  9546.  
  9547. PSZ      pszDirectory;   /* The drive and directory to be set current.  */
  9548. APIRET   ulrc;           /* Return Code.                                */
  9549.  
  9550. ulrc = WtkSetCurrentDir( pszDirectory);
  9551.  
  9552.  
  9553. ΓòÉΓòÉΓòÉ <hidden> WtkSetCurrentDir - Parameter pszDirectory ΓòÉΓòÉΓòÉ
  9554.  
  9555. pszDirectory (PSZ) - 
  9556.     The drive and directory to be set current. 
  9557.  
  9558.     If a drive is not given, the current drive is being assumed. 
  9559.  
  9560.     The directory name may contain ?: for the drive in order to set the boot 
  9561.     drive as the default drive. 
  9562.  
  9563.  
  9564. ΓòÉΓòÉΓòÉ <hidden> WtkSetCurrentDir - Parameters ΓòÉΓòÉΓòÉ
  9565.  
  9566. pszDirectory (PSZ) - 
  9567.     The drive and directory to be set current. 
  9568.  
  9569.     If a drive is not given, the current drive is being assumed. 
  9570.  
  9571.     The directory name may contain ?: for the drive in order to set the boot 
  9572.     drive as the default drive. 
  9573.  
  9574.  ulrc (APIRET) - returns 
  9575.     Return Code. 
  9576.  
  9577.     WtkSetCurrentDir returns one of the following return codes: 
  9578.  
  9579.     0         NO_ERROR 
  9580.     87        ERROR_INVALID_PARAMETER 
  9581.  
  9582.     or return codes of the following functions 
  9583.  
  9584.         DosSetDefaultDisk 
  9585.         DosSetCurrentDir 
  9586.  
  9587.  
  9588. ΓòÉΓòÉΓòÉ <hidden> WtkSetCurrentDir Return Value - ulrc ΓòÉΓòÉΓòÉ
  9589.  
  9590. ulrc (APIRET) - returns 
  9591.     Return Code. 
  9592.  
  9593.     WtkSetCurrentDir returns one of the following return codes: 
  9594.  
  9595.     0         NO_ERROR 
  9596.     87        ERROR_INVALID_PARAMETER 
  9597.  
  9598.     or return codes of the following functions 
  9599.  
  9600.         DosSetDefaultDisk 
  9601.         DosSetCurrentDir 
  9602.  
  9603.  
  9604. ΓòÉΓòÉΓòÉ <hidden> WtkSetCurrentDir - Remarks ΓòÉΓòÉΓòÉ
  9605.  
  9606. In opposite to DosSetCurrentDir, this function sets also a given drive as 
  9607. default disk. 
  9608.  
  9609. This function supports boot drive recognition. Specify ?: for the drive in 
  9610. order to set the boot drive as the default drive. 
  9611.  
  9612.  
  9613. ΓòÉΓòÉΓòÉ <hidden> WtkSetCurrentDir - Related functions ΓòÉΓòÉΓòÉ
  9614.  
  9615. Related Functions 
  9616.  
  9617. none 
  9618.  
  9619.  
  9620. ΓòÉΓòÉΓòÉ 8.81. WtkSetDateTime ΓòÉΓòÉΓòÉ
  9621.  
  9622. Select an item: 
  9623.  
  9624.      Syntax 
  9625.      Parameters 
  9626.      Returns 
  9627.      Remarks 
  9628.      Related Functions 
  9629.  
  9630.  
  9631. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Syntax ΓòÉΓòÉΓòÉ
  9632.  
  9633. This function sets up a DATETIME structure in a single API call. 
  9634.  
  9635. #define INCL_WTKUTLTIME
  9636. #include <wpstk.h>
  9637.  
  9638. UCHAR       uchDay;       /* Day of the month, using values 1 through 31.   */
  9639. UCHAR       uchMonth;     /* Month of the year, using values 1 through 12.  */
  9640. USHORT      usYear;       /* Year, using values from 1900 up.               */
  9641. UCHAR       uchHours;     /* Hour, using values 0 through 23.               */
  9642. UCHAR       uchMinutes;   /* Minute, using values 0 through 59.             */
  9643. UCHAR       uchSeconds;   /* Second, using values 0 through 59.             */
  9644. PDATETIME   pdt;          /* Address of the DATETIME structure to set up.   */
  9645. BOOL        fResult;      /* Success indicator.                             */
  9646.  
  9647. fResult = WtkSetDateTime( uchDay, uchMonth, usYear, uchHours, uchMinutes, uchSeconds, pdt);
  9648.  
  9649.  
  9650. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Parameter uchDay ΓòÉΓòÉΓòÉ
  9651.  
  9652. uchDay (UCHAR) - input 
  9653.     Day of the month, using values 1 through 31. 
  9654.  
  9655.  
  9656. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Parameter uchMonth ΓòÉΓòÉΓòÉ
  9657.  
  9658. uchMonth (UCHAR) - input 
  9659.     Month of the year, using values 1 through 12. 
  9660.  
  9661.  
  9662. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Parameter usYear ΓòÉΓòÉΓòÉ
  9663.  
  9664. usYear (USHORT) - input 
  9665.     Year, using values from 1900 up. 
  9666.  
  9667.  
  9668. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Parameter uchHours ΓòÉΓòÉΓòÉ
  9669.  
  9670. uchHours (UCHAR) - input 
  9671.     Hour, using values 0 through 23. 
  9672.  
  9673.  
  9674. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Parameter uchMinutes ΓòÉΓòÉΓòÉ
  9675.  
  9676. uchMinutes (UCHAR) - input 
  9677.     Minute, using values 0 through 59. 
  9678.  
  9679.  
  9680. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Parameter uchSeconds ΓòÉΓòÉΓòÉ
  9681.  
  9682. uchSeconds (UCHAR) - input 
  9683.     Second, using values 0 through 59. 
  9684.  
  9685.  
  9686. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Parameter pdt ΓòÉΓòÉΓòÉ
  9687.  
  9688. pdt (PDATETIME) - output 
  9689.     Address of the DATETIME structure to set up. 
  9690.  
  9691.  
  9692. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Parameters ΓòÉΓòÉΓòÉ
  9693.  
  9694. uchDay (UCHAR) - input 
  9695.     Day of the month, using values 1 through 31. 
  9696.  
  9697.  uchMonth (UCHAR) - input 
  9698.     Month of the year, using values 1 through 12. 
  9699.  
  9700.  usYear (USHORT) - input 
  9701.     Year, using values from 1900 up. 
  9702.  
  9703.  uchHours (UCHAR) - input 
  9704.     Hour, using values 0 through 23. 
  9705.  
  9706.  uchMinutes (UCHAR) - input 
  9707.     Minute, using values 0 through 59. 
  9708.  
  9709.  uchSeconds (UCHAR) - input 
  9710.     Second, using values 0 through 59. 
  9711.  
  9712.  pdt (PDATETIME) - output 
  9713.     Address of the DATETIME structure to set up. 
  9714.  
  9715.  fResult (BOOL) - returns 
  9716.     Success indicator. 
  9717.  
  9718.     TRUE 
  9719.               Successful 
  9720.     FALSE 
  9721.               Not successful (due to invalid parameter). 
  9722.  
  9723.  
  9724. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime Return Value - fResult ΓòÉΓòÉΓòÉ
  9725.  
  9726. fResult (BOOL) - returns 
  9727.     Success indicator. 
  9728.  
  9729.     TRUE 
  9730.               Successful 
  9731.     FALSE 
  9732.               Not successful (due to invalid parameter). 
  9733.  
  9734.  
  9735. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Remarks ΓòÉΓòÉΓòÉ
  9736.  
  9737. This function does not check any of the date or time values. It only fails, if 
  9738. the provided pointer to the DATETIME structure is NULL. 
  9739.  
  9740.  
  9741. ΓòÉΓòÉΓòÉ <hidden> WtkSetDateTime - Related functions ΓòÉΓòÉΓòÉ
  9742.  
  9743. Related Functions 
  9744.  
  9745. none 
  9746.  
  9747.  
  9748. ΓòÉΓòÉΓòÉ 8.82. WtkSetErrorInfo ΓòÉΓòÉΓòÉ
  9749.  
  9750. Select an item: 
  9751.  
  9752.      Syntax 
  9753.      Parameters 
  9754.      Returns 
  9755.      Remarks 
  9756.      Related Functions 
  9757.  
  9758.  
  9759. ΓòÉΓòÉΓòÉ <hidden> WtkSetErrorInfo - Syntax ΓòÉΓòÉΓòÉ
  9760.  
  9761. This function sets the error info, that can be obtained later by 
  9762. WinGetLastError and WinGetErrorInfo. 
  9763.  
  9764. #define INCL_WTKUTLERROR
  9765. #include <wpstk.h>
  9766.  
  9767. APIRET   rc;        /* Return code to be used when creating the error information.  */
  9768. BOOL     fResult;   /* Error indicator.                                             */
  9769.  
  9770. fResult = WtkSetErrorInfo( rc);
  9771.  
  9772.  
  9773. ΓòÉΓòÉΓòÉ <hidden> WtkSetErrorInfo - Parameter rc ΓòÉΓòÉΓòÉ
  9774.  
  9775. rc (APIRET) - input 
  9776.     Return code to be used when creating the error information. 
  9777.  
  9778.     When rc is set to NO_ERROR (0) or PMHERR_USE_EXISTING_ERRORINFO (-1), 
  9779.     WtkSetErrorInfo takes no action. 
  9780.  
  9781.  
  9782. ΓòÉΓòÉΓòÉ <hidden> WtkSetErrorInfo - Parameters ΓòÉΓòÉΓòÉ
  9783.  
  9784. rc (APIRET) - input 
  9785.     Return code to be used when creating the error information. 
  9786.  
  9787.     When rc is set to NO_ERROR (0) or PMHERR_USE_EXISTING_ERRORINFO (-1), 
  9788.     WtkSetErrorInfo takes no action. 
  9789.  
  9790.  fResult (BOOL) - returns 
  9791.     Error indicator. 
  9792.  
  9793.     TRUE 
  9794.               rc was reporting NO_ERROR. 
  9795.     FALSE 
  9796.               rc was reporting an error. 
  9797.  
  9798.  
  9799. ΓòÉΓòÉΓòÉ <hidden> WtkSetErrorInfo Return Value - fResult ΓòÉΓòÉΓòÉ
  9800.  
  9801. fResult (BOOL) - returns 
  9802.     Error indicator. 
  9803.  
  9804.     TRUE 
  9805.               rc was reporting NO_ERROR. 
  9806.     FALSE 
  9807.               rc was reporting an error. 
  9808.  
  9809.  
  9810. ΓòÉΓòÉΓòÉ <hidden> WtkSetErrorInfo - Remarks ΓòÉΓòÉΓòÉ
  9811.  
  9812. WtkSetErrorInfo distincts between OS/2 control program errors and errors of the 
  9813. presentation manager API, and sets the error info according to that 
  9814. distinction. 
  9815.  
  9816. When rc is set to NO_ERROR (0) or PMHERR_USE_EXISTING_ERRORINFO (-1), 
  9817. WtkSetErrorInfo takes no action. This enables the caller to invoke this 
  9818. function always without taking care, if an error occurred or not. More, 
  9819. PMHERR_USE_EXISTING_ERRORINFO can preserve the error info of a previous failed 
  9820. Win* API call, but still lets WtkSetErrorInfo return FALSE. 
  9821.  
  9822. When the callers function returns BOOL, the following line would automatically 
  9823. set the error info and return the appropriate value: 
  9824.  
  9825. return WtkSetErrorInfo( rc);
  9826.  
  9827.  
  9828. ΓòÉΓòÉΓòÉ <hidden> WtkSetErrorInfo - Related functions ΓòÉΓòÉΓòÉ
  9829.  
  9830. Related Functions 
  9831.  
  9832. none 
  9833.  
  9834.  
  9835. ΓòÉΓòÉΓòÉ 8.83. WtkSetFDateTime ΓòÉΓòÉΓòÉ
  9836.  
  9837. Select an item: 
  9838.  
  9839.      Syntax 
  9840.      Parameters 
  9841.      Returns 
  9842.      Remarks 
  9843.      Related Functions 
  9844.  
  9845.  
  9846. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Syntax ΓòÉΓòÉΓòÉ
  9847.  
  9848. This function sets up a FDATE and/or FTIME structure in a single API call. 
  9849.  
  9850. #define INCL_WTKUTLTIME
  9851. #include <wpstk.h>
  9852.  
  9853. UCHAR    uchDay;       /* Day of the month, using values 1 through 31.   */
  9854. UCHAR    uchMonth;     /* Month of the year, using values 1 through 12.  */
  9855. USHORT   usYear;       /* Year, using values from 1980 up.               */
  9856. UCHAR    uchHours;     /* Hour, using values 0 through 23.               */
  9857. UCHAR    uchMinutes;   /* Minute, using values 0 through 59.             */
  9858. UCHAR    uchSeconds;   /* Second, using values 0 through 59.             */
  9859. PFDATE   pfdate;       /* Address of the FDATE structure to set up.      */
  9860. PFTIME   pftime;       /* Address of the FTIME structure to set up.      */
  9861. BOOL     fResult;      /* Success indicator.                             */
  9862.  
  9863. fResult = WtkSetFDateTime( uchDay, uchMonth, usYear, uchHours, uchMinutes, uchSeconds, pfdate, pftime);
  9864.  
  9865.  
  9866. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameter uchDay ΓòÉΓòÉΓòÉ
  9867.  
  9868. uchDay (UCHAR) - input 
  9869.     Day of the month, using values 1 through 31. 
  9870.  
  9871.  
  9872. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameter uchMonth ΓòÉΓòÉΓòÉ
  9873.  
  9874. uchMonth (UCHAR) - input 
  9875.     Month of the year, using values 1 through 12. 
  9876.  
  9877.  
  9878. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameter usYear ΓòÉΓòÉΓòÉ
  9879.  
  9880. usYear (USHORT) - input 
  9881.     Year, using values from 1980 up. 
  9882.  
  9883.  
  9884. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameter uchHours ΓòÉΓòÉΓòÉ
  9885.  
  9886. uchHours (UCHAR) - input 
  9887.     Hour, using values 0 through 23. 
  9888.  
  9889.  
  9890. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameter uchMinutes ΓòÉΓòÉΓòÉ
  9891.  
  9892. uchMinutes (UCHAR) - input 
  9893.     Minute, using values 0 through 59. 
  9894.  
  9895.  
  9896. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameter uchSeconds ΓòÉΓòÉΓòÉ
  9897.  
  9898. uchSeconds (UCHAR) - input 
  9899.     Second, using values 0 through 59. 
  9900.  
  9901.  
  9902. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameter pfdate ΓòÉΓòÉΓòÉ
  9903.  
  9904. pfdate (PFDATE) - output 
  9905.     Address of the FDATE structure to set up. 
  9906.  
  9907.     If the setup of a FDATE structure is not required, leave this parameter 
  9908.     NULL. 
  9909.  
  9910.  
  9911. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameter pftime ΓòÉΓòÉΓòÉ
  9912.  
  9913. pftime (PFTIME) - output 
  9914.     Address of the FTIME structure to set up. 
  9915.  
  9916.     If the setup of a FTIME structure is not required, leave this parameter 
  9917.     NULL. 
  9918.  
  9919.  
  9920. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Parameters ΓòÉΓòÉΓòÉ
  9921.  
  9922. uchDay (UCHAR) - input 
  9923.     Day of the month, using values 1 through 31. 
  9924.  
  9925.  uchMonth (UCHAR) - input 
  9926.     Month of the year, using values 1 through 12. 
  9927.  
  9928.  usYear (USHORT) - input 
  9929.     Year, using values from 1980 up. 
  9930.  
  9931.  uchHours (UCHAR) - input 
  9932.     Hour, using values 0 through 23. 
  9933.  
  9934.  uchMinutes (UCHAR) - input 
  9935.     Minute, using values 0 through 59. 
  9936.  
  9937.  uchSeconds (UCHAR) - input 
  9938.     Second, using values 0 through 59. 
  9939.  
  9940.  pfdate (PFDATE) - output 
  9941.     Address of the FDATE structure to set up. 
  9942.  
  9943.     If the setup of a FDATE structure is not required, leave this parameter 
  9944.     NULL. 
  9945.  
  9946.  pftime (PFTIME) - output 
  9947.     Address of the FTIME structure to set up. 
  9948.  
  9949.     If the setup of a FTIME structure is not required, leave this parameter 
  9950.     NULL. 
  9951.  
  9952.  fResult (BOOL) - returns 
  9953.     Success indicator. 
  9954.  
  9955.     TRUE 
  9956.               Conversion successful. 
  9957.     FALSE 
  9958.               Conversion not successful or invalid parameters. 
  9959.  
  9960.  
  9961. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime Return Value - fResult ΓòÉΓòÉΓòÉ
  9962.  
  9963. fResult (BOOL) - returns 
  9964.     Success indicator. 
  9965.  
  9966.     TRUE 
  9967.               Conversion successful. 
  9968.     FALSE 
  9969.               Conversion not successful or invalid parameters. 
  9970.  
  9971.  
  9972. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Remarks ΓòÉΓòÉΓòÉ
  9973.  
  9974. This function does not check any of the date or time values. It only fails, if 
  9975. both pointers to the FDATE and FTIME structure are NULL. 
  9976.  
  9977. Due to limitations of the FAT filesystem 
  9978.  
  9979.      the FDATE structure can store and thus this function can handle only 
  9980.       dates from 1980 up. 
  9981.      the FTIME structure can store and thus this function can handle only 
  9982.       seconds in two seconds steps. As a result, the conversion via this 
  9983.       function results in the loss of one second, if an odd number of seconds 
  9984.       is specified. 
  9985.  
  9986.  
  9987. ΓòÉΓòÉΓòÉ <hidden> WtkSetFDateTime - Related functions ΓòÉΓòÉΓòÉ
  9988.  
  9989. Related Functions 
  9990.  
  9991. none 
  9992.  
  9993.  
  9994. ΓòÉΓòÉΓòÉ 8.84. WtkSetMmfSize ΓòÉΓòÉΓòÉ
  9995.  
  9996. Select an item: 
  9997.  
  9998.      Syntax 
  9999.      Parameters 
  10000.      Returns 
  10001.      Remarks 
  10002.      Related Functions 
  10003.  
  10004.  
  10005. ΓòÉΓòÉΓòÉ <hidden> WtkSetMmfSize - Syntax ΓòÉΓòÉΓòÉ
  10006.  
  10007. This function adjusts the size of a dynamic memory buffer. 
  10008.  
  10009. #define INCL_WTKMMF
  10010. #include <wpstk.h>
  10011.  
  10012. HMMF     hmmf;        /* Handle to the MMF manager.                                      */
  10013. PVOID    pvData;      /* Pointer to the allocated address space to be adjusted in size.  */
  10014. ULONG    ulNewSize;   /* New size of the memory buffer.                                  */
  10015. APIRET   ulrc;        /* Return Code.                                                    */
  10016.  
  10017. ulrc = WtkSetMmfSize( hmmf, pvData, ulNewSize);
  10018.  
  10019.  
  10020. ΓòÉΓòÉΓòÉ <hidden> WtkSetMmfSize - Parameter hmmf ΓòÉΓòÉΓòÉ
  10021.  
  10022. hmmf (HMMF) - input 
  10023.     Handle to the MMF manager. 
  10024.  
  10025.  
  10026. ΓòÉΓòÉΓòÉ <hidden> WtkSetMmfSize - Parameter pvData ΓòÉΓòÉΓòÉ
  10027.  
  10028. pvData (PVOID) - input 
  10029.     Pointer to the allocated address space to be adjusted in size. 
  10030.  
  10031.  
  10032. ΓòÉΓòÉΓòÉ <hidden> WtkSetMmfSize - Parameter ulNewSize ΓòÉΓòÉΓòÉ
  10033.  
  10034. ulNewSize (ULONG) - input 
  10035.     New size of the memory buffer. 
  10036.  
  10037.     The new size cannot exceed the maximum size that was specified when 
  10038.     allocating the dynamic memory buffer with WtkAllocMmf. 
  10039.  
  10040.  
  10041. ΓòÉΓòÉΓòÉ <hidden> WtkSetMmfSize - Parameters ΓòÉΓòÉΓòÉ
  10042.  
  10043. hmmf (HMMF) - input 
  10044.     Handle to the MMF manager. 
  10045.  
  10046.  pvData (PVOID) - input 
  10047.     Pointer to the allocated address space to be adjusted in size. 
  10048.  
  10049.  ulNewSize (ULONG) - input 
  10050.     New size of the memory buffer. 
  10051.  
  10052.     The new size cannot exceed the maximum size that was specified when 
  10053.     allocating the dynamic memory buffer with WtkAllocMmf. 
  10054.  
  10055.  ulrc (APIRET) - returns 
  10056.     Return Code. 
  10057.  
  10058.     WtkSetMmfSize returns one of the following return codes: 
  10059.  
  10060.     0         NO_ERROR 
  10061.     5         ERROR_INVALID_HANDLE 
  10062.     87        ERROR_INVALID_PARAMETER 
  10063.     111       ERROR_BUFFER_OVERFLOW 
  10064.  
  10065.  
  10066. ΓòÉΓòÉΓòÉ <hidden> WtkSetMmfSize Return Value - ulrc ΓòÉΓòÉΓòÉ
  10067.  
  10068. ulrc (APIRET) - returns 
  10069.     Return Code. 
  10070.  
  10071.     WtkSetMmfSize returns one of the following return codes: 
  10072.  
  10073.     0         NO_ERROR 
  10074.     5         ERROR_INVALID_HANDLE 
  10075.     87        ERROR_INVALID_PARAMETER 
  10076.     111       ERROR_BUFFER_OVERFLOW 
  10077.  
  10078.  
  10079. ΓòÉΓòÉΓòÉ <hidden> WtkSetMmfSize - Remarks ΓòÉΓòÉΓòÉ
  10080.  
  10081. The new size cannot exceed the maximum size that was specified when allocating 
  10082. the dynamic memory buffer with WtkAllocMmf. 
  10083.  
  10084.  
  10085. ΓòÉΓòÉΓòÉ <hidden> WtkSetMmfSize - Related functions ΓòÉΓòÉΓòÉ
  10086.  
  10087. Related Functions 
  10088.  
  10089. none 
  10090.  
  10091.  
  10092. ΓòÉΓòÉΓòÉ 8.85. WtkTerminateMmf ΓòÉΓòÉΓòÉ
  10093.  
  10094. Select an item: 
  10095.  
  10096.      Syntax 
  10097.      Parameters 
  10098.      Returns 
  10099.      Remarks 
  10100.      Related Functions 
  10101.  
  10102.  
  10103. ΓòÉΓòÉΓòÉ <hidden> WtkTerminateMmf - Syntax ΓòÉΓòÉΓòÉ
  10104.  
  10105. This function deinitializes MMF support for the current thread. 
  10106.  
  10107. #define INCL_WTKMMF
  10108. #include <wpstk.h>
  10109.  
  10110. HMMF     hmmf;   /* Handle to the MMF manager.  */
  10111. APIRET   ulrc;   /* Return Code.                */
  10112.  
  10113. ulrc = WtkTerminateMmf( hmmf);
  10114.  
  10115.  
  10116. ΓòÉΓòÉΓòÉ <hidden> WtkTerminateMmf - Parameter hmmf ΓòÉΓòÉΓòÉ
  10117.  
  10118. hmmf (HMMF) - input 
  10119.     Handle to the MMF manager. 
  10120.  
  10121.  
  10122. ΓòÉΓòÉΓòÉ <hidden> WtkTerminateMmf - Parameters ΓòÉΓòÉΓòÉ
  10123.  
  10124. hmmf (HMMF) - input 
  10125.     Handle to the MMF manager. 
  10126.  
  10127.  ulrc (APIRET) - returns 
  10128.     Return Code. 
  10129.  
  10130.     WtkTerminateMmf returns one of the following return codes: 
  10131.  
  10132.     0         NO_ERROR 
  10133.     87        ERROR_INVALID_PARAMETER 
  10134.  
  10135.  
  10136. ΓòÉΓòÉΓòÉ <hidden> WtkTerminateMmf Return Value - ulrc ΓòÉΓòÉΓòÉ
  10137.  
  10138. ulrc (APIRET) - returns 
  10139.     Return Code. 
  10140.  
  10141.     WtkTerminateMmf returns one of the following return codes: 
  10142.  
  10143.     0         NO_ERROR 
  10144.     87        ERROR_INVALID_PARAMETER 
  10145.  
  10146.  
  10147. ΓòÉΓòÉΓòÉ <hidden> WtkTerminateMmf - Remarks ΓòÉΓòÉΓòÉ
  10148.  
  10149. This function deregisters the exception handler for to support memory mapped 
  10150. files. Make sure that you always WtkTerminateMmf before exiting the function 
  10151. that has called WtkInitializeMmf, especially if other exception handler are 
  10152. used beside the one for MMF support. Otherwise unpredictable results (most 
  10153. often simply protection violations may occurr). 
  10154.  
  10155.  
  10156. ΓòÉΓòÉΓòÉ <hidden> WtkTerminateMmf - Related functions ΓòÉΓòÉΓòÉ
  10157.  
  10158. Related Functions 
  10159.  
  10160. none 
  10161.  
  10162.  
  10163. ΓòÉΓòÉΓòÉ 8.86. WtkTimeToCDateTime ΓòÉΓòÉΓòÉ
  10164.  
  10165. Select an item: 
  10166.  
  10167.      Syntax 
  10168.      Parameters 
  10169.      Returns 
  10170.      Remarks 
  10171.      Related Functions 
  10172.  
  10173.  
  10174. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToCDateTime - Syntax ΓòÉΓòÉΓòÉ
  10175.  
  10176. This function either converts a time value used by the compiler runtime to 
  10177. CDATE and CTIME stuctures or fills it with values of current date and time. 
  10178.  
  10179. #define INCL_WTKUTLTIME
  10180. #include <wpstk.h>
  10181.  
  10182. time_t   *ptime;     /* Address of the time value.       */
  10183. PCDATE    pcdate;    /* Address of the CDATE structure.  */
  10184. PCTIME    pctime;    /* Address of the CTIME structure.  */
  10185. BOOL      fResult;   /* Success indicator.               */
  10186.  
  10187. fResult = WtkTimeToCDateTime( ptime, pcdate, pctime);
  10188.  
  10189.  
  10190. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToCDateTime - Parameter ptime ΓòÉΓòÉΓòÉ
  10191.  
  10192. ptime (time_t*) - input 
  10193.     Address of the time value. 
  10194.  
  10195.     In order to use the current time, leave this parameter NULL. 
  10196.  
  10197.  
  10198. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToCDateTime - Parameter pcdate ΓòÉΓòÉΓòÉ
  10199.  
  10200. pcdate (PCDATE) - output 
  10201.     Address of the CDATE structure. 
  10202.  
  10203.     If the setup of a CDATE structure is not required, leave this parameter 
  10204.     NULL. 
  10205.  
  10206.  
  10207. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToCDateTime - Parameter pctime ΓòÉΓòÉΓòÉ
  10208.  
  10209. pctime (PCTIME) - output 
  10210.     Address of the CTIME structure. 
  10211.  
  10212.     If the setup of a CTIME structure is not required, leave this parameter 
  10213.     NULL. 
  10214.  
  10215.  
  10216. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToCDateTime - Parameters ΓòÉΓòÉΓòÉ
  10217.  
  10218. ptime (time_t*) - input 
  10219.     Address of the time value. 
  10220.  
  10221.     In order to use the current time, leave this parameter NULL. 
  10222.  
  10223.  pcdate (PCDATE) - output 
  10224.     Address of the CDATE structure. 
  10225.  
  10226.     If the setup of a CDATE structure is not required, leave this parameter 
  10227.     NULL. 
  10228.  
  10229.  pctime (PCTIME) - output 
  10230.     Address of the CTIME structure. 
  10231.  
  10232.     If the setup of a CTIME structure is not required, leave this parameter 
  10233.     NULL. 
  10234.  
  10235.  fResult (BOOL) - returns 
  10236.     Success indicator. 
  10237.  
  10238.     TRUE 
  10239.               Conversion successful. 
  10240.     FALSE 
  10241.               Conversion not successful or invalid parameters. 
  10242.  
  10243.  
  10244. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToCDateTime Return Value - fResult ΓòÉΓòÉΓòÉ
  10245.  
  10246. fResult (BOOL) - returns 
  10247.     Success indicator. 
  10248.  
  10249.     TRUE 
  10250.               Conversion successful. 
  10251.     FALSE 
  10252.               Conversion not successful or invalid parameters. 
  10253.  
  10254.  
  10255. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToCDateTime - Remarks ΓòÉΓòÉΓòÉ
  10256.  
  10257. This function uses the localtime function and thus modifies the runtime memory 
  10258. being used for reporting the result. 
  10259.  
  10260.  
  10261. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToCDateTime - Related functions ΓòÉΓòÉΓòÉ
  10262.  
  10263. Related Functions 
  10264.  
  10265. none 
  10266.  
  10267.  
  10268. ΓòÉΓòÉΓòÉ 8.87. WtkTimeToDateTime ΓòÉΓòÉΓòÉ
  10269.  
  10270. Select an item: 
  10271.  
  10272.      Syntax 
  10273.      Parameters 
  10274.      Returns 
  10275.      Remarks 
  10276.      Related Functions 
  10277.  
  10278.  
  10279. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToDateTime - Syntax ΓòÉΓòÉΓòÉ
  10280.  
  10281. This function either converts a time value used by the compiler runtime to a 
  10282. DATETIME stucture or fills it with values of current date and time. 
  10283.  
  10284. #define INCL_WTKUTLTIME
  10285. #include <wpstk.h>
  10286.  
  10287. time_t     *ptime;     /* Address of the time value to be converted.    */
  10288. PDATETIME   pdt;       /* Address of the DATETIME structure to set up.  */
  10289. BOOL        fResult;   /* Success indicator.                            */
  10290.  
  10291. fResult = WtkTimeToDateTime( ptime, pdt);
  10292.  
  10293.  
  10294. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToDateTime - Parameter ptime ΓòÉΓòÉΓòÉ
  10295.  
  10296. ptime (time_t*) - input 
  10297.     Address of the time value to be converted. 
  10298.  
  10299.     In order to use the current time, leave this parameter NULL. 
  10300.  
  10301.  
  10302. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToDateTime - Parameter pdt ΓòÉΓòÉΓòÉ
  10303.  
  10304. pdt (PDATETIME) - output 
  10305.     Address of the DATETIME structure to set up. 
  10306.  
  10307.  
  10308. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToDateTime - Parameters ΓòÉΓòÉΓòÉ
  10309.  
  10310. ptime (time_t*) - input 
  10311.     Address of the time value to be converted. 
  10312.  
  10313.     In order to use the current time, leave this parameter NULL. 
  10314.  
  10315.  pdt (PDATETIME) - output 
  10316.     Address of the DATETIME structure to set up. 
  10317.  
  10318.  fResult (BOOL) - returns 
  10319.     Success indicator. 
  10320.  
  10321.     TRUE 
  10322.               Conversion successful. 
  10323.     FALSE 
  10324.               Conversion not successful or invalid parameters. 
  10325.  
  10326.  
  10327. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToDateTime Return Value - fResult ΓòÉΓòÉΓòÉ
  10328.  
  10329. fResult (BOOL) - returns 
  10330.     Success indicator. 
  10331.  
  10332.     TRUE 
  10333.               Conversion successful. 
  10334.     FALSE 
  10335.               Conversion not successful or invalid parameters. 
  10336.  
  10337.  
  10338. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToDateTime - Remarks ΓòÉΓòÉΓòÉ
  10339.  
  10340. When converting a given time value, this function uses the localtime function 
  10341. and thus modifies the runtime memory being used for reporting the result. 
  10342.  
  10343.  
  10344. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToDateTime - Related functions ΓòÉΓòÉΓòÉ
  10345.  
  10346. Related Functions 
  10347.  
  10348. none 
  10349.  
  10350.  
  10351. ΓòÉΓòÉΓòÉ 8.88. WtkTimeToFDateTime ΓòÉΓòÉΓòÉ
  10352.  
  10353. Select an item: 
  10354.  
  10355.      Syntax 
  10356.      Parameters 
  10357.      Returns 
  10358.      Remarks 
  10359.      Related Functions 
  10360.  
  10361.  
  10362. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToFDateTime - Syntax ΓòÉΓòÉΓòÉ
  10363.  
  10364. This function either converts a time value used by the compiler runtime to 
  10365. FDATE and FTIME stuctures or fills it with values of current date and time. 
  10366.  
  10367. #define INCL_WTKUTLTIME
  10368. #include <wpstk.h>
  10369.  
  10370. time_t   *ptime;     /* Address of the time value.       */
  10371. PFDATE    pfdate;    /* Address of the FDATE structure.  */
  10372. PFTIME    pftime;    /* Address of the FTIME structure.  */
  10373. BOOL      fResult;   /* Success indicator.               */
  10374.  
  10375. fResult = WtkTimeToFDateTime( ptime, pfdate, pftime);
  10376.  
  10377.  
  10378. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToFDateTime - Parameter ptime ΓòÉΓòÉΓòÉ
  10379.  
  10380. ptime (time_t*) - input 
  10381.     Address of the time value. 
  10382.  
  10383.     In order to use the current time, leave this parameter NULL. 
  10384.  
  10385.  
  10386. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToFDateTime - Parameter pfdate ΓòÉΓòÉΓòÉ
  10387.  
  10388. pfdate (PFDATE) - output 
  10389.     Address of the FDATE structure. 
  10390.  
  10391.     If the setup of a FDATE structure is not required, leave this parameter 
  10392.     NULL. 
  10393.  
  10394.  
  10395. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToFDateTime - Parameter pftime ΓòÉΓòÉΓòÉ
  10396.  
  10397. pftime (PFTIME) - output 
  10398.     Address of the FTIME structure. 
  10399.  
  10400.     If the setup of a FDATE structure is not required, leave this parameter 
  10401.     NULL. 
  10402.  
  10403.  
  10404. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToFDateTime - Parameters ΓòÉΓòÉΓòÉ
  10405.  
  10406. ptime (time_t*) - input 
  10407.     Address of the time value. 
  10408.  
  10409.     In order to use the current time, leave this parameter NULL. 
  10410.  
  10411.  pfdate (PFDATE) - output 
  10412.     Address of the FDATE structure. 
  10413.  
  10414.     If the setup of a FDATE structure is not required, leave this parameter 
  10415.     NULL. 
  10416.  
  10417.  pftime (PFTIME) - output 
  10418.     Address of the FTIME structure. 
  10419.  
  10420.     If the setup of a FDATE structure is not required, leave this parameter 
  10421.     NULL. 
  10422.  
  10423.  fResult (BOOL) - returns 
  10424.     Success indicator. 
  10425.  
  10426.     TRUE 
  10427.               Conversion successful. 
  10428.     FALSE 
  10429.               Conversion not successful or invalid parameters. 
  10430.  
  10431.  
  10432. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToFDateTime Return Value - fResult ΓòÉΓòÉΓòÉ
  10433.  
  10434. fResult (BOOL) - returns 
  10435.     Success indicator. 
  10436.  
  10437.     TRUE 
  10438.               Conversion successful. 
  10439.     FALSE 
  10440.               Conversion not successful or invalid parameters. 
  10441.  
  10442.  
  10443. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToFDateTime - Remarks ΓòÉΓòÉΓòÉ
  10444.  
  10445. This function uses the localtime function and thus modifies the runtime memory 
  10446. being used for reporting the result. 
  10447.  
  10448.  
  10449. ΓòÉΓòÉΓòÉ <hidden> WtkTimeToFDateTime - Related functions ΓòÉΓòÉΓòÉ
  10450.  
  10451. Related Functions 
  10452.  
  10453. none 
  10454.  
  10455.  
  10456. ΓòÉΓòÉΓòÉ 8.89. WtkUpdateMmf ΓòÉΓòÉΓòÉ
  10457.  
  10458. Select an item: 
  10459.  
  10460.      Syntax 
  10461.      Parameters 
  10462.      Returns 
  10463.      Remarks 
  10464.      Related Functions 
  10465.  
  10466.  
  10467. ΓòÉΓòÉΓòÉ <hidden> WtkUpdateMmf - Syntax ΓòÉΓòÉΓòÉ
  10468.  
  10469. This function updates the file attached to a dynamic memory buffer. 
  10470.  
  10471. #define INCL_WTKMMF
  10472. #include <wpstk.h>
  10473.  
  10474. HMMF     hmmf;     /* Handle to the MMF manager.                           */
  10475. PVOID    pvData;   /* Pointer to the allocated address space to be saved.  */
  10476. APIRET   ulrc;     /* Return Code.                                         */
  10477.  
  10478. ulrc = WtkUpdateMmf( hmmf, pvData);
  10479.  
  10480.  
  10481. ΓòÉΓòÉΓòÉ <hidden> WtkUpdateMmf - Parameter hmmf ΓòÉΓòÉΓòÉ
  10482.  
  10483. hmmf (HMMF) - input 
  10484.     Handle to the MMF manager. 
  10485.  
  10486.  
  10487. ΓòÉΓòÉΓòÉ <hidden> WtkUpdateMmf - Parameter pvData ΓòÉΓòÉΓòÉ
  10488.  
  10489. pvData (PVOID) - input 
  10490.     Pointer to the allocated address space to be saved. 
  10491.  
  10492.  
  10493. ΓòÉΓòÉΓòÉ <hidden> WtkUpdateMmf - Parameters ΓòÉΓòÉΓòÉ
  10494.  
  10495. hmmf (HMMF) - input 
  10496.     Handle to the MMF manager. 
  10497.  
  10498.  pvData (PVOID) - input 
  10499.     Pointer to the allocated address space to be saved. 
  10500.  
  10501.  ulrc (APIRET) - returns 
  10502.     Return Code. 
  10503.  
  10504.     WtkUpdateMmf returns one of the following return codes: 
  10505.  
  10506.     0         NO_ERROR 
  10507.     5         ERROR_ACCESS_DENIED 
  10508.     87        ERROR_INVALID_HANDLE 
  10509.     87        ERROR_INVALID_PARAMETER 
  10510.  
  10511.  
  10512. ΓòÉΓòÉΓòÉ <hidden> WtkUpdateMmf Return Value - ulrc ΓòÉΓòÉΓòÉ
  10513.  
  10514. ulrc (APIRET) - returns 
  10515.     Return Code. 
  10516.  
  10517.     WtkUpdateMmf returns one of the following return codes: 
  10518.  
  10519.     0         NO_ERROR 
  10520.     5         ERROR_ACCESS_DENIED 
  10521.     87        ERROR_INVALID_HANDLE 
  10522.     87        ERROR_INVALID_PARAMETER 
  10523.  
  10524.  
  10525. ΓòÉΓòÉΓòÉ <hidden> WtkUpdateMmf - Remarks ΓòÉΓòÉΓòÉ
  10526.  
  10527. Only truly modified memory pages of the dynamic memory buffer are stored (every 
  10528. memory page of 4KB in size that has been modified since the read from disk) and 
  10529. then marked as updated. 
  10530.  
  10531. Calling WtkUpdateMmf on memory buffers that hold data from a file opened in 
  10532. readonly mode will return ERROR_ACCESS_DENIED. 
  10533.  
  10534.  
  10535. ΓòÉΓòÉΓòÉ <hidden> WtkUpdateMmf - Related functions ΓòÉΓòÉΓòÉ
  10536.  
  10537. Related Functions 
  10538.  
  10539. none 
  10540.  
  10541.  
  10542. ΓòÉΓòÉΓòÉ 8.90. WtkValidateObjectValueTable ΓòÉΓòÉΓòÉ
  10543.  
  10544. Select an item: 
  10545.  
  10546.      Syntax 
  10547.      Parameters 
  10548.      Returns 
  10549.      Remarks 
  10550.      Related Functions 
  10551.  
  10552.  
  10553. ΓòÉΓòÉΓòÉ <hidden> WtkValidateObjectValueTable - Syntax ΓòÉΓòÉΓòÉ
  10554.  
  10555. This function validates values of all active GUI controls registered for values 
  10556. in the objects valuetable and triggers the callback routine for validation and 
  10557. error report. On error, the notebook is switched to the page with the control 
  10558. having invalid content and the focus is set to that control. 
  10559.  
  10560. Note:  It is recommended not to call this function by the code of your WPS 
  10561. class directly, when validation should take place only on closing the settings 
  10562. notebook (see remarks). 
  10563.  
  10564. #define INCL_WTKSETTINGS
  10565. #include <wpstk.h>
  10566.  
  10567. HVALUETABLE   hvt;            /* Valuetable handle.  */
  10568. HWND          hwndNotebook;   /* Notebook handle.    */
  10569. BOOL          fResult;        /* Success indicator.  */
  10570.  
  10571. fResult = WtkValidateObjectValueTable( hvt, hwndNotebook);
  10572.  
  10573.  
  10574. ΓòÉΓòÉΓòÉ <hidden> WtkValidateObjectValueTable - Parameter hvt ΓòÉΓòÉΓòÉ
  10575.  
  10576. hvt (HVALUETABLE) - input 
  10577.     Valuetable handle. 
  10578.  
  10579.  
  10580. ΓòÉΓòÉΓòÉ <hidden> WtkValidateObjectValueTable - Parameter hwndNotebook ΓòÉΓòÉΓòÉ
  10581.  
  10582. hwndNotebook (HWND) - input 
  10583.     Notebook handle. 
  10584.  
  10585.  
  10586. ΓòÉΓòÉΓòÉ <hidden> WtkValidateObjectValueTable - Parameters ΓòÉΓòÉΓòÉ
  10587.  
  10588. hvt (HVALUETABLE) - input 
  10589.     Valuetable handle. 
  10590.  
  10591.  hwndNotebook (HWND) - input 
  10592.     Notebook handle. 
  10593.  
  10594.  fResult (BOOL) - returns 
  10595.     Success indicator. 
  10596.  
  10597.     TRUE 
  10598.               The values of all registered GUI controls are valid. 
  10599.     FALSE 
  10600.               A validation error occurred. 
  10601.  
  10602.  
  10603. ΓòÉΓòÉΓòÉ <hidden> WtkValidateObjectValueTable Return Value - fResult ΓòÉΓòÉΓòÉ
  10604.  
  10605. fResult (BOOL) - returns 
  10606.     Success indicator. 
  10607.  
  10608.     TRUE 
  10609.               The values of all registered GUI controls are valid. 
  10610.     FALSE 
  10611.               A validation error occurred. 
  10612.  
  10613.  
  10614. ΓòÉΓòÉΓòÉ <hidden> WtkValidateObjectValueTable - Remarks ΓòÉΓòÉΓòÉ
  10615.  
  10616. If validation should take place on close of the settings notebook, this 
  10617. function should not be called directly by the code of your WPS class directly. 
  10618.  
  10619. Instead, the notebook frame should be registered with 
  10620. WtkRegisterSettingsNotebook during the processing of _wpAddSettingsPages(). 
  10621. This will let Settings Manager subclass the notebook frame and call 
  10622. WtkValidateObjectValueTable automatically when the notebook is closed. 
  10623.  
  10624. If it is required to validate GUI controls also on other events, 
  10625. WtkValidateObjectValueTable can still be used for that. Note however that it is 
  10626. not possible to validate only for one dialog registered with Settings Manager. 
  10627. Instead, always the registered controls of all registered dialogs are validated 
  10628. - this may result in switching to another notebook page, if there a GUI control 
  10629. contains invalid contents! 
  10630.  
  10631.  
  10632. ΓòÉΓòÉΓòÉ <hidden> WtkValidateObjectValueTable - Related functions ΓòÉΓòÉΓòÉ
  10633.  
  10634. Related Functions 
  10635.  
  10636. none 
  10637.  
  10638.  
  10639. ΓòÉΓòÉΓòÉ 8.91. WtkWriteFile ΓòÉΓòÉΓòÉ
  10640.  
  10641. Select an item: 
  10642.  
  10643.      Syntax 
  10644.      Parameters 
  10645.      Returns 
  10646.      Remarks 
  10647.      Related Functions 
  10648.  
  10649.  
  10650. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile - Syntax ΓòÉΓòÉΓòÉ
  10651.  
  10652. This function writes a data buffer to a file. The file can either be 
  10653. overwritten or the data can be appended to the file. 
  10654.  
  10655. #define INCL_WTKUTLFILE
  10656. #include <wpstk.h>
  10657.  
  10658. PSZ      pszName;     /* Address of the ASCIIZ pathname, which is to be overwritten by the given data.                    */
  10659. PSZ      pszBuffer;   /* The address of a buffer, which is to be written to a file.                                       */
  10660. ULONG    ulBuflen;    /* The length, in bytes, of the buffer described by pszBuffer.                                      */
  10661. BOOL     fAppend;     /* Flag for appending the data to a file rather than overwriting the contents of an existing file.  */
  10662. APIRET   ulrc;        /* Return Code.                                                                                     */
  10663.  
  10664. ulrc = WtkWriteFile( pszName, pszBuffer, ulBuflen, fAppend);
  10665.  
  10666.  
  10667. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile - Parameter pszName ΓòÉΓòÉΓòÉ
  10668.  
  10669. pszName (PSZ) - input 
  10670.     Address of the ASCIIZ pathname, which is to be overwritten by the given 
  10671.     data. 
  10672.  
  10673.     The path name may contain ?: for the drive in order to write the file on 
  10674.     the boot drive. 
  10675.  
  10676.  
  10677. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile - Parameter pszBuffer ΓòÉΓòÉΓòÉ
  10678.  
  10679. pszBuffer (PSZ) - input 
  10680.     The address of a buffer, which is to be written to a file. 
  10681.  
  10682.  
  10683. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile - Parameter ulBuflen ΓòÉΓòÉΓòÉ
  10684.  
  10685. ulBuflen (ULONG) - input 
  10686.     The length, in bytes, of the buffer described by pszBuffer. 
  10687.  
  10688.  
  10689. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile - Parameter fAppend ΓòÉΓòÉΓòÉ
  10690.  
  10691. fAppend (BOOL) - input 
  10692.     Flag for appending the data to a file rather than overwriting the contents 
  10693.     of an existing file. 
  10694.  
  10695.  
  10696. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile - Parameters ΓòÉΓòÉΓòÉ
  10697.  
  10698. pszName (PSZ) - input 
  10699.     Address of the ASCIIZ pathname, which is to be overwritten by the given 
  10700.     data. 
  10701.  
  10702.     The path name may contain ?: for the drive in order to write the file on 
  10703.     the boot drive. 
  10704.  
  10705.  pszBuffer (PSZ) - input 
  10706.     The address of a buffer, which is to be written to a file. 
  10707.  
  10708.  ulBuflen (ULONG) - input 
  10709.     The length, in bytes, of the buffer described by pszBuffer. 
  10710.  
  10711.  fAppend (BOOL) - input 
  10712.     Flag for appending the data to a file rather than overwriting the contents 
  10713.     of an existing file. 
  10714.  
  10715.  ulrc (APIRET) - returns 
  10716.     Return Code. 
  10717.  
  10718.     WtkWriteFile returns one of the following return codes: 
  10719.  
  10720.     0         NO_ERROR 
  10721.     87        ERROR_INVALID_PARAMETER 
  10722.  
  10723.     or return codes of the following functions 
  10724.  
  10725.         DosOpen 
  10726.         DosWrite 
  10727.  
  10728.  
  10729. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile Return Value - ulrc ΓòÉΓòÉΓòÉ
  10730.  
  10731. ulrc (APIRET) - returns 
  10732.     Return Code. 
  10733.  
  10734.     WtkWriteFile returns one of the following return codes: 
  10735.  
  10736.     0         NO_ERROR 
  10737.     87        ERROR_INVALID_PARAMETER 
  10738.  
  10739.     or return codes of the following functions 
  10740.  
  10741.         DosOpen 
  10742.         DosWrite 
  10743.  
  10744.  
  10745. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile - Remarks ΓòÉΓòÉΓòÉ
  10746.  
  10747. This function supports boot drive recognition. Specify ?: for the drive in 
  10748. order to write the file on the boot drive. 
  10749.  
  10750.  
  10751. ΓòÉΓòÉΓòÉ <hidden> WtkWriteFile - Related functions ΓòÉΓòÉΓòÉ
  10752.  
  10753. Related Functions 
  10754.  
  10755. none 
  10756.  
  10757.  
  10758. ΓòÉΓòÉΓòÉ 8.92. WtkWriteObjectValueTable ΓòÉΓòÉΓòÉ
  10759.  
  10760. Select an item: 
  10761.  
  10762.      Syntax 
  10763.      Parameters 
  10764.      Returns 
  10765.      Remarks 
  10766.      Related Functions 
  10767.  
  10768.  
  10769. ΓòÉΓòÉΓòÉ <hidden> WtkWriteObjectValueTable - Syntax ΓòÉΓòÉΓòÉ
  10770.  
  10771. This function reads the GUI controls of the given settings notebookpage and 
  10772. updates the corresponding values in the object valuetable. 
  10773.  
  10774. #define INCL_WTKSETTINGS
  10775. #include <wpstk.h>
  10776.  
  10777. HVALUETABLE   hvt;          /* Valuetable handle.                            */
  10778. HWND          hwndDialog;   /* Dialog handle of the settings notebook page.  */
  10779. BOOL          fResult;      /* Success indicator.                            */
  10780.  
  10781. fResult = WtkWriteObjectValueTable( hvt, hwndDialog);
  10782.  
  10783.  
  10784. ΓòÉΓòÉΓòÉ <hidden> WtkWriteObjectValueTable - Parameter hvt ΓòÉΓòÉΓòÉ
  10785.  
  10786. hvt (HVALUETABLE) - input 
  10787.     Valuetable handle. 
  10788.  
  10789.  
  10790. ΓòÉΓòÉΓòÉ <hidden> WtkWriteObjectValueTable - Parameter hwndDialog ΓòÉΓòÉΓòÉ
  10791.  
  10792. hwndDialog (HWND) - input 
  10793.     Dialog handle of the settings notebook page. 
  10794.  
  10795.  
  10796. ΓòÉΓòÉΓòÉ <hidden> WtkWriteObjectValueTable - Parameters ΓòÉΓòÉΓòÉ
  10797.  
  10798. hvt (HVALUETABLE) - input 
  10799.     Valuetable handle. 
  10800.  
  10801.  hwndDialog (HWND) - input 
  10802.     Dialog handle of the settings notebook page. 
  10803.  
  10804.  fResult (BOOL) - returns 
  10805.     Success indicator. 
  10806.  
  10807.     TRUE 
  10808.               Values could be transferred to the object valuetable. 
  10809.     FALSE 
  10810.               An error occurred. 
  10811.  
  10812.  
  10813. ΓòÉΓòÉΓòÉ <hidden> WtkWriteObjectValueTable Return Value - fResult ΓòÉΓòÉΓòÉ
  10814.  
  10815. fResult (BOOL) - returns 
  10816.     Success indicator. 
  10817.  
  10818.     TRUE 
  10819.               Values could be transferred to the object valuetable. 
  10820.     FALSE 
  10821.               An error occurred. 
  10822.  
  10823.  
  10824. ΓòÉΓòÉΓòÉ <hidden> WtkWriteObjectValueTable - Remarks ΓòÉΓòÉΓòÉ
  10825.  
  10826. This function is to be called in the WM_DESTROY message handling of the window 
  10827. procedure being used for the settings notebookpages, so that the values of the 
  10828. GUI controls are written to the object valuetable, when the notebook is closed. 
  10829.  
  10830.  
  10831. ΓòÉΓòÉΓòÉ <hidden> WtkWriteObjectValueTable - Related functions ΓòÉΓòÉΓòÉ
  10832.  
  10833. Related Functions 
  10834.  
  10835. none 
  10836.  
  10837.  
  10838. ΓòÉΓòÉΓòÉ 8.93. WtkWriteStringEa ΓòÉΓòÉΓòÉ
  10839.  
  10840. Select an item: 
  10841.  
  10842.      Syntax 
  10843.      Parameters 
  10844.      Returns 
  10845.      Remarks 
  10846.      Related Functions 
  10847.  
  10848.  
  10849. ΓòÉΓòÉΓòÉ <hidden> WtkWriteStringEa - Syntax ΓòÉΓòÉΓòÉ
  10850.  
  10851. This function attaches a string extended attribute to a file or directory. 
  10852.  
  10853. #define INCL_WTKEAS
  10854. #include <wpstk.h>
  10855.  
  10856. PSZ      pszName;      /* Address of the ASCIIZ path name of the file or directory.  */
  10857. PSZ      pszEaName;    /* Address of the ASCIIZ name of the extended attribute.      */
  10858. PSZ      pszEaValue;   /* The address of a string to be written.                     */
  10859. APIRET   ulrc;         /* Return Code.                                               */
  10860.  
  10861. ulrc = WtkWriteStringEa( pszName, pszEaName, pszEaValue);
  10862.  
  10863.  
  10864. ΓòÉΓòÉΓòÉ <hidden> WtkWriteStringEa - Parameter pszName ΓòÉΓòÉΓòÉ
  10865.  
  10866. pszName (PSZ) - input 
  10867.     Address of the ASCIIZ path name of the file or directory. 
  10868.  
  10869.     The path name may contain ?: for the drive in order to search the file or 
  10870.     directory on the boot drive. 
  10871.  
  10872.     The name may not include wildcards. 
  10873.  
  10874.  
  10875. ΓòÉΓòÉΓòÉ <hidden> WtkWriteStringEa - Parameter pszEaName ΓòÉΓòÉΓòÉ
  10876.  
  10877. pszEaName (PSZ) - input 
  10878.     Address of the ASCIIZ name of the extended attribute. 
  10879.  
  10880.  
  10881. ΓòÉΓòÉΓòÉ <hidden> WtkWriteStringEa - Parameter pszEaValue ΓòÉΓòÉΓòÉ
  10882.  
  10883. pszEaValue (PSZ) - input 
  10884.     The address of a string to be written. 
  10885.  
  10886.  
  10887. ΓòÉΓòÉΓòÉ <hidden> WtkWriteStringEa - Parameters ΓòÉΓòÉΓòÉ
  10888.  
  10889. pszName (PSZ) - input 
  10890.     Address of the ASCIIZ path name of the file or directory. 
  10891.  
  10892.     The path name may contain ?: for the drive in order to search the file or 
  10893.     directory on the boot drive. 
  10894.  
  10895.     The name may not include wildcards. 
  10896.  
  10897.  pszEaName (PSZ) - input 
  10898.     Address of the ASCIIZ name of the extended attribute. 
  10899.  
  10900.  pszEaValue (PSZ) - input 
  10901.     The address of a string to be written. 
  10902.  
  10903.  ulrc (APIRET) - returns 
  10904.     Return Code. 
  10905.  
  10906.     WtkWriteStringEa returns one of the following return codes: 
  10907.  
  10908.     0         NO_ERROR 
  10909.     6         ERROR_INVALID_HANDLE 
  10910.     8         ERROR_NOT_ENOUGH_MEMORY 
  10911.     13        ERROR_INVALID_DATA 
  10912.     87        ERROR_INVALID_PARAMETER 
  10913.  
  10914.     or return codes of the following functions 
  10915.  
  10916.         DosSetPathInfo 
  10917.  
  10918.  
  10919. ΓòÉΓòÉΓòÉ <hidden> WtkWriteStringEa Return Value - ulrc ΓòÉΓòÉΓòÉ
  10920.  
  10921. ulrc (APIRET) - returns 
  10922.     Return Code. 
  10923.  
  10924.     WtkWriteStringEa returns one of the following return codes: 
  10925.  
  10926.     0         NO_ERROR 
  10927.     6         ERROR_INVALID_HANDLE 
  10928.     8         ERROR_NOT_ENOUGH_MEMORY 
  10929.     13        ERROR_INVALID_DATA 
  10930.     87        ERROR_INVALID_PARAMETER 
  10931.  
  10932.     or return codes of the following functions 
  10933.  
  10934.         DosSetPathInfo 
  10935.  
  10936.  
  10937. ΓòÉΓòÉΓòÉ <hidden> WtkWriteStringEa - Remarks ΓòÉΓòÉΓòÉ
  10938.  
  10939. This function supports boot drive recognition. Specify ?: for the drive in 
  10940. order to open the file or directory on the boot drive. 
  10941.  
  10942. This function is meant to provide you with easy handling of string extended 
  10943. attributes. The drawback is that for simplicity you cannot 
  10944.  
  10945.      attach more than one string to the specified extended attribute (but that 
  10946.       is what is needed for most cases anyway) 
  10947.      write through (ommit the cache) 
  10948.      mark the extended attribute as critical 
  10949.  
  10950.  If these limitations does not meet your requirements, use the move flexible 
  10951.  call WtkPutEaValue instead. 
  10952.  
  10953.  
  10954. ΓòÉΓòÉΓòÉ <hidden> WtkWriteStringEa - Related functions ΓòÉΓòÉΓòÉ
  10955.  
  10956. Related Functions 
  10957.  
  10958. none 
  10959.  
  10960.  
  10961. ΓòÉΓòÉΓòÉ 9. Data Types ΓòÉΓòÉΓòÉ
  10962.  
  10963. The following are all the data types used by the Workplace Shell Toolkit. 
  10964.  
  10965. Data types of the WPS Toolkit 
  10966.  
  10967.      CBINITCONTROL 
  10968.      CBQUERYINDEX 
  10969.      CBQUERYSTRING 
  10970.      CBQUERYTARGETBUF 
  10971.      CBQUERYVALUE 
  10972.      CBQUERYVALUEINFO 
  10973.      CBREPORTCHANGED 
  10974.      CBREPORTDESTROYED 
  10975.      CBREPORTERROR 
  10976.      CBREPORTINIT 
  10977.      CBREPORTSAVED 
  10978.      CBVALIDATE 
  10979.      FNCB 
  10980.      HEA 
  10981.      HMMF 
  10982.      HSETTINGTABLE 
  10983.      HVALUETABLE 
  10984.  
  10985.  Data types from the Toolkit for OS/2 WARP or compiler runtime 
  10986.  
  10987.      APIRET 
  10988.      BOOL 
  10989.      BYTE 
  10990.      CDATE 
  10991.      CHAR 
  10992.      CTIME 
  10993.      DATETIME 
  10994.      FDATE 
  10995.      FILESTATUS3 
  10996.      FTIME 
  10997.      HDIR 
  10998.      HFILE 
  10999.      HMODULE 
  11000.      HWND 
  11001.      LONG 
  11002.      MPARAM 
  11003.      MRESULT 
  11004.      PFN 
  11005.      PFNWP 
  11006.      PSZ 
  11007.      PVOID 
  11008.      SHORT 
  11009.      UCHAR 
  11010.      ULONG 
  11011.      USHORT 
  11012.      VOID 
  11013.      time_t 
  11014.  
  11015.  
  11016. ΓòÉΓòÉΓòÉ 9.1. APIRET ΓòÉΓòÉΓòÉ
  11017.  
  11018. Unsigned integer in the range 0 through 4 294 967 295. 
  11019.  
  11020. typedef unsigned long APIRET;
  11021.  
  11022. This data type is being introduced by the OS/2 Warp Toolkit. 
  11023.  
  11024.  
  11025. ΓòÉΓòÉΓòÉ 9.2. BOOL ΓòÉΓòÉΓòÉ
  11026.  
  11027. Boolean. 
  11028.  
  11029. Valid values are: 
  11030.  
  11031.      FALSE, which is 0 
  11032.      TRUE, which is 1 
  11033.  
  11034.   typedef unsigned long BOOL;
  11035.  
  11036.  This data type is being introduced by the OS/2 Warp Toolkit. 
  11037.  
  11038.  
  11039. ΓòÉΓòÉΓòÉ 9.3. BYTE ΓòÉΓòÉΓòÉ
  11040.  
  11041. A byte. 
  11042.  
  11043. typedef unsigned char BYTE;
  11044.  
  11045.  
  11046. ΓòÉΓòÉΓòÉ 9.4. CBINITCONTROL ΓòÉΓòÉΓòÉ
  11047.  
  11048. Structure for callback request to initialize a GUI control of a settings 
  11049. notebookpage. 
  11050.  
  11051. typedef struct _CBINITCONTROL {
  11052.   USHORT         usDialogid;                /* out - id of dialog                      */
  11053.   USHORT         usControlid;               /* out - id of control                     */
  11054.   HWND           hwndDialog;                /* out - handle of dialog                  */
  11055.   HWND           hwndControl;               /* out - handle of control                 */
  11056. } CBINITCONTROL, *PCBINITCONTROL;
  11057.  
  11058.  
  11059. ΓòÉΓòÉΓòÉ 9.5. CBQUERYINDEX ΓòÉΓòÉΓòÉ
  11060.  
  11061. Structure for callback request to translate strings to array indicees for a 
  11062. (sub)value of a setting. 
  11063.  
  11064. typedef struct _CBQUERYINDEX {
  11065.   PVOID          pvObjectInstance;          /* out - somSelf of object instance        */
  11066.   ULONG          ulSettingId;               /* out - id of setting                     */
  11067.   PSZ            pszName;                   /* out - name of setting                   */
  11068.   PSZ            pszValue;                  /* out - string value to be translated     */
  11069.   ULONG          ulValueIndex;              /* out - index of subvalue                 */
  11070.   ULONG          ulStringIndex;             /*  in - index to be used                  */
  11071. } CBQUERYINDEX, *PCBQUERYINDEX;             /* return TRUE if processed, else FALSE    */
  11072.  
  11073.  
  11074. ΓòÉΓòÉΓòÉ 9.6. CBQUERYSTRING ΓòÉΓòÉΓòÉ
  11075.  
  11076. Structure for callback request to translate array indicees to strings for a 
  11077. (sub)value of a setting. 
  11078.  
  11079. typedef struct _CBQUERYSTRING {
  11080.   PVOID          pvObjectInstance;          /* out - somSelf of object instance        */
  11081.   ULONG          ulSettingId;               /* out - id of setting                     */
  11082.   PSZ            pszName;                   /* out - name of setting                   */
  11083.   ULONG          ulStringIndex;             /* out - index to be translated            */
  11084.   ULONG          ulValueIndex;              /* out - index of subvalue                 */
  11085.   CHAR           szValue[ _STM_MAX_SETTINGSVALUE];/* in - string value to be used      */
  11086. } CBQUERYSTRING, *PCBQUERYSTRING;           /* return TRUE if processed, else FALSE    */
  11087.  
  11088.  
  11089. ΓòÉΓòÉΓòÉ 9.7. CBQUERYTARGETBUF ΓòÉΓòÉΓòÉ
  11090.  
  11091. Structure for callback request to query a target buffer for a (sub)value of a 
  11092. setting. 
  11093.  
  11094. typedef struct _CBQUERYTARGETBUF {
  11095.   PVOID          pvObjectInstance;          /* out - somSelf of object instance        */
  11096.   PSZ            pszName;                   /* out - name of setting                   */
  11097.   ULONG          ulSettingId;               /* out - id of setting                     */
  11098.   ULONG          ulValueIndex;              /* out - index of subvalue                 */
  11099.                                             /*    (only > 0 for multivalue settings)   */
  11100.   ULONG          ulBufMax;                  /* #in - len of target buffer              */
  11101.   PVOID          pvTarget;                  /* #in - target buffer                     */
  11102. } CBQUERYTARGETBUF, *PCBQUERYTARGETBUF;     /*  return TRUE to use the returned data   */
  11103.  
  11104.  
  11105. ΓòÉΓòÉΓòÉ 9.8. CBQUERYVALUE ΓòÉΓòÉΓòÉ
  11106.  
  11107. Structure for callback request to let the WPS class update the target buffer(s) 
  11108. for a given setting, before it is read for determining the current settings. 
  11109.  
  11110. typedef struct _CBQUERYVALUE {
  11111.   PVOID          pvObjectInstance;          /* out - somSelf of object instance        */
  11112.   ULONG          ulSettingId;               /* out - id of setting                     */
  11113.   PSZ            pszName;                   /* out - name of setting                   */
  11114.   ULONG          ulQueryIndex;              /* out - index of query                    */
  11115. } CBQUERYVALUE, *PCBQUERYVALUE;
  11116.  
  11117.  
  11118. ΓòÉΓòÉΓòÉ 9.9. CBQUERYVALUEINFO ΓòÉΓòÉΓòÉ
  11119.  
  11120. Structure for callback request to query infos about a given (sub)value of a 
  11121. setting. 
  11122.  
  11123. typedef struct _CBQUERYVALUEINFO {
  11124.   PSZ            pszName;                   /* out - name of setting                   */
  11125.   ULONG          ulSettingId;               /* out - id of setting                     */
  11126.   ULONG          ulValueIndex;              /* out - index of subvalue                 */
  11127.   ULONG          ulValueType;               /* #in - type of value - see VALUETYPE_*   */
  11128.   USHORT         usDialogid;                /*  in - id of dialog containing control   */
  11129.   USHORT         usControlid;               /*  in - id of control                     */
  11130.   PFNWP          pfnwpSubclass;             /*  in - subclass window proc for control  */
  11131.   PSZ            pszDetailsTitle;           /*  in - title of folderdetails view       */
  11132. } CBQUERYVALUEINFO, *PCBQUERYVALUEINFO;
  11133.  
  11134.  
  11135. ΓòÉΓòÉΓòÉ 9.10. CBREPORTCHANGED ΓòÉΓòÉΓòÉ
  11136.  
  11137. Structure for callback request to inform the WPS class that a given setting has 
  11138. changed. 
  11139.  
  11140. typedef struct _CBREPORTCHANGED {
  11141.   PVOID          pvObjectInstance;          /* out - somSelf of object instance        */
  11142.   ULONG          ulSettingId;               /* out - id of setting                     */
  11143.   PSZ            pszName;                   /* out - name of setting                   */
  11144. } CBREPORTCHANGED, *PCBREPORTCHANGED;
  11145.  
  11146.  
  11147. ΓòÉΓòÉΓòÉ 9.11. CBREPORTDESTROYED ΓòÉΓòÉΓòÉ
  11148.  
  11149. Structure for callback request to inform the WPS class that the settingstable 
  11150. has been destroyed. 
  11151.  
  11152. typedef struct _CBREPORTDESTROYED {
  11153.   BOOL           fDestroyed;                /*  no data really required here yet       */
  11154. } CBREPORTDESTROYED, *PCBREPORTDESTROYED;
  11155.  
  11156.  
  11157. ΓòÉΓòÉΓòÉ 9.12. CBREPORTERROR ΓòÉΓòÉΓòÉ
  11158.  
  11159. Structure for callback request to inform the WPS class that a given control of 
  11160. a settings notebookpage has failed the validation. 
  11161.  
  11162. typedef struct _CBREPORTERROR {
  11163.   PVOID          pvObjectInstance;          /* out - somSelf of object instance        */
  11164.   ULONG          ulSettingId;               /* out - id of setting                     */
  11165.   PSZ            pszName;                   /* out - name of setting                   */
  11166.   USHORT         usDialogid;                /* out - id of dialog                      */
  11167.   USHORT         usControlid;               /* out - id of control                     */
  11168.   HWND           hwndDialog;                /* out - handle of dialog                  */
  11169.   HWND           hwndControl;               /* out - handle of control                 */
  11170. } CBREPORTERROR, *PCBREPORTERROR;           /* return TRUE to ignore error             */
  11171.  
  11172.  
  11173. ΓòÉΓòÉΓòÉ 9.13. CBREPORTINIT ΓòÉΓòÉΓòÉ
  11174.  
  11175. Structure for callback request to inform the WPS class that the settings table 
  11176. has been initialized. 
  11177.  
  11178. typedef struct _CBREPORTINIT {
  11179.   BOOL           fInitialized;              /*  no data really required here yet       */
  11180. } CBREPORTINIT, *PCBREPORTINIT;
  11181.  
  11182.  
  11183. ΓòÉΓòÉΓòÉ 9.14. CBREPORTSAVED ΓòÉΓòÉΓòÉ
  11184.  
  11185. Structure for callback request to inform the WPS class that the settings have 
  11186. been saved. 
  11187.  
  11188. typedef struct _CBREPORTSAVED {
  11189.   BOOL           fSaved;                    /*  no data really required here yet       */
  11190. } CBREPORTSAVED, *PCBREPORTSAVED;
  11191.  
  11192.  
  11193. ΓòÉΓòÉΓòÉ 9.15. CBVALIDATE ΓòÉΓòÉΓòÉ
  11194.  
  11195. Structure for callback request to let the WPS class validate a settings 
  11196. (sub)value. 
  11197.  
  11198. typedef struct _CBVALIDATE {
  11199.   PVOID          pvObjectInstance;          /* out - somSelf of object instance        */
  11200.   ULONG          ulSettingId;               /* out - id of setting                     */
  11201.   PSZ            pszName;                   /* out - name of setting                   */
  11202.   PSZ            pszValue;                  /* out - name of value to be validated     */
  11203.   ULONG          ulValueIndex;              /* out - index of subvalue                 */
  11204.   BOOL           fResult;                   /*  in - result of validation              */
  11205. } CBVALIDATE, *PCBVALIDATE;                 /* return TRUE if your callback validates, */
  11206.  
  11207.  
  11208. ΓòÉΓòÉΓòÉ 9.16. CDATE ΓòÉΓòÉΓòÉ
  11209.  
  11210. Structure that contains date information for a data element in the details view 
  11211. of a container control. 
  11212.  
  11213. typedef struct _CDATE {
  11214.   UCHAR      day;    /*  Current day. */
  11215.   UCHAR      month;  /*  Current month. */
  11216.   USHORT     year;   /*  Current year. */
  11217. } CDATE;
  11218.  
  11219. typedef CDATE *PCDATE;
  11220.  
  11221. This data type is being introduced by the OS/2 Warp Toolkit. 
  11222.  
  11223.  
  11224. ΓòÉΓòÉΓòÉ 9.17. CHAR ΓòÉΓòÉΓòÉ
  11225.  
  11226. Single-byte character. 
  11227.  
  11228. #define CHAR char
  11229.  
  11230.  
  11231. ΓòÉΓòÉΓòÉ 9.18. CTIME ΓòÉΓòÉΓòÉ
  11232.  
  11233. Structure that contains time information for a data element in the details view 
  11234. of a container control. 
  11235.  
  11236. typedef struct _CTIME {
  11237.   UCHAR     hours;       /*  Current hour. */
  11238.   UCHAR     minutes;     /*  Current minute. */
  11239.   UCHAR     seconds;     /*  Current second. */
  11240.   UCHAR     ucReserved;  /*  Reserved. */
  11241. } CTIME;
  11242.  
  11243. typedef CTIME *PCTIME;
  11244.  
  11245. This data type is being introduced by the OS/2 Warp Toolkit. 
  11246.  
  11247.  
  11248. ΓòÉΓòÉΓòÉ 9.19. DATETIME ΓòÉΓòÉΓòÉ
  11249.  
  11250. Date and time data structure. 
  11251.  
  11252. typedef struct _DATETIME {
  11253.   UCHAR      hours;       /*  Current hour, using values 0 through 23. */
  11254.   UCHAR      minutes;     /*  Current minute, using values 0 through 59. */
  11255.   UCHAR      seconds;     /*  Current second, using values 0 through 59. */
  11256.   UCHAR      hundredths;  /*  Current hundredths of a second, using values 0 through 99. */
  11257.   UCHAR      day;         /*  Current day of the month, using values 1 through 31. */
  11258.   UCHAR      month;       /*  Current month of the year, using values 1 through 12. */
  11259.   USHORT     year;        /*  Current year. */
  11260.   SHORT      timezone;    /*  The difference in minutes between the current time zone and Greenwich Mean Time (GMT). */
  11261.   UCHAR      weekday;     /*  Current day of the week, using values 0 through 6. */
  11262. } DATETIME;
  11263.  
  11264. typedef DATETIME *PDATETIME;
  11265.  
  11266. This data type is being introduced by the OS/2 Warp Toolkit. 
  11267.  
  11268.  
  11269. ΓòÉΓòÉΓòÉ 9.20. FDATE ΓòÉΓòÉΓòÉ
  11270.  
  11271. Date data structure for file-system functions. 
  11272.  
  11273. typedef struct _FDATE {
  11274.   USHORT     day:5;    /*  Binary day for directory entry. */
  11275.   USHORT     month:4;  /*  Binary month for directory entry. */
  11276.   USHORT     year:7;   /*  The number of years since 1980 for this directory entry. */
  11277. } FDATE;
  11278.  
  11279. typedef FDATE *PFDATE;
  11280.  
  11281. This data type is being introduced by the OS/2 Warp Toolkit. 
  11282.  
  11283.  
  11284. ΓòÉΓòÉΓòÉ 9.21. FILESTATUS3 ΓòÉΓòÉΓòÉ
  11285.  
  11286. Level 1 (32-bit) (FIL_STANDARD) information. 
  11287.  
  11288.  typedef struct _FILESTATUS3 {
  11289.    FDATE     fdateCreation;    /*  Date of file creation. */
  11290.    FTIME     ftimeCreation;    /*  Time of file creation. */
  11291.    FDATE     fdateLastAccess;  /*  Date of last access. */
  11292.    FTIME     ftimeLastAccess;  /*  Time of last access. */
  11293.    FDATE     fdateLastWrite;   /*  Date of last write. */
  11294.    FTIME     ftimeLastWrite;   /*  Time of last write. */
  11295.    ULONG     cbFile;           /*  File size (end of data). */
  11296.    ULONG     cbFileAlloc;      /*  File allocated size. */
  11297.    ULONG     attrFile;         /*  Attributes of the file. */
  11298.  } FILESTATUS3;
  11299.  
  11300.  typedef FILESTATUS3 *PFILESTATUS3;
  11301.  
  11302. This data type is being introduced by the OS/2 Warp Toolkit. 
  11303.  
  11304.  
  11305. ΓòÉΓòÉΓòÉ 9.22. FNCB ΓòÉΓòÉΓòÉ
  11306.  
  11307. Pointer to a callback procedure for the Settings Manager. 
  11308.  
  11309. typedef BOOL (FNCB)(ULONG ulAction, PVOID pvData, PVOID pvObjectInstance, PVOID pvObjectData);
  11310.  
  11311. typedef FNCB *PFNCB;
  11312.  
  11313.  
  11314. ΓòÉΓòÉΓòÉ 9.23. FTIME ΓòÉΓòÉΓòÉ
  11315.  
  11316. Time data structure for file-system functions. 
  11317.  
  11318. typedef struct _FTIME {
  11319.   USHORT     twosecs:5;  /*  Binary number of two-second increments. */
  11320.   USHORT     minutes:6;  /*  Binary number of minutes. */
  11321.   USHORT     hours:5;    /*  Binary number of hours. */
  11322. } FTIME;
  11323.  
  11324. typedef FTIME *PFTIME;
  11325.  
  11326. This data type is being introduced by the OS/2 Warp Toolkit. 
  11327.  
  11328.  
  11329. ΓòÉΓòÉΓòÉ 9.24. HDIR ΓòÉΓòÉΓòÉ
  11330.  
  11331. Value (32-bit) used as a directory handle. 
  11332.  
  11333. typedef LHANDLE HDIR;
  11334.  
  11335. This data type is being introduced by the OS/2 Warp Toolkit. 
  11336.  
  11337.  
  11338. ΓòÉΓòÉΓòÉ 9.25. HEA ΓòÉΓòÉΓòÉ
  11339.  
  11340. Extended attibute handle. 
  11341.  
  11342. typedef LHANDLE HEA;
  11343.  
  11344.  
  11345. ΓòÉΓòÉΓòÉ 9.26. HFILE ΓòÉΓòÉΓòÉ
  11346.  
  11347. File handle. 
  11348.  
  11349.  typedef LHANDLE HFILE;
  11350.  
  11351. This data type is being introduced by the OS/2 Warp Toolkit. 
  11352.  
  11353.  
  11354. ΓòÉΓòÉΓòÉ 9.27. HMMF ΓòÉΓòÉΓòÉ
  11355.  
  11356. Memory mapped file handle 
  11357.  
  11358. typedef LHANDLE HMMF;
  11359.  
  11360.  
  11361. ΓòÉΓòÉΓòÉ 9.28. HMODULE ΓòÉΓòÉΓòÉ
  11362.  
  11363. Module handle. 
  11364.  
  11365. typedef LHANDLE HMODULE;
  11366.  
  11367. This data type is being introduced by the OS/2 Warp Toolkit. 
  11368.  
  11369.  
  11370. ΓòÉΓòÉΓòÉ 9.29. HSETTINGTABLE ΓòÉΓòÉΓòÉ
  11371.  
  11372. Settingstable handle. 
  11373.  
  11374. typedef LHANDLE HSETTINGTABLE;
  11375.  
  11376.  
  11377. ΓòÉΓòÉΓòÉ 9.30. HVALUETABLE ΓòÉΓòÉΓòÉ
  11378.  
  11379. Valuetable handle. 
  11380.  
  11381. typedef LHANDLE HVALUETABLE;
  11382.  
  11383.  
  11384. ΓòÉΓòÉΓòÉ 9.31. HWND ΓòÉΓòÉΓòÉ
  11385.  
  11386. Window handle. 
  11387.  
  11388. typedef LHANDLE HWND;
  11389.  
  11390. This data type is being introduced by the OS/2 Warp Toolkit. 
  11391.  
  11392.  
  11393. ΓòÉΓòÉΓòÉ 9.32. LONG ΓòÉΓòÉΓòÉ
  11394.  
  11395. Signed integer in the range -2 147 483 648 through 2 147 483 647. 
  11396.  
  11397. #define LONG long
  11398.  
  11399. This data type is being introduced by the OS/2 Warp Toolkit. 
  11400.  
  11401.  
  11402. ΓòÉΓòÉΓòÉ 9.33. MPARAM ΓòÉΓòÉΓòÉ
  11403.  
  11404. A 4-byte message-dependent parameter structure. 
  11405.  
  11406. typedef VOID *MPARAM;
  11407.  
  11408. Certain elements of information, placed into the parameters of a message, have 
  11409. data types that do not use all four bytes of this data type. The rules 
  11410. governing these cases are: 
  11411.  
  11412.  BOOL      The value is contained in the low word and the high word is 0. 
  11413.  SHORT     The value is contained in the low word and its sign is extended into 
  11414.            the high word. 
  11415.  USHORT    The value is contained in the low word and the high word is 0. 
  11416.  NULL      The entire four bytes are 0. 
  11417.  
  11418.  The structure of this data type depends on the message. For details, see the 
  11419.  description of the particular message. 
  11420.  
  11421.  This data type is being introduced by the OS/2 Warp Toolkit. 
  11422.  
  11423.  
  11424. ΓòÉΓòÉΓòÉ 9.34. MRESULT ΓòÉΓòÉΓòÉ
  11425.  
  11426. A 4-byte message-dependent reply parameter structure. 
  11427.  
  11428. typedef VOID *MRESULT;
  11429.  
  11430. Certain elements of information, placed into the parameters of a message, have 
  11431. data types that do not use all four bytes of this data type. The rules 
  11432. governing these cases are: 
  11433.  
  11434.  BOOL      The value is contained in the low word and the high word is 0. 
  11435.  SHORT     The value is contained in the low word and its sign is extended into 
  11436.            the high word. 
  11437.  USHORT    The value is contained in the low word and the high word is 0. 
  11438.  NULL      The entire four bytes are 0. 
  11439.  
  11440.  The structure of this data type depends on the message. For details, see the 
  11441.  description of the particular message. 
  11442.  
  11443.  This data type is being introduced by the OS/2 Warp Toolkit. 
  11444.  
  11445.  
  11446. ΓòÉΓòÉΓòÉ 9.35. PFN ΓòÉΓòÉΓòÉ
  11447.  
  11448. Pointer to a procedure. 
  11449.  
  11450. typedef _PFN *PFN;
  11451.  
  11452. In the OS/2 toolkit header file, this is a two-part definition as shown below: 
  11453.  
  11454. typedef  int   (APIENTRY _PFN) ();
  11455. typedef  _PFN  *PFN;
  11456.  
  11457. This data type is being introduced by the OS/2 Warp Toolkit. 
  11458.  
  11459.  
  11460. ΓòÉΓòÉΓòÉ 9.36. PFNWP ΓòÉΓòÉΓòÉ
  11461.  
  11462. Pointer to a window procedure. 
  11463.  
  11464. This is the standard function definition for window procedures. 
  11465.  
  11466. typedef FNWP *PFNWP;
  11467.  
  11468. The first argument (HWND) is the handle of the window receiving the message. 
  11469. The second argument (ULONG) is a message identifier. 
  11470. The third argument (MPARAM) is the first message parameter (mp1). 
  11471. The fourth argument (MPARAM) is the second message parameter (mp2). 
  11472. The function returns an MRESULT. Each message has a specific set of possible 
  11473. return codes. The window procedure must return a value that is appropriate for 
  11474. the message being processed.  In the header file, this is a two-part definition 
  11475. as shown below: 
  11476.  
  11477. typedef MRESULT (EXPENTRY FNWP)(HWND, ULONG, MPARAM, MPARAM);
  11478. typedef FNWP *PFNWP;
  11479.  
  11480. This data type is being introduced by the OS/2 Warp Toolkit. 
  11481.  
  11482.  
  11483. ΓòÉΓòÉΓòÉ 9.37. PSZ ΓòÉΓòÉΓòÉ
  11484.  
  11485. Pointer to a null-terminated string. 
  11486.  
  11487. If you are using C++ **, you may need to use PCSZ. 
  11488.  
  11489. typedef unsigned char *PSZ;
  11490.  
  11491. This data type is being introduced by the OS/2 Warp Toolkit. 
  11492.  
  11493.  
  11494. ΓòÉΓòÉΓòÉ 9.38. PVOID ΓòÉΓòÉΓòÉ
  11495.  
  11496. Pointer to a data type of undefined format. 
  11497.  
  11498. typedef VOID *PVOID;
  11499.  
  11500. This data type is being introduced by the OS/2 Warp Toolkit. 
  11501.  
  11502.  
  11503. ΓòÉΓòÉΓòÉ 9.39. SHORT ΓòÉΓòÉΓòÉ
  11504.  
  11505. Signed integer in the range -32 768 through 32 767. 
  11506.  
  11507. #define SHORT short
  11508.  
  11509. This data type is being introduced by the OS/2 Warp Toolkit. 
  11510.  
  11511.  
  11512. ΓòÉΓòÉΓòÉ 9.40. UCHAR ΓòÉΓòÉΓòÉ
  11513.  
  11514. Single-byte unsigned character or unsigned integer in the range 0 through 255. 
  11515.  
  11516. typedef unsigned char UCHAR;
  11517.  
  11518. This data type is being introduced by the OS/2 Warp Toolkit. 
  11519.  
  11520.  
  11521. ΓòÉΓòÉΓòÉ 9.41. ULONG ΓòÉΓòÉΓòÉ
  11522.  
  11523. 32-bit unsigned integer in the range 0 through 4 294 967 295. 
  11524.  
  11525. typedef unsigned long ULONG;
  11526.  
  11527. This data type is being introduced by the OS/2 Warp Toolkit. 
  11528.  
  11529.  
  11530. ΓòÉΓòÉΓòÉ 9.42. USHORT ΓòÉΓòÉΓòÉ
  11531.  
  11532. Unsigned integer in the range 0 through 65 535. 
  11533.  
  11534. typedef unsigned short USHORT;
  11535.  
  11536. This data type is being introduced by the OS/2 Warp Toolkit. 
  11537.  
  11538.  
  11539. ΓòÉΓòÉΓòÉ 9.43. VOID ΓòÉΓòÉΓòÉ
  11540.  
  11541. A data area of undefined format. 
  11542.  
  11543. #define VOID void
  11544.  
  11545. This data type is being introduced by the OS/2 Warp Toolkit. 
  11546.  
  11547.  
  11548. ΓòÉΓòÉΓòÉ 9.44. time_t ΓòÉΓòÉΓòÉ
  11549.  
  11550. Current calendar time. 
  11551.  
  11552. typedef long time_t;
  11553.  
  11554. This data type is being introduced by the compiler runtime. 
  11555.  
  11556.  
  11557. ΓòÉΓòÉΓòÉ 10. Text Message Files (TMF) ΓòÉΓòÉΓòÉ
  11558.  
  11559. The Text Message File API of the Workplace Shell Toolkit provides an 
  11560. alternative to the OS/2 message files, which have several drawbacks: 
  11561.  
  11562.      they need to be compiled with the mkmsgf utility 
  11563.      testing is complicated 
  11564.      some APIs like the SysGetMessage of REXX call keep the file open until 
  11565.       the shell closes, where the REXX script is running in 
  11566.  
  11567.  For that reasons many programs use plain text files, but also this has a 
  11568.  drawback, as the complete file has to be searched for every message again and 
  11569.  again. Here the Text Message File (TMF) concept jumps in, combining the 
  11570.  convenience of having editable text files while avoiding to search the whole 
  11571.  file for every message request. 
  11572.  Text message files complying to the TMF format can be used with the 
  11573.  WtkGetTextMessage, call. When a message is requested by this, the following 
  11574.  actions are performed: 
  11575.  
  11576.      the text message file is checked for being modified (compared with a 
  11577.       previously saved timestamp) 
  11578.      if modified, 
  11579.         -  an internal message id table is compiled and saved as extended 
  11580.            attribute 
  11581.         -  the current timestamp is saved as an extended attribute 
  11582.      the requested message is located by the internal message id table and 
  11583.       returned to the caller 
  11584.  
  11585.  So in most of the times the internal message id table is used to determine the 
  11586.  location of a message within the text message file, which decreases the amount 
  11587.  of required file handling drastically. 
  11588.  
  11589.  Further releases of the Workplace Shell Toolkit will be extended by a similar 
  11590.  API, either holding the file open and/or reading the file into memory, once 
  11591.  more increasing the access to messages. 
  11592.  
  11593.  
  11594. ΓòÉΓòÉΓòÉ 10.1. text message file format ΓòÉΓòÉΓòÉ
  11595.  
  11596. The Text Message Files (TMF) must comply to the following format in order to 
  11597. let WtkGetTextMessage retrieve messages out of it: 
  11598.  
  11599.      messages start with a message id in the first column of a line. The 
  11600.       message id is assembled by : 
  11601.  
  11602.         -  the string <-- 
  11603.         -  the alphanumeric message id 
  11604.         -  the string --> 
  11605.  
  11606.       A valid message id would be: <--MyString001--> 
  11607.  
  11608.      before the first message comments may be included within the file, 
  11609.       started with a semikolon in the first column. 
  11610.  
  11611.       Note: 
  11612.  
  11613.         -  After the first message id all comments are taken being part of 
  11614.            messages ! 
  11615.  
  11616.      messages may span several lines, where the carriage return and linefeed 
  11617.       characters (except of the last line of a message) will become part of the 
  11618.       message. So if you don't eant to have linefeeds in your message, make 
  11619.       sure that they don't span lines, no matter how long the line will ever 
  11620.       get 
  11621.  
  11622.      placeholders from %1 to %1 in the message text are replaced if values for 
  11623.       those are handed over to WtkGetTextMessage in the pointer table referred 
  11624.       to by the pTable parameter. 
  11625.       In opposite to the DosGetMessage call text replacement is performed even 
  11626.       if not enough parameters are supplied - where values are missing, the 
  11627.       placeholder remains unmodified within the message text. 
  11628.  
  11629.  
  11630. ΓòÉΓòÉΓòÉ 11. Settings and Details Manager ΓòÉΓòÉΓòÉ
  11631.  
  11632. The Settings and Details Manager API of the Workplace Shell Toolkit 
  11633. encapsulates the complexity of handling object settings and details by 
  11634. automating the following tasks of a Workplace Shell object class: 
  11635.  
  11636.      handling settings strings (like "NAME1=value1;NAME2=value21,value22;") 
  11637.       per object class 
  11638.  
  11639.      handling values for all of the settings per object intance. 
  11640.  
  11641.      automatic transporting object instance setting values to the settings 
  11642.       notebookpages of the object instance and vice versa. 
  11643.  
  11644.      providing an automatic translation of setup strings sent to _wpSetup into 
  11645.       changes of the settings values of an object instance, with automatic 
  11646.       update of open setting notebook pages, if desired. 
  11647.  
  11648.      querying the complete settings implemented by the WPS class for an object 
  11649.       instance in a settings string, greatly simplifying the code for 
  11650.       _wpSaveState and _wpRestoreState. While _wpSaveState can save the 
  11651.       settings as one string, the _wpRestoreState just has to send the 
  11652.       previously saved settings string to _wpSetup to initialize the object on 
  11653.       next Workplace Shell startup. 
  11654.  
  11655.  Select one of the following topics : 
  11656.  
  11657.       Handling of object settings in general 
  11658.       Handling of object settings with the Worplace Shell Toolkit 
  11659.           Callback function for the Settings Manager API 
  11660.           Supported value types 
  11661.       Handling of object details in general 
  11662.       Handling of object details with the Worplace Shell Toolkit 
  11663.  
  11664.  
  11665. ΓòÉΓòÉΓòÉ 11.1. Handling of object settings in general ΓòÉΓòÉΓòÉ
  11666.  
  11667. The general handling of object settings is divided into several parts: 
  11668.  
  11669.       creation/awakening of an object 
  11670.  
  11671.       _wpclsInitData - Initializing the meta class data 
  11672.  
  11673.                      Here variables used by all object instances are being set 
  11674.                      up. 
  11675.  
  11676.       _wpInitData - Initializing the object instance data 
  11677.  
  11678.                      Here the variables are initnalized, of which every object 
  11679.                      instance has its own copy. 
  11680.  
  11681.       _wpRestoreState - restoring previously settings values 
  11682.  
  11683.                      get previously saved values for all settings and store 
  11684.                      them in the instance variables of the object. 
  11685.  
  11686.       opening of the settings notebook / selecting a notebook page / performing 
  11687.       undo 
  11688.  
  11689.       _wpAddSettingsPages - add own setting notebook pages 
  11690.  
  11691.                      a WPS class adds setting notebook pages implementing GUI 
  11692.                      conrols for each value of the supported settings. When 
  11693.                      adding new notebook pages, a window message procedure has 
  11694.                      to be specified for each page. When using the Settings and 
  11695.                      Details Manager API of the Workplace Shell Toolkit, mostly 
  11696.                      one window message procedure is sufficient for all 
  11697.                      settings notebook pages that a WPS class implements. 
  11698.  
  11699.                      Note: 
  11700.  
  11701.                          The Settings and Details Manager API of the Workplace 
  11702.                           Shell Toolkit does not provide a function for this. 
  11703.                           This part has to be coded conventionally and is 
  11704.                           enlisted here for clarity. 
  11705.  
  11706.       WM_INITDLG in window message procedure - initialize dialog 
  11707.  
  11708.                      fill all GUI controls with the appropriate values that are 
  11709.                      stored in the instance variables of the object. 
  11710.  
  11711.       WM_COMMAND for undo pushbutton in window message procedure - restore to 
  11712.       current values 
  11713.  
  11714.                      fill all GUI controls with the appropriate values that are 
  11715.                      stored in the instance variables of the object. 
  11716.  
  11717.       closing the settings notebook / saving the current values 
  11718.  
  11719.       WM_DESTROY in window message procedure - destroy the dialog 
  11720.  
  11721.                      get values from all GUI controls, validate them and store 
  11722.                      them in the instance variables of the object. 
  11723.  
  11724.       _wpSaveState - saving current settings values 
  11725.  
  11726.                      save all values of the instance variables of the object. 
  11727.  
  11728.       external setup of an object 
  11729.  
  11730.       _wpSetup (_wpSetupOnce) - modifying the setttings values via settings 
  11731.       strings 
  11732.  
  11733.                      evaluate all settings strings. If they apply to the WPS 
  11734.                      class and contain valid values, store them in the instance 
  11735.                      variables of the object. 
  11736.  
  11737.       deletion/making dormant of an object 
  11738.  
  11739.       _wpUnInitData - Deinitializing the object instance data 
  11740.  
  11741.                      Free all resources being used by the object instance, e.g 
  11742.                      memory. 
  11743.  
  11744.       _wpclsUnInitData - Initializing the meta class data 
  11745.  
  11746.                      Free all resources being used together by all object 
  11747.                      instance, e.g memory. 
  11748.  
  11749.  
  11750. ΓòÉΓòÉΓòÉ 11.2. Handling of object settings with the Worplace Shell Toolkit ΓòÉΓòÉΓòÉ
  11751.  
  11752. Use the Workplace Shell Toolkit API as follows to automate the settings 
  11753. handling: 
  11754.  
  11755.       creation/awakening of an object 
  11756.  
  11757.       _wpclsInitData - Initializing the meta class data 
  11758.  
  11759.                      Create a settings table and fill it with definitions for 
  11760.                      all uspported settings 
  11761.  
  11762.                          WtkCreateClassSettingsTable - create the class 
  11763.                           settings table and specify the address of a callback 
  11764.                           function. 
  11765.                          WtkAddClassSetting - call this once for each setting 
  11766.                           that the WPS class should support. 
  11767.                          WtkCloseClassSettingsTable - close the table for 
  11768.                           usage by object instances 
  11769.  
  11770.       _wpInitData - Initializing the object instance data 
  11771.  
  11772.                      initialize all instance variables Create a value table for 
  11773.                      the object instance. This table contains pointers to the 
  11774.                      instance variables maintained by the WPS class. 
  11775.  
  11776.                          WtkCreateObjectValueTable - create the object value 
  11777.                           table 
  11778.  
  11779.       _wpRestoreState - restoring previously settings values 
  11780.  
  11781.                      get previously saved values for all settings and store 
  11782.                      them in the instance variables of the object by calling 
  11783.                      _wpSetup. 
  11784.  
  11785.       opening of the settings notebook / selecting a notebook page / performing 
  11786.       undo 
  11787.  
  11788.       _wpAddSettingsPages - add own setting notebook pages 
  11789.  
  11790.                      a WPS class adds setting notebook pages implementing GUI 
  11791.                      conrols for each value of the supported settings. 
  11792.  
  11793.                      Specify a single window message procedure for all settings 
  11794.                      notebook pages that a WPS class implements. Also, pass the 
  11795.                      handle to the object value table as a parameter to the 
  11796.                      window procedure, so that it can be stored with 
  11797.                      WinSetWindowULong to position QWL_USER. This handle is 
  11798.                      required within the window procedure to call any of the 
  11799.                      Wtk APIs for object handling. 
  11800.  
  11801.                      if desired, call WtkRegisterSettingsNotebook to register 
  11802.                      the notbook for automatic validation of all notebookpages, 
  11803.                      when the when the notebook is closed. Of course onle these 
  11804.                      pages can be validated, which have been registered with 
  11805.                      WtkRegisterSettingsDialog during their creation. 
  11806.  
  11807.       WM_INITDLG in window message procedure - initialize dialog 
  11808.  
  11809.                      prepare the dialog for automatic update by the setting 
  11810.                      smanager API and setup all GUI controls 
  11811.  
  11812.                          WtkRegisterSettingsDialog - register the dialog for 
  11813.                           automatic update of GUI controls and object instance 
  11814.                           values 
  11815.                          WtkReadObjectValueTable - fill all GUI controls in 
  11816.                           this dialog with the appropriate values that are 
  11817.                           stored in the instance variables of the object. You 
  11818.                           may also use WinSendMsg with WM_COMMAD for the undo 
  11819.                           button to accomplish this task, as this also calls 
  11820.                           WtkReadObjectValueTable, see below. 
  11821.  
  11822.       WM_COMMAND for undo pushbutton in window message procedure - restore to 
  11823.       current values 
  11824.  
  11825.                      refill all GUI controls in this dialog with the 
  11826.                      appropriate values that are stored in the instance 
  11827.                      variables of the object. 
  11828.  
  11829.                          WtkReadObjectValueTable - fill all GUI controls with 
  11830.                           the appropriate values that are stored in the 
  11831.                           instance variables of the object. 
  11832.  
  11833.       closing the settings notebook / saving the current values 
  11834.  
  11835.       WM_DESTROY in window message procedure - destroy the dialog 
  11836.  
  11837.                      get values from all GUI controls, validate them and store 
  11838.                      them in the instance variables of the object. 
  11839.  
  11840.                          WtkWriteObjectValueTable - fill all GUI controls with 
  11841.                           the appropriate values of the value table. 
  11842.  
  11843.       _wpSaveState - saving current settings values 
  11844.  
  11845.                      save all values of the instance variables of the object. 
  11846.  
  11847.                          WtkQueryObjectSettings - query all settings as one 
  11848.                           string that can easily be saved and further easily be 
  11849.                           restored by sending it to _wpSetup (see external 
  11850.                           setup of an object below). 
  11851.  
  11852.       external setup of an object 
  11853.  
  11854.       _wpSetup (_wpSetupOnce) - modifying the setttings values via settings 
  11855.       strings 
  11856.  
  11857.                      evaluate all settings strings. If they apply to the WPS 
  11858.                      class and contain valid values, store them in the instance 
  11859.                      variables of the object. 
  11860.  
  11861.                          WtkEvaluateObjectSettings - validates settings values 
  11862.                           and updates the object value table. 
  11863.  
  11864.       deletion/making dormant of an object 
  11865.  
  11866.       _wpUnInitData - Deinitializing the object instance data 
  11867.  
  11868.                      Free all resources being used by the object instance. 
  11869.  
  11870.                          WtkDestroyObjectValueTable - frees all memory being 
  11871.                           used by the settings manager API for the object 
  11872.                           instance 
  11873.  
  11874.       _wpclsUnInitData - Initializing the meta class data 
  11875.  
  11876.                      Free all resources being used together by all object 
  11877.                      instance. 
  11878.  
  11879.                          WtkDestroyClassSettingsTable - frees all memory being 
  11880.                           used by the settings manager API for the object 
  11881.                           class. 
  11882.  
  11883.  
  11884. ΓòÉΓòÉΓòÉ 11.2.1. Callback function for the Settings Manager API ΓòÉΓòÉΓòÉ
  11885.  
  11886. You need to specify a callback function when creating a class settings and 
  11887. details table with WtkCreateClassSettingsTable. 
  11888.  
  11889. This callback has the prototype FNCB. Depending on ulAction the callback has to 
  11890. perform the following function: 
  11891.  
  11892.  STM_CALLBACK_REPORTINIT - pvData is PCBREPORTINIT 
  11893.  
  11894.            optional - initialize all data required by the callback. You might 
  11895.            want to read initialization files or other data being required to 
  11896.            fill GUI values etc.. 
  11897.  
  11898.            This callback is being invoked on WtkCreateClassSettingsTable, which 
  11899.            is in turn to be called on _wpclsInitData. 
  11900.  
  11901.            Note: 
  11902.  
  11903.                The parameters pvObjectInstance and pvObjectData are NULL for 
  11904.                 this callback ! 
  11905.  
  11906.  STM_CALLBACK_QUERYVALUEINFO - pvData is PCBQUERYVALUEINFO 
  11907.  
  11908.            mandatory - for each (sub)value of a setting pass information to the 
  11909.            API about the setting and the GUI dialog and control IDs for 
  11910.            automatic transport of the settings (sub)value. All values, for 
  11911.            which this information is not passed back, are ignored and not 
  11912.            handled in any way. 
  11913.  
  11914.            Most important is the value type for the settings value. See also 
  11915.  
  11916.                 Supported value types 
  11917.  
  11918.  STM_CALLBACK_QUERYTARGETBUF - pvData is PCBQUERYTARGETBUF 
  11919.  
  11920.            mandatory - for each (sub)value of a setting pass the pointer to the 
  11921.            object instance variable. 
  11922.  
  11923.  STM_CALLBACK_VALIDATE - pvData is PCBVALIDATE 
  11924.  
  11925.            optional - for each (sub)value of a setting validate the provided 
  11926.            value. 
  11927.  
  11928.            Return 
  11929.  
  11930.            TRUE         The result of the validation is returned in fResult of 
  11931.                         PCBQUERYVALIDATE 
  11932.  
  11933.            FALSE        The value is to be validated with the standard 
  11934.                         validation scheme for the given value type. If no 
  11935.                         standard validation scheme exists, the value is always 
  11936.                         valid. See also 
  11937.  
  11938.                              Supported value types 
  11939.  
  11940.  STM_CALLBACK_REPORTCHANGED - pvData is PCBREPORTCHANGED 
  11941.  
  11942.            optional - for each setting take an appropriate action, when the 
  11943.            reported setting has changed either by passed setup strings 
  11944.            (WtkEvaluateObjectSettings) or modified GUI controls 
  11945.            (WtkWriteObjectValueTable). When either function exits, a last 
  11946.            change report is generated with no name and id specified in order to 
  11947.            enable any action required after all changes have been saved. 
  11948.  
  11949.  STM_CALLBACK_QUERYVALUE - pvData is PCBQUERYVALUE 
  11950.  
  11951.            optional - for each index of a setting set the target buffer for the 
  11952.            appropriate value. This callback is being invoked n times for each 
  11953.            setting, where n is equal to the parameter ulQueryIndex of 
  11954.            WtkAddClassSetting. 
  11955.  
  11956.            This value is normally set to one, and thus this callback needs not 
  11957.            to be handled. 
  11958.  
  11959.  STM_CALLBACK_QUERYINDEX - pvData is PCBQUERYINDEX 
  11960.  
  11961.            mandatory - for each (sub)value of a setting that is of type 
  11962.            STM_VALUETYPE_INDEX or STM_VALUETYPE_INDEXITEM, this callback passes 
  11963.            a string to the WPS class, which needs to be translated by the 
  11964.            callback procedure to a numeric value. 
  11965.  
  11966.            For STM_VALUETYPE_INDEX, the string may come from either a GUI 
  11967.            control or a settings string, for STM_VALUETYPE_INDEXITEM the string 
  11968.            can come only from a settings string. The index value is stored in 
  11969.            the target buffer reported on callback STM_CALLBACK_QUERYTARGETBUF 
  11970.            (mostly the object member variable). 
  11971.  
  11972.  STM_CALLBACK_QUERYSTRING - pvData is PCBQUERYSTRING 
  11973.  
  11974.            mandatory - for each (sub)value of a setting that is of type 
  11975.            STM_VALUETYPE_INDEX or STM_VALUETYPE_INDEXITEM, this callback passes 
  11976.            a numeric value to the WPS class, which needs to be translated by 
  11977.            the callback procedure to a string representing the numeric value. 
  11978.  
  11979.            For STM_VALUETYPE_INDEX, the string is used to either update a GUI 
  11980.            control or be added to a settings string, for 
  11981.            STM_VALUETYPE_INDEXITEM the string is only to be used to be added to 
  11982.            a settings string. The index value is taken from the target buffer 
  11983.            reported on callback STM_CALLBACK_QUERYTARGETBUF (mostly the object 
  11984.            member variable). 
  11985.  
  11986.  STM_CALLBACK_INITCONTROL - pvData is PCBINITCONTROL 
  11987.  
  11988.            optional - for each GUI control being associated to a (sub)value of 
  11989.            a setting, initialize the GUI control to your needs. Mostly valuable 
  11990.            for filling listboxes etc.. More, you can specify the address of a 
  11991.            subclass window procedure for a given control. 
  11992.  
  11993.  STM_CALLBACK_REPORTERROR - pvData is PCBREPORTERROR 
  11994.  
  11995.            optional - for each GUI control not containing a valid value, when 
  11996.            WtkValidateObjectValueTable was called. This enables the WPS class 
  11997.            to popup a message box. 
  11998.  
  11999.            Note: 
  12000.  
  12001.                The WPS class normally does not call 
  12002.                 WtkValidateObjectValueTable directly. Instead, to let the 
  12003.                 Settings and Details Manager API automatically validate all 
  12004.                 setting notebook dialog pages registered with 
  12005.                 WtkRegisterSettingsDialog on close of the settings notebook, 
  12006.                 call WtkRegisterSettingsNotebook within the _wpAddSettingsPages 
  12007.                 method. 
  12008.  
  12009.  STM_CALLBACK_REPORTSAVED - pvData is PCBREPORTSAVED 
  12010.  
  12011.            optional - for taking an appropriate action, when the object setting 
  12012.            values have been saved with WtkWriteObjectValueTable 
  12013.  
  12014.  STM_CALLBACK_REPORTDESTROYED - pvData is PCBREPORTDESTROYED 
  12015.  
  12016.            optional - free all resources being held by the callback. 
  12017.  
  12018.            This callback is being invoked on WtkDestroyClassSettingsTable, 
  12019.            which is in turn to be called on _wpclsUnInitData. 
  12020.  
  12021.            Note: 
  12022.  
  12023.                The parameters pvObjectInstance and pvObjectData are NULL for 
  12024.                 this callback ! 
  12025.  
  12026.  
  12027. ΓòÉΓòÉΓòÉ 11.2.2. Supported value types ΓòÉΓòÉΓòÉ
  12028.  
  12029. The Settings and Details Manager API of the Workplace Shell Toolkit supports 
  12030. several types of values. 
  12031.  
  12032. The value type must be specified on the callback with ulAction equal to 
  12033. STM_CALLBACK_QUERYVALUEINFO (pvData for this callback is PCBQUERYVALUEINFO). 
  12034.  
  12035. The following value types are supported: 
  12036.  
  12037. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  12038. Γöétype                   Γöéstandard         Γöétarget  Γöésupported GUI controls   Γöé
  12039. Γöé                       Γöévalidation       Γöébuffer  Γöé                         Γöé
  12040. Γöé                       Γöéprovided         Γöé        Γöé                         Γöé
  12041. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  12042. ΓöéSTM_VALUETYPE_STRING   ΓöéNo, always valid.ΓöéCHAR[]  Γöé- <all supported> except Γöé
  12043. Γöé                       Γöé                 Γöé        ΓöéWC_*SLIDER. WC_COMBOBOX  Γöé
  12044. Γöé                       Γöé                 Γöé        Γöéand WC_SPINBUTTON only asΓöé
  12045. Γöé                       Γöé                 Γöé        Γöélistbox                  Γöé
  12046. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  12047. ΓöéSTM_VALUETYPE_INDEX    ΓöéYes, the         ΓöéLONG    Γöé<all supported>          Γöé
  12048. Γöé                       Γöétranslation from Γöé        Γöé                         Γöé
  12049. Γöé                       Γöéstring to index  Γöé        Γöé                         Γöé
  12050. Γöé                       Γöéand vice versa   Γöé        Γöé                         Γöé
  12051. Γöé                       Γöémay not fail.    Γöé        Γöé                         Γöé
  12052. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  12053. ΓöéSTM_VALUETYPE_INDEXITEMΓöéYes, the         ΓöéLONG    ΓöéWC_LISTBOX and           Γöé
  12054. Γöé                       Γöétranslation from Γöé        ΓöéWC_COMBOBOX              Γöé
  12055. Γöé                       Γöéstring to index  Γöé        ΓöéCan currently not be usedΓöé
  12056. Γöé                       Γöéand vice versa   Γöé        Γöéfor details !!!          Γöé
  12057. Γöé                       Γöémay not fail.    Γöé        Γöé                         Γöé
  12058. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  12059. ΓöéSTM_VALUETYPE_LONG     ΓöéNo, always valid.ΓöéLONG    Γöé<all supported>          Γöé
  12060. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  12061. ΓöéSTM_VALUETYPE_TRUEFALSEΓöéYes, the value   ΓöéBOOL    Γöé<all supported> except   Γöé
  12062. Γöé                       Γöémust be either   Γöé        ΓöéWC_*SLIDER               Γöé
  12063. Γöé                       ΓöéTRUE or FALSE    Γöé        Γöé                         Γöé
  12064. Γöé                       Γöé(case            Γöé        Γöé                         Γöé
  12065. Γöé                       Γöéinsensitive).    Γöé        Γöé                         Γöé
  12066. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  12067. ΓöéSTM_VALUETYPE_YESNO    ΓöéYes, the value   ΓöéBOOL    Γöé<all supported> except   Γöé
  12068. Γöé                       Γöémust be either   Γöé        ΓöéWC_*SLIDER               Γöé
  12069. Γöé                       ΓöéYES or NO (case  Γöé        Γöé                         Γöé
  12070. Γöé                       Γöéinsensitive).    Γöé        Γöé                         Γöé
  12071. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  12072. ΓöéSTM_VALUETYPE_ONOFF    ΓöéYes, the value   ΓöéBOOL    Γöé<all supported> except   Γöé
  12073. Γöé                       Γöémust be either ONΓöé        ΓöéWC_*SLIDER               Γöé
  12074. Γöé                       Γöéor OFF (case     Γöé        Γöé                         Γöé
  12075. Γöé                       Γöéinsensitive).    Γöé        Γöé                         Γöé
  12076. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  12077.  
  12078. The following value types are reserved for using with details only: 
  12079.  
  12080.      STM_VALUETYPE_CDATE 
  12081.      STM_VALUETYPE_CTIME 
  12082.  
  12083.  
  12084. ΓòÉΓòÉΓòÉ 11.3. Handling of object details in general ΓòÉΓòÉΓòÉ
  12085.  
  12086. The general handling of object details is divided into several parts: 
  12087.  
  12088.       initializing the meta class 
  12089.  
  12090.       _wpclsQueryDetailsInfo - Retrieving information about provided details 
  12091.  
  12092.                      Here the Workplace Shell queries, what details are 
  12093.                      provided by the meta class. This includes type 
  12094.                      information, layout information for the details view and 
  12095.                      the title for the column of every detail. This method is 
  12096.                      mostly called during the initialization of the meta class. 
  12097.  
  12098.       updating the details view of a folder that contains an object 
  12099.  
  12100.       _wpQueryDetailsData - Querying the current details data 
  12101.  
  12102.                      Here the Workplace Shell queries the current set of data 
  12103.                      of an object instance, whenever it has changed. 
  12104.  
  12105.  
  12106. ΓòÉΓòÉΓòÉ 11.4. Handling of object details with the Worplace Shell Toolkit ΓòÉΓòÉΓòÉ
  12107.  
  12108. Use the Workplace Shell Toolkit API as follows to automate the details 
  12109. handling: 
  12110.  
  12111.       initializing the meta class 
  12112.  
  12113.       _wpclsQueryDetailsInfo - Retrieving information about provided details 
  12114.  
  12115.                      Call 
  12116.  
  12117.                           WtkQueryClassDetailsInfo 
  12118.                      in order to let the Settings and Details Manager report 
  12119.                      all provided details for the given WPS class. Note that 
  12120.                      when _wpclsQueryDetailsInfo is being called, your WPS 
  12121.                      class already has done the following things: 
  12122.  
  12123.                          it has registered all details by either calling 
  12124.                             -  WtkAddClassSetting or 
  12125.                             -  WtkAddClassDetail 
  12126.                           during the initialization of the meta class, where 
  12127.                           the order of of the registration determines the 
  12128.                           order, in that the details apper in the details view. 
  12129.                          for all details provided a value for pszDetailsTitle 
  12130.                           on the STM_CALLBACK_QUERYVALUEINFO callback within 
  12131.                           your Callback function for the Settings Manager API. 
  12132.  
  12133.       updating the details view of a folder that contains an object 
  12134.  
  12135.       _wpQueryDetailsData - Querying the current details data 
  12136.  
  12137.                      Call 
  12138.  
  12139.                           WtkQueryObjectDetailsData 
  12140.                      in order to let the Settings and Details Manager report 
  12141.                      all current detail data for the given WPS class. 
  12142.  
  12143.  
  12144. ΓòÉΓòÉΓòÉ 12. Extended Attributes Manager ΓòÉΓòÉΓòÉ
  12145.  
  12146. The Extended Attributes Manager API of the Workplace Shell Toolkit is designed 
  12147. to greatly ease the handling of extended attributes. While the attribute data 
  12148. structures that can be read and/or written with several OS/2 control programs, 
  12149. provide great flexibility, the setup of these structures require time consuming 
  12150. coding and testing, and such each time that you are required to handle extended 
  12151. attributes. 
  12152.  
  12153. In order to have a simplified API, the API of the Workplace Shell Toolkit 
  12154. differs from conventional extended attribute handling in several ways: 
  12155.  
  12156.      You can only read or write one extended attribute (either with a single 
  12157.       or a list of multiple values) at a time. Since this is, what you will do 
  12158.       in most cases anyway, this will not really restrict you a lot and this 
  12159.       step alone makes the following point possible: 
  12160.  
  12161.      You never have to deal with the binary structures again, if you use the 
  12162.       extended attributes API of the Workplace Shell Toolkit. All this handling 
  12163.       is completely done for you, while you just provide values for a given 
  12164.       extended attribute in a source buffer to let it be written or appended, 
  12165.       or you ask for values to be returned in a target buffer for a specific 
  12166.       type of extended attributes. The EAT_* type values and some knowledge 
  12167.       about organization of extended attributes are the only things that you 
  12168.       are still requiring in order to setup extended attributes for a given 
  12169.       file or directory. 
  12170.  
  12171.      Normally, you are required to read, modify and write an extended 
  12172.       attribute, if you do not even just replace it with a completely new 
  12173.       value. Having said this, the Workplace Shell Toolkit provides you both 
  12174.       with three APIs to let you do also these single steps one after another, 
  12175.       but also with a single step API to accomplish this task in one step. 
  12176.       Since writing exactly one value to an extended attribute is exactly, what 
  12177.       most Workplace Shell classes need to do, this simplifies your coding a 
  12178.       lot. And even if you call these APIs for several extended attributes one 
  12179.       after another (compared to setup a complex structure and write it with 
  12180.       only one call to a control program API), the effective use of the OS/2 
  12181.       filesystem cache will reduce the overhead of subsequent disk I/O 
  12182.       accesses. 
  12183.  
  12184.  See the following sections: 
  12185.  
  12186.      Reading an extended attribute 
  12187.      Writing an extended attribute 
  12188.  
  12189.  
  12190. ΓòÉΓòÉΓòÉ 12.1. Reading an extended attribute ΓòÉΓòÉΓòÉ
  12191.  
  12192. The following APIs are provided to read an extended attribute of a given file 
  12193. or directory: 
  12194.  
  12195.  WtkQueryEaSize 
  12196.            determines the size of all values of the given EA. 
  12197.  
  12198.  WtkReadEa 
  12199.            reads the value (list) of a given extended attribute into memory. 
  12200.            Use the following APIs to query all or certain of these values: 
  12201.  
  12202.                WtkFindFirstEaValue 
  12203.                WtkFindNextEaValue 
  12204.  
  12205.            Note: 
  12206.  
  12207.                Call WtkCloseEa in order to release the memory occupied by the 
  12208.                 value (list) of the extended attribute afterwards ! 
  12209.                an in-memory value (list) of an extended attribute being read 
  12210.                 by WtkReadEa can be extended by calling WtkAppendEaValue and 
  12211.                 saved to disk by WtkSaveEa. 
  12212.  
  12213.  WtkGetNextEaValue 
  12214.            In order to easily query all values of an extended attribute 
  12215.            matching a given type. call this API in a simple while loop, until 
  12216.            it returns ERROR_NO_MORE_FILES. WtkGetNextEaValue will call 
  12217.  
  12218.                WtkFindNextEaValue, 
  12219.                WtkFindNextEaValue and 
  12220.                WtkCloseEa 
  12221.  
  12222.            for you to accomplish this task. Make sure to either call 
  12223.            WtkGetNextEaValue, until it returns ERROR_NO_MORE_FILES, or call 
  12224.            WtkCloseEa yourself to free up the memory occupied by the temporary 
  12225.            in-memory value (list) for the extended attribute. 
  12226.  
  12227.  WtkReadStringEa 
  12228.            This API is even simpler to use compared to WtkGetNextEaValue when 
  12229.            it comes to read a string extended attribute. While being able to 
  12230.            read exactly one value and only a string value, no knowledge of 
  12231.            extended attributes is required at all to use it. 
  12232.  
  12233.  
  12234. ΓòÉΓòÉΓòÉ 12.2. Writing an extended attribute ΓòÉΓòÉΓòÉ
  12235.  
  12236. The following APIs are provided to write an extended attribute of a given file 
  12237. or directory: 
  12238.  
  12239.  WtkCreateEa 
  12240.            creates an empty in-memory valuelist for an extended attribute. 
  12241.  
  12242.  WtkAppendEaValue 
  12243.            appends a value to an in-memory valuelist for an extended attribute 
  12244.            that has either been created by WtkCreateEa or read from disk by 
  12245.            WtkReadEa. The value can only be appended, if the type matches the 
  12246.            current value (list). 
  12247.  
  12248.  WtkSave 
  12249.            writes a modified value (list) of a given extended attribute to 
  12250.            disk. 
  12251.  
  12252.  WtkPutEaValue 
  12253.            reads the current value (list) of an extended attribute from disk, 
  12254.            appends the given value to the list, if the type matches the current 
  12255.            value (list), and saves the newly extended valuelist to disk. 
  12256.  
  12257.  WtkWriteStringEa 
  12258.            This API is even simpler to use compared to WtkPutEaValue when it 
  12259.            comes to write an string extended attribute. While being able to 
  12260.            write exactly one value and only a string value, no knowledge of 
  12261.            extended attributes is required at all to use it. 
  12262.  
  12263.  
  12264. ΓòÉΓòÉΓòÉ 13. Memory Mapped Files Manager ΓòÉΓòÉΓòÉ
  12265.  
  12266. The Memory Mapped Files Manager API of the Workplace Shell Toolkit provides an 
  12267. API for reading and writing files by simply reading from and writing to memory. 
  12268. For that files are mapped to memory and the MMF exception handler takes care 
  12269. for that only the required parts of the file are being read from disk and only 
  12270. the modified parts are saved to disk, if requested. 
  12271.  
  12272. With memory mapped files opening a file is as easy as allocating a chunk of 
  12273. memory, and saving all changes is done by a simple API call, there is no need 
  12274. for intermediate files or for fiddeling around with file pointers. 
  12275.  
  12276. See the following sections for more information and the APIs related to them: 
  12277.  
  12278.       Intitialize MMF support 
  12279.  
  12280.           WtkInitializeMmf 
  12281.  
  12282.       allocate memory mapped file buffer or dynamic memory buffer 
  12283.  
  12284.           WtkAllocMmf 
  12285.  
  12286.       maintain buffer size 
  12287.  
  12288.           WtkQueryMmfSize 
  12289.           WtkSetMmfSize 
  12290.  
  12291.       save changes from memory mapped file buffer to disk 
  12292.  
  12293.           WtkUpdateMmf 
  12294.  
  12295.       free memory buffer 
  12296.  
  12297.           WtkFreeMmf 
  12298.  
  12299.       terminate MMF support 
  12300.  
  12301.           WtkTerminateMmf 
  12302.  
  12303.  
  12304. ΓòÉΓòÉΓòÉ 13.1. initialize MMF support ΓòÉΓòÉΓòÉ
  12305.  
  12306. When using the Memory Mapped Files Manager API, it must be initialized by a 
  12307. call to WtkInitializeMmf, this must be done per thread. 
  12308.  
  12309. Beside initializing the internal data this call will register the MMF exception 
  12310. handler. 
  12311.  
  12312. Note: 
  12313.  
  12314.      When leaving the function that called WtkInitializeMmf, WtkTerminateMmf 
  12315.       must be called to deregister the exception handler again, especially if 
  12316.       other exception handlers are used beside the one for MMF support. 
  12317.       Otherwise unpredictable results (most often simply protection violations 
  12318.       may occurr). 
  12319.  
  12320.  
  12321. ΓòÉΓòÉΓòÉ 13.2. allocating a memory mapped file buffer ΓòÉΓòÉΓòÉ
  12322.  
  12323. Allocating a file with the Memory Mapped Files Manager API by a call to 
  12324. WtkAllocMmf does not really already allocate memory. Instead, it only reserves 
  12325. address space for the requested memory object so that the new and/or existant 
  12326. file could fit into the memory. The maximum size of the memory object must be 
  12327. specified on allocation, because it cannot be extended later. 
  12328.  
  12329. All further access to the file can simply be done by accessing the memory, 
  12330. everything else is being taken care by the MMF exception handler. 
  12331.  
  12332.  
  12333. ΓòÉΓòÉΓòÉ 13.3. allocating a memory only buffer ΓòÉΓòÉΓòÉ
  12334.  
  12335. The Memory Mapped Files Manager API WtkAllocMmf can also be used to allocate a 
  12336. memory object without mapping a file to it. Such a memory object has still the 
  12337. advantage that it can grow dynamically, so subsequent handling of memory 
  12338. (sub)allocation within the uncommitted memory object is done automatically by 
  12339. the MMF exception handler. 
  12340.  
  12341.  
  12342. ΓòÉΓòÉΓòÉ 13.4. update a file from  a memory mapped file buffer ΓòÉΓòÉΓòÉ
  12343.  
  12344. After having modified a memory mapped file buffer all changes can be written 
  12345. back to disk by a call to WtkUpdateMmf. When doing so, only the memory pages 
  12346. being marked as modified by the MMF exception handler are written to disk. 
  12347.  
  12348.  
  12349. ΓòÉΓòÉΓòÉ 13.5. MMF exception handler ΓòÉΓòÉΓòÉ
  12350.  
  12351. The exception handler used by the Memory Mapped Files Manager API is 
  12352. responsible for keeping track of the file being mapped to memory. 
  12353.  
  12354. On PC platforms memory is reserved and or allocated in 4 Kb memory pages and 
  12355. every page can among others have the attributes committed for read access 
  12356. and/or committed for write access.  Having reserved the memory address space 
  12357. only at first, none of the commit attributes are set, this is called 
  12358. uncommitted memory. Every access now of uncommitted memory will normally cause 
  12359. an access violation. This fact is used by the MMF exception handler, it 
  12360. intercepts all exceptions for allocated memory mapped file buffers and performs 
  12361. the following actions: 
  12362.  
  12363.  on a read access to a memory page not committed for read 
  12364.     read the 4 Kb portion of the mapped file and mark this memory page 
  12365.     committed for read access 
  12366.  
  12367.  on a write access to a memory page not committed for write 
  12368.  
  12369.         perform the action for memory not being committed for read, if that 
  12370.          memory page was not read before 
  12371.         mark this memory page committed for write access, so that a call to 
  12372.          WtkUpdateMmf later can write the modified pages back to disk. 
  12373.  
  12374.  
  12375. ΓòÉΓòÉΓòÉ 14. Modifying and distributing the Workplace Shell Toolkit ΓòÉΓòÉΓòÉ
  12376.  
  12377. The WPS Toolkit package is free software. 
  12378.  
  12379. You can redistribute it and/or modify it under the terms of the GNU Library 
  12380. General Public License as published by the Free Software Foundation, in version 
  12381. 2 as it comes in the "COPYING.LIB" file of the WPS Toolkit main distribution. 
  12382.  
  12383. This library is distributed in the hope that it will be useful, but WITHOUT ANY 
  12384. WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
  12385. PARTICULAR PURPOSE. 
  12386.  
  12387. See the GNU Library General Public License for more details. 
  12388.  
  12389.  
  12390. ΓòÉΓòÉΓòÉ 14.1. GNU Library General Public License ΓòÉΓòÉΓòÉ
  12391.  
  12392.                   GNU LIBRARY GENERAL PUBLIC LICENSE
  12393.                        Version 2, June 1991
  12394.  
  12395.  Copyright (C) 1991 Free Software Foundation, Inc.
  12396.                     675 Mass Ave, Cambridge, MA 02139, USA
  12397.  Everyone is permitted to copy and distribute verbatim copies
  12398.  of this license document, but changing it is not allowed.
  12399.  
  12400. [This is the first released version of the library GPL.  It is
  12401.  numbered 2 because it goes with version 2 of the ordinary GPL.]
  12402.  
  12403.                             Preamble
  12404.  
  12405.   The licenses for most software are designed to take away your
  12406. freedom to share and change it.  By contrast, the GNU General Public
  12407. Licenses are intended to guarantee your freedom to share and change
  12408. free software--to make sure the software is free for all its users.
  12409.  
  12410.   This license, the Library General Public License, applies to some
  12411. specially designated Free Software Foundation software, and to any
  12412. other libraries whose authors decide to use it.  You can use it for
  12413. your libraries, too.
  12414.  
  12415.   When we speak of free software, we are referring to freedom, not
  12416. price.  Our General Public Licenses are designed to make sure that you
  12417. have the freedom to distribute copies of free software (and charge for
  12418. this service if you wish), that you receive source code or can get it
  12419. if you want it, that you can change the software or use pieces of it
  12420. in new free programs; and that you know you can do these things.
  12421.  
  12422.   To protect your rights, we need to make restrictions that forbid
  12423. anyone to deny you these rights or to ask you to surrender the rights.
  12424. These restrictions translate to certain responsibilities for you if
  12425. you distribute copies of the library, or if you modify it.
  12426.  
  12427.   For example, if you distribute copies of the library, whether gratis
  12428. or for a fee, you must give the recipients all the rights that we gave
  12429. you.  You must make sure that they, too, receive or can get the source
  12430. code.  If you link a program with the library, you must provide
  12431. complete object files to the recipients so that they can relink them
  12432. with the library, after making changes to the library and recompiling
  12433. it.  And you must show them these terms so they know their rights.
  12434.  
  12435.   Our method of protecting your rights has two steps: (1) copyright
  12436. the library, and (2) offer you this license which gives you legal
  12437. permission to copy, distribute and/or modify the library.
  12438.  
  12439.   Also, for each distributor's protection, we want to make certain
  12440. that everyone understands that there is no warranty for this free
  12441. library.  If the library is modified by someone else and passed on, we
  12442. want its recipients to know that what they have is not the original
  12443. version, so that any problems introduced by others will not reflect on
  12444. the original authors' reputations.
  12445.  
  12446.   Finally, any free program is threatened constantly by software
  12447. patents.  We wish to avoid the danger that companies distributing free
  12448. software will individually obtain patent licenses, thus in effect
  12449. transforming the program into proprietary software.  To prevent this,
  12450. we have made it clear that any patent must be licensed for everyone's
  12451. free use or not licensed at all.
  12452.  
  12453.   Most GNU software, including some libraries, is covered by the ordinary
  12454. GNU General Public License, which was designed for utility programs.  This
  12455. license, the GNU Library General Public License, applies to certain
  12456. designated libraries.  This license is quite different from the ordinary
  12457. one; be sure to read it in full, and don't assume that anything in it is
  12458. the same as in the ordinary license.
  12459.  
  12460.   The reason we have a separate public license for some libraries is that
  12461. they blur the distinction we usually make between modifying or adding to a
  12462. program and simply using it.  Linking a program with a library, without
  12463. changing the library, is in some sense simply using the library, and is
  12464. analogous to running a utility program or application program.  However, in
  12465. a textual and legal sense, the linked executable is a combined work, a
  12466. derivative of the original library, and the ordinary General Public License
  12467. treats it as such.
  12468.  
  12469.   Because of this blurred distinction, using the ordinary General
  12470. Public License for libraries did not effectively promote software
  12471. sharing, because most developers did not use the libraries.  We
  12472. concluded that weaker conditions might promote sharing better.
  12473.  
  12474.   However, unrestricted linking of non-free programs would deprive the
  12475. users of those programs of all benefit from the free status of the
  12476. libraries themselves.  This Library General Public License is intended to
  12477. permit developers of non-free programs to use free libraries, while
  12478. preserving your freedom as a user of such programs to change the free
  12479. libraries that are incorporated in them.  (We have not seen how to achieve
  12480. this as regards changes in header files, but we have achieved it as regards
  12481. changes in the actual functions of the Library.)  The hope is that this
  12482. will lead to faster development of free libraries.
  12483.  
  12484.   The precise terms and conditions for copying, distribution and
  12485. modification follow.  Pay close attention to the difference between a
  12486. "work based on the library" and a "work that uses the library".  The
  12487. former contains code derived from the library, while the latter only
  12488. works together with the library.
  12489.  
  12490.   Note that it is possible for a library to be covered by the ordinary
  12491. General Public License rather than by this special one.
  12492.  
  12493.                   GNU LIBRARY GENERAL PUBLIC LICENSE
  12494.    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  12495.  
  12496.   0. This License Agreement applies to any software library which
  12497. contains a notice placed by the copyright holder or other authorized
  12498. party saying it may be distributed under the terms of this Library
  12499. General Public License (also called "this License").  Each licensee is
  12500. addressed as "you".
  12501.  
  12502.   A "library" means a collection of software functions and/or data
  12503. prepared so as to be conveniently linked with application programs
  12504. (which use some of those functions and data) to form executables.
  12505.  
  12506.   The "Library", below, refers to any such software library or work
  12507. which has been distributed under these terms.  A "work based on the
  12508. Library" means either the Library or any derivative work under
  12509. copyright law: that is to say, a work containing the Library or a
  12510. portion of it, either verbatim or with modifications and/or translated
  12511. straightforwardly into another language.  (Hereinafter, translation is
  12512. included without limitation in the term "modification".)
  12513.  
  12514.   "Source code" for a work means the preferred form of the work for
  12515. making modifications to it.  For a library, complete source code means
  12516. all the source code for all modules it contains, plus any associated
  12517. interface definition files, plus the scripts used to control compilation
  12518. and installation of the library.
  12519.  
  12520.   Activities other than copying, distribution and modification are not
  12521. covered by this License; they are outside its scope.  The act of
  12522. running a program using the Library is not restricted, and output from
  12523. such a program is covered only if its contents constitute a work based
  12524. on the Library (independent of the use of the Library in a tool for
  12525. writing it).  Whether that is true depends on what the Library does
  12526. and what the program that uses the Library does.
  12527.  
  12528.   1. You may copy and distribute verbatim copies of the Library's
  12529. complete source code as you receive it, in any medium, provided that
  12530. you conspicuously and appropriately publish on each copy an
  12531. appropriate copyright notice and disclaimer of warranty; keep intact
  12532. all the notices that refer to this License and to the absence of any
  12533. warranty; and distribute a copy of this License along with the
  12534. Library.
  12535.  
  12536.   You may charge a fee for the physical act of transferring a copy,
  12537. and you may at your option offer warranty protection in exchange for a
  12538. fee.
  12539.  
  12540.   2. You may modify your copy or copies of the Library or any portion
  12541. of it, thus forming a work based on the Library, and copy and
  12542. distribute such modifications or work under the terms of Section 1
  12543. above, provided that you also meet all of these conditions:
  12544.  
  12545.     a) The modified work must itself be a software library.
  12546.  
  12547.     b) You must cause the files modified to carry prominent notices
  12548.     stating that you changed the files and the date of any change.
  12549.  
  12550.     c) You must cause the whole of the work to be licensed at no
  12551.     charge to all third parties under the terms of this License.
  12552.  
  12553.     d) If a facility in the modified Library refers to a function or a
  12554.     table of data to be supplied by an application program that uses
  12555.     the facility, other than as an argument passed when the facility
  12556.     is invoked, then you must make a good faith effort to ensure that,
  12557.     in the event an application does not supply such function or
  12558.     table, the facility still operates, and performs whatever part of
  12559.     its purpose remains meaningful.
  12560.  
  12561.     (For example, a function in a library to compute square roots has
  12562.     a purpose that is entirely well-defined independent of the
  12563.     application.  Therefore, Subsection 2d requires that any
  12564.     application-supplied function or table used by this function must
  12565.     be optional: if the application does not supply it, the square
  12566.     root function must still compute square roots.)
  12567.  
  12568. These requirements apply to the modified work as a whole.  If
  12569. identifiable sections of that work are not derived from the Library,
  12570. and can be reasonably considered independent and separate works in
  12571. themselves, then this License, and its terms, do not apply to those
  12572. sections when you distribute them as separate works.  But when you
  12573. distribute the same sections as part of a whole which is a work based
  12574. on the Library, the distribution of the whole must be on the terms of
  12575. this License, whose permissions for other licensees extend to the
  12576. entire whole, and thus to each and every part regardless of who wrote
  12577. it.
  12578.  
  12579. Thus, it is not the intent of this section to claim rights or contest
  12580. your rights to work written entirely by you; rather, the intent is to
  12581. exercise the right to control the distribution of derivative or
  12582. collective works based on the Library.
  12583.  
  12584. In addition, mere aggregation of another work not based on the Library
  12585. with the Library (or with a work based on the Library) on a volume of
  12586. a storage or distribution medium does not bring the other work under
  12587. the scope of this License.
  12588.  
  12589.   3. You may opt to apply the terms of the ordinary GNU General Public
  12590. License instead of this License to a given copy of the Library.  To do
  12591. this, you must alter all the notices that refer to this License, so
  12592. that they refer to the ordinary GNU General Public License, version 2,
  12593. instead of to this License.  (If a newer version than version 2 of the
  12594. ordinary GNU General Public License has appeared, then you can specify
  12595. that version instead if you wish.)  Do not make any other change in
  12596. these notices.
  12597.  
  12598.   Once this change is made in a given copy, it is irreversible for
  12599. that copy, so the ordinary GNU General Public License applies to all
  12600. subsequent copies and derivative works made from that copy.
  12601.  
  12602.   This option is useful when you wish to copy part of the code of
  12603. the Library into a program that is not a library.
  12604.  
  12605.   4. You may copy and distribute the Library (or a portion or
  12606. derivative of it, under Section 2) in object code or executable form
  12607. under the terms of Sections 1 and 2 above provided that you accompany
  12608. it with the complete corresponding machine-readable source code, which
  12609. must be distributed under the terms of Sections 1 and 2 above on a
  12610. medium customarily used for software interchange.
  12611.  
  12612.   If distribution of object code is made by offering access to copy
  12613. from a designated place, then offering equivalent access to copy the
  12614. source code from the same place satisfies the requirement to
  12615. distribute the source code, even though third parties are not
  12616. compelled to copy the source along with the object code.
  12617.  
  12618.   5. A program that contains no derivative of any portion of the
  12619. Library, but is designed to work with the Library by being compiled or
  12620. linked with it, is called a "work that uses the Library".  Such a
  12621. work, in isolation, is not a derivative work of the Library, and
  12622. therefore falls outside the scope of this License.
  12623.  
  12624.   However, linking a "work that uses the Library" with the Library
  12625. creates an executable that is a derivative of the Library (because it
  12626. contains portions of the Library), rather than a "work that uses the
  12627. library".  The executable is therefore covered by this License.
  12628. Section 6 states terms for distribution of such executables.
  12629.  
  12630.   When a "work that uses the Library" uses material from a header file
  12631. that is part of the Library, the object code for the work may be a
  12632. derivative work of the Library even though the source code is not.
  12633. Whether this is true is especially significant if the work can be
  12634. linked without the Library, or if the work is itself a library.  The
  12635. threshold for this to be true is not precisely defined by law.
  12636.  
  12637.   If such an object file uses only numerical parameters, data
  12638. structure layouts and accessors, and small macros and small inline
  12639. functions (ten lines or less in length), then the use of the object
  12640. file is unrestricted, regardless of whether it is legally a derivative
  12641. work.  (Executables containing this object code plus portions of the
  12642. Library will still fall under Section 6.)
  12643.  
  12644.   Otherwise, if the work is a derivative of the Library, you may
  12645. distribute the object code for the work under the terms of Section 6.
  12646. Any executables containing that work also fall under Section 6,
  12647. whether or not they are linked directly with the Library itself.
  12648.  
  12649.   6. As an exception to the Sections above, you may also compile or
  12650. link a "work that uses the Library" with the Library to produce a
  12651. work containing portions of the Library, and distribute that work
  12652. under terms of your choice, provided that the terms permit
  12653. modification of the work for the customer's own use and reverse
  12654. engineering for debugging such modifications.
  12655.  
  12656.   You must give prominent notice with each copy of the work that the
  12657. Library is used in it and that the Library and its use are covered by
  12658. this License.  You must supply a copy of this License.  If the work
  12659. during execution displays copyright notices, you must include the
  12660. copyright notice for the Library among them, as well as a reference
  12661. directing the user to the copy of this License.  Also, you must do one
  12662. of these things:
  12663.  
  12664.     a) Accompany the work with the complete corresponding
  12665.     machine-readable source code for the Library including whatever
  12666.     changes were used in the work (which must be distributed under
  12667.     Sections 1 and 2 above); and, if the work is an executable linked
  12668.     with the Library, with the complete machine-readable "work that
  12669.     uses the Library", as object code and/or source code, so that the
  12670.     user can modify the Library and then relink to produce a modified
  12671.     executable containing the modified Library.  (It is understood
  12672.     that the user who changes the contents of definitions files in the
  12673.     Library will not necessarily be able to recompile the application
  12674.     to use the modified definitions.)
  12675.  
  12676.     b) Accompany the work with a written offer, valid for at
  12677.     least three years, to give the same user the materials
  12678.     specified in Subsection 6a, above, for a charge no more
  12679.     than the cost of performing this distribution.
  12680.  
  12681.     c) If distribution of the work is made by offering access to copy
  12682.     from a designated place, offer equivalent access to copy the above
  12683.     specified materials from the same place.
  12684.  
  12685.     d) Verify that the user has already received a copy of these
  12686.     materials or that you have already sent this user a copy.
  12687.  
  12688.   For an executable, the required form of the "work that uses the
  12689. Library" must include any data and utility programs needed for
  12690. reproducing the executable from it.  However, as a special exception,
  12691. the source code distributed need not include anything that is normally
  12692. distributed (in either source or binary form) with the major
  12693. components (compiler, kernel, and so on) of the operating system on
  12694. which the executable runs, unless that component itself accompanies
  12695. the executable.
  12696.  
  12697.   It may happen that this requirement contradicts the license
  12698. restrictions of other proprietary libraries that do not normally
  12699. accompany the operating system.  Such a contradiction means you cannot
  12700. use both them and the Library together in an executable that you
  12701. distribute.
  12702.  
  12703.   7. You may place library facilities that are a work based on the
  12704. Library side-by-side in a single library together with other library
  12705. facilities not covered by this License, and distribute such a combined
  12706. library, provided that the separate distribution of the work based on
  12707. the Library and of the other library facilities is otherwise
  12708. permitted, and provided that you do these two things:
  12709.  
  12710.     a) Accompany the combined library with a copy of the same work
  12711.     based on the Library, uncombined with any other library
  12712.     facilities.  This must be distributed under the terms of the
  12713.     Sections above.
  12714.  
  12715.     b) Give prominent notice with the combined library of the fact
  12716.     that part of it is a work based on the Library, and explaining
  12717.     where to find the accompanying uncombined form of the same work.
  12718.  
  12719.   8. You may not copy, modify, sublicense, link with, or distribute
  12720. the Library except as expressly provided under this License.  Any
  12721. attempt otherwise to copy, modify, sublicense, link with, or
  12722. distribute the Library is void, and will automatically terminate your
  12723. rights under this License.  However, parties who have received copies,
  12724. or rights, from you under this License will not have their licenses
  12725. terminated so long as such parties remain in full compliance.
  12726.  
  12727.   9. You are not required to accept this License, since you have not
  12728. signed it.  However, nothing else grants you permission to modify or
  12729. distribute the Library or its derivative works.  These actions are
  12730. prohibited by law if you do not accept this License.  Therefore, by
  12731. modifying or distributing the Library (or any work based on the
  12732. Library), you indicate your acceptance of this License to do so, and
  12733. all its terms and conditions for copying, distributing or modifying
  12734. the Library or works based on it.
  12735.  
  12736.   10. Each time you redistribute the Library (or any work based on the
  12737. Library), the recipient automatically receives a license from the
  12738. original licensor to copy, distribute, link with or modify the Library
  12739. subject to these terms and conditions.  You may not impose any further
  12740. restrictions on the recipients' exercise of the rights granted herein.
  12741. You are not responsible for enforcing compliance by third parties to
  12742. this License.
  12743.  
  12744.   11. If, as a consequence of a court judgment or allegation of patent
  12745. infringement or for any other reason (not limited to patent issues),
  12746. conditions are imposed on you (whether by court order, agreement or
  12747. otherwise) that contradict the conditions of this License, they do not
  12748. excuse you from the conditions of this License.  If you cannot
  12749. distribute so as to satisfy simultaneously your obligations under this
  12750. License and any other pertinent obligations, then as a consequence you
  12751. may not distribute the Library at all.  For example, if a patent
  12752. license would not permit royalty-free redistribution of the Library by
  12753. all those who receive copies directly or indirectly through you, then
  12754. the only way you could satisfy both it and this License would be to
  12755. refrain entirely from distribution of the Library.
  12756.  
  12757. If any portion of this section is held invalid or unenforceable under any
  12758. particular circumstance, the balance of the section is intended to apply,
  12759. and the section as a whole is intended to apply in other circumstances.
  12760.  
  12761. It is not the purpose of this section to induce you to infringe any
  12762. patents or other property right claims or to contest validity of any
  12763. such claims; this section has the sole purpose of protecting the
  12764. integrity of the free software distribution system which is
  12765. implemented by public license practices.  Many people have made
  12766. generous contributions to the wide range of software distributed
  12767. through that system in reliance on consistent application of that
  12768. system; it is up to the author/donor to decide if he or she is willing
  12769. to distribute software through any other system and a licensee cannot
  12770. impose that choice.
  12771.  
  12772. This section is intended to make thoroughly clear what is believed to
  12773. be a consequence of the rest of this License.
  12774.  
  12775.   12. If the distribution and/or use of the Library is restricted in
  12776. certain countries either by patents or by copyrighted interfaces, the
  12777. original copyright holder who places the Library under this License may add
  12778. an explicit geographical distribution limitation excluding those countries,
  12779. so that distribution is permitted only in or among countries not thus
  12780. excluded.  In such case, this License incorporates the limitation as if
  12781. written in the body of this License.
  12782.  
  12783.   13. The Free Software Foundation may publish revised and/or new
  12784. versions of the Library General Public License from time to time.
  12785. Such new versions will be similar in spirit to the present version,
  12786. but may differ in detail to address new problems or concerns.
  12787.  
  12788. Each version is given a distinguishing version number.  If the Library
  12789. specifies a version number of this License which applies to it and
  12790. "any later version", you have the option of following the terms and
  12791. conditions either of that version or of any later version published by
  12792. the Free Software Foundation.  If the Library does not specify a
  12793. license version number, you may choose any version ever published by
  12794. the Free Software Foundation.
  12795.  
  12796.   14. If you wish to incorporate parts of the Library into other free
  12797. programs whose distribution conditions are incompatible with these,
  12798. write to the author to ask for permission.  For software which is
  12799. copyrighted by the Free Software Foundation, write to the Free
  12800. Software Foundation; we sometimes make exceptions for this.  Our
  12801. decision will be guided by the two goals of preserving the free status
  12802. of all derivatives of our free software and of promoting the sharing
  12803. and reuse of software generally.
  12804.  
  12805.                             NO WARRANTY
  12806.  
  12807.   15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
  12808. WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
  12809. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
  12810. OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
  12811. KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
  12812. IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  12813. PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  12814. LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
  12815. THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  12816.  
  12817.   16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  12818. WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
  12819. AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
  12820. FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
  12821. CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
  12822. LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
  12823. RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
  12824. FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
  12825. SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  12826. DAMAGES.
  12827.  
  12828.                      END OF TERMS AND CONDITIONS
  12829.  
  12830.      Appendix: How to Apply These Terms to Your New Libraries
  12831.  
  12832.   If you develop a new library, and you want it to be of the greatest
  12833. possible use to the public, we recommend making it free software that
  12834. everyone can redistribute and change.  You can do so by permitting
  12835. redistribution under these terms (or, alternatively, under the terms of the
  12836. ordinary General Public License).
  12837.  
  12838.   To apply these terms, attach the following notices to the library.  It is
  12839. safest to attach them to the start of each source file to most effectively
  12840. convey the exclusion of warranty; and each file should have at least the
  12841. "copyright" line and a pointer to where the full notice is found.
  12842.  
  12843.     <one line to give the library's name and a brief idea of what it does.>
  12844.     Copyright (C) <year> <name of author>
  12845.  
  12846.     This library is free software; you can redistribute it and/or
  12847.     modify it under the terms of the GNU Library General Public
  12848.     License as published by the Free Software Foundation; either
  12849.     version 2 of the License, or (at your option) any later version.
  12850.  
  12851.     This library is distributed in the hope that it will be useful,
  12852.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12853.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12854.     Library General Public License for more details.
  12855.  
  12856.     You should have received a copy of the GNU Library General Public
  12857.     License along with this library; if not, write to the Free
  12858.     Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  12859.  
  12860. Also add information on how to contact you by electronic and paper mail.
  12861.  
  12862. You should also get your employer (if you work as a programmer) or your
  12863. school, if any, to sign a "copyright disclaimer" for the library, if
  12864. necessary.  Here is a sample; alter the names:
  12865.  
  12866.   Yoyodyne, Inc., hereby disclaims all copyright interest in the
  12867.   library `Frob' (a library for tweaking knobs) written by James Random Hacker.
  12868.  
  12869.   <signature of Ty Coon>, 1 April 1990
  12870.   Ty Coon, President of Vice
  12871.  
  12872. That's all there is to it!
  12873.  
  12874.  
  12875. ΓòÉΓòÉΓòÉ 15. Contact ΓòÉΓòÉΓòÉ
  12876.  
  12877. If you have suggestions for or problems with the Workplace Shell Toolkit, send 
  12878. email to 
  12879.  
  12880.       wpstk@netlabs.org 
  12881.  
  12882.  As soon as the project team grows to some more members, we will also install a 
  12883.  mailing list. 
  12884.  
  12885.  
  12886. ΓòÉΓòÉΓòÉ 16. Credits ΓòÉΓòÉΓòÉ
  12887.  
  12888. Please note the following credits and thank-yous: 
  12889.  
  12890.  Radim Kolar (email: 2:423/66.111@FidoNet.Org) 
  12891.            for making his CRC package with source public domain. It was the 
  12892.            basis for the CRC related helper functions. 
  12893.  
  12894.  Ulrich Moeller (email: ulrich.moeller@rz.hu-berlin.de) 
  12895.            Inventor of the XWorkplace and WarpIn packages, for giving a lot of 
  12896.            ideas via telephone and by making his packages OpenSource on 
  12897.            Netlabs. 
  12898.  
  12899.  Sergey I. Yevtushenko (email: es@os2.kiev.ua) 
  12900.            for his MMF library. This was the base for the Memory Mapped Files 
  12901.            ManagerAPI in this toolkit, where it was only extended to have a 
  12902.            separate manager for each tread. See also Sergey's article 
  12903.            Memory-Mapped files in OS/2 in the Electronic Developers Magazine 
  12904.            (EDM/2) issue of 10/1998. 
  12905.  
  12906.  
  12907. ΓòÉΓòÉΓòÉ 17. Authors ΓòÉΓòÉΓòÉ
  12908.  
  12909. Currently, the following persons have contributed to the Workplace Shell 
  12910. Toolkit: 
  12911.  
  12912.  Christian Langanke (email: cla@clanganke.de) 
  12913.            Inventor of the WPS toolkit, author of "Animated mouse Pointer for 
  12914.            OS/2", contributor to XWorkplace, coded and/or integrated all of the 
  12915.            functions of the first release and the makefiles and batch files 
  12916.            required for compilation. See his homepage for lots of free 
  12917.            utilities for OS/2 and eComStation at: 
  12918.            http://www.clanganke.de/os2 
  12919.  
  12920.  
  12921. ΓòÉΓòÉΓòÉ 18. Appendix: Building the Workplace Shell Toolkit library / samples ΓòÉΓòÉΓòÉ
  12922.  
  12923. The Workplace Shell Toolkit provides makefiles for the supported compilers, 
  12924. where each source directory contains both a 
  12925.  
  12926.  makefile            being the makefile for NMAKE (for IBM compilers only), and 
  12927.                      a 
  12928.  GNUmakefile         being the makefile for GNU make (for the emx compiler 
  12929.                      only) 
  12930.  
  12931.  Each of them includes a file from within the the config directory, which 
  12932.  determines all the compiler and linker flags etc. and the relative pathnames 
  12933.  to the directories holding object modules, libraries, etc. to be created 
  12934.  during the build. 
  12935.  
  12936.  All created files are being written to the directories: 
  12937.  
  12938.  compile             for object modules, sample program executables, other 
  12939.                      intermediate files 
  12940.                      The subdirectories cset2s, cset2m, vac3 and gcc contain 
  12941.                      the files according to the used compiler and, for the IBM 
  12942.                      CSet/2 compiler, also according to the thread mode (mixing 
  12943.                      of singlethreaded or multithreaded code not allowed with 
  12944.                      this). 
  12945.  
  12946.  ipf                 for intermediate files required to create the online help 
  12947.                      file. 
  12948.                      This directory is being created only when compiling the 
  12949.                      source distribution. 
  12950.                      Otherwise, it already exists. 
  12951.  
  12952.  lib                 for the Workplace Shell Toolkit library file to be linked 
  12953.                      with your application 
  12954.  
  12955.                      Note: 
  12956.  
  12957.                          when you compile the Workplace Shell Toolkit 
  12958.                           yourself, the resulting libraries are put into 
  12959.                           directories named either debug or release instead of 
  12960.                           lib, depending on the debug status during 
  12961.                           compilation. 
  12962.  
  12963.                      The subdirectories cset2s, cset2m, vac3 and gcc contain 
  12964.                      the library file according to the used compiler and, for 
  12965.                      the IBM CSet/2 compiler, also according to the thread mode 
  12966.                      (mixing of singlethreaded or multithreaded code not 
  12967.                      allowed with this). 
  12968.                      This directory is being created only when compiling the 
  12969.                      source distribution. 
  12970.                      Otherwise, it already exists. 
  12971.  
  12972.  book                for the documentation files in INF format 
  12973.                      This directory is being created only when compiling the 
  12974.                      source distribution. 
  12975.                      Otherwise, it already exists. 
  12976.  
  12977.  If these directories do not exist, the make process creates them when being 
  12978.  invoked for the first time. 
  12979.  
  12980.  See the following sections for details about include files used by the 
  12981.  (GNU)makefiles for your compiler: 
  12982.  
  12983.      IBM C Set ++  V2.1 / IBM VisualAge C++ V3.0 for OS/2 
  12984.      emx 0.9d for OS/2 
  12985.  
  12986.  
  12987. ΓòÉΓòÉΓòÉ 18.1. IBM C Set ++  V2.1 / IBM VisualAge C++ V3.0 for OS/2 ΓòÉΓòÉΓòÉ
  12988.  
  12989. The following files are used by the makefiles of the Workplace Shell Toolkit in 
  12990. order to define flags and inference rules for usage with the IBM compilers. 
  12991. Normally the makefile process should only be configured by the project team, if 
  12992. you require changes, please tell the team about it. : 
  12993.  
  12994.  makefile                 makefile for NMAKE in each source directory 
  12995.  
  12996.  config\rules.in          This file is included by all makefiles (makefile in 
  12997.                           each source directory) of the Workplace Shell 
  12998.                           Toolkit. 
  12999.                           It determines flags and inference rules for most 
  13000.                           tools and utilities used for the compilation process. 
  13001.                           Please do not modify this file ! 
  13002.  
  13003.  config\project.in        This file is included by config\rules.in 
  13004.                           This is the project specific extension to 
  13005.                           config\rules.in. 
  13006.  
  13007.  config.cmd               This program is called by project.in to perform the 
  13008.                           following tasks: 
  13009.  
  13010.                               determine the current compiler and tookit 
  13011.                               determine if NMAKE is compiling sources in the 
  13012.                                developer tree or within an installation tree of 
  13013.                                a binary release (results in different 
  13014.                                directories where the libraries wpstk*.lib can 
  13015.                                be found) 
  13016.  
  13017.  
  13018. ΓòÉΓòÉΓòÉ 18.2. emx 0.9d for OS/2 ΓòÉΓòÉΓòÉ
  13019.  
  13020. The following files are used by the makefiles of the Workplace Shell Toolkit in 
  13021. order to define flags and inference rules for usage with the emx compiler. 
  13022. Normally the makefile process should only be configured by the project team, if 
  13023. you require changes, please tell the team about it. : The following files are 
  13024. provided with the Workplace Shell Toolkit in order to configure the makefiles 
  13025. for usage with the emx compiler: 
  13026.  
  13027.  GNUmakefile              makefile for GNU make in each source directory 
  13028.  
  13029.  config\GNUrules.in       This file is included by all makefiles (GNUmakefile 
  13030.                           in each source directory) of the Workplace Shell 
  13031.                           Toolkit. 
  13032.                           It determines flags and inference rules for most 
  13033.                           tools and utilities used for the compilation process. 
  13034.                           Please do not modify this file ! 
  13035.  
  13036.  config\GNUproject.in     This file is included by config\GNUrules.in 
  13037.                           This is the project specific extension to 
  13038.                           config\GNUrules.in. 
  13039.  
  13040.  config.cmd               This program is called by GNUproject.in to perform 
  13041.                           the following tasks: 
  13042.  
  13043.                               determine the current compiler and tookit 
  13044.                               determine if GNU make is compiling sources in 
  13045.                                the developer tree or within an installation 
  13046.                                tree of a binary release (results in different 
  13047.                                directories where the libraries wpstk*.lib can 
  13048.                                be found) 
  13049.                               if not already exists, creates OMF versions of 
  13050.                                the emx libraries (.a to .lib) in the lib 
  13051.                                directory of the emx compiler tree. 
  13052.                               creates modified copies of some Workplace Shell 
  13053.                                headers to work with emx 
  13054.                               for IBM Toolkit for OS/2 WARP 4, creates a 
  13055.                                modified copy of os2def.h to eliminate keywords 
  13056.                                for thunking not being supported by emx 
  13057.                                (normally not used by WPS classes anyway...) 
  13058.  
  13059.  
  13060. ΓòÉΓòÉΓòÉ 19. Appendix: Extending the Worplace Shell Toolkit ΓòÉΓòÉΓòÉ
  13061.  
  13062. This section describes, how new functions are to be integrated into the 
  13063. Workplace Shell Toolkit. 
  13064.  
  13065. Note: 
  13066.  
  13067.      Anyone, who extends the Workplace Shell Toolkit, is kindly asked to do so 
  13068.       using the Netlabs Open Source Archive for this project instead of 
  13069.       modifying and redistributing it separately. This way all users of the 
  13070.       Workplace Shell Toolkit benefit directly. 
  13071.  
  13072.      Most important, is has to be made sure that if new source files are being 
  13073.       introduced to the toolkit, they can be compiled with all of the supported 
  13074.       compilers, requiring also the update of both the makefile for the IBM 
  13075.       compilers and the GNUmakefile for the emx compiler. The biggest problem 
  13076.       is that the NMAKE and GNU make work differently at some important points. 
  13077.       While it may be not that difficult to make slight modifications in both 
  13078.       types of makefiles, testing it can be done most effectively by the 
  13079.       project team. 
  13080.  
  13081.      When introducing new functions, anyone wanting to do so is kindly asked 
  13082.       to follow the naming scheme for functions, variables and files, which has 
  13083.       been mostly adopted from the IBM Toolkit for OS/2 WARP 3/4, and the 
  13084.       layout of sourcefiles. This is the only way to make sure that the 
  13085.       Workplace Shell Toolkit will stay to be a consistent piece of software, 
  13086.       presenting a homogeneous API to the user. 
  13087.  
  13088.  Select one of the following topics: 
  13089.  
  13090.      Getting the source from Netlabs 
  13091.      Source Code Notation Conventions 
  13092.      Source File Naming Conventions/Restrictions 
  13093.      Source Code Categories 
  13094.      Adding functions to existing files of the library source 
  13095.         -  Modifying an existing source file 
  13096.         -  Modifying an existing header file 
  13097.         -  Extending an existing sample progam 
  13098.      Adding new files to the library source 
  13099.         -  Create a new source file 
  13100.         -  Create a new header file 
  13101.         -  Extending the makefiles for new source files 
  13102.         -  Create a new sample program 
  13103.      Adding online help comments for new functions 
  13104.  
  13105.  
  13106. ΓòÉΓòÉΓòÉ 19.1. Getting the source from Netlabs ΓòÉΓòÉΓòÉ
  13107.  
  13108. In order to get the up-to-date source code of the Workplace Shell Toolkit, you 
  13109. can access the Netlabs Open Source Archive. For that, you need to use the 
  13110. Concurrent Version System (CVS), and it is recommended to also use the Netlabs 
  13111. Open Source Archive client (NOSAC). 
  13112.  
  13113. With these packages you can donwload the current code, being read up-to-date 
  13114. from the Netlabs CVS server, and, if you would like to join the project team, 
  13115. can later upload bugfixes or extensions to the Workplace Shell Toolkit. 
  13116.  
  13117. See 
  13118.  
  13119.      The Netlabs 
  13120.      The Netlabs Open Source Archive 
  13121.  
  13122.  to get more information about Netlabs, Open Source, the Open Source Archive 
  13123.  and to download the required software. 
  13124.  
  13125.  
  13126. ΓòÉΓòÉΓòÉ 19.2. Source Code Notation Conventions ΓòÉΓòÉΓòÉ
  13127.  
  13128. The following notation conventions are used in the source of the Workplace 
  13129. Shell Toolkit: 
  13130.  
  13131.      All external function names in library sources start with Wtk. 
  13132.  
  13133.      The names of the parameter variables in the prototypes of the functions 
  13134.       (being included in the header files) and the names of the parameter 
  13135.       variables being used in the documentation comments (being part of the C 
  13136.       source) must be identical, otherwise the generation of the online 
  13137.       documentation will report warnings that documentation comments for 
  13138.       certain parameters of certain functions are missing. 
  13139.  
  13140.       This is due to the fact that the script generating the online help file 
  13141.       first scans the header files for prototypes, and then searches the 
  13142.       documentation comments in the source files. 
  13143.  
  13144.       Of course, also the names of the parameter variables used in the library 
  13145.       source should be identical to these being used in the headers and the 
  13146.       online docs 
  13147.  
  13148.      All internal function names start with a double underscore and are to be 
  13149.       marked as static, so that they are not exported. 
  13150.  
  13151.      All type names not being used from the C compiler runtime are written 
  13152.       with uppercase letters only. 
  13153.  
  13154.      All type names not being used from the C compiler runtime and being a 
  13155.       pointer to a type are named with "Pxxxxxxx", where "xxxxxxx" is the data 
  13156.       type being pointed to. 
  13157.  
  13158.      All variable names not being of a type used by the C compiler start with 
  13159.       an abbreviation according to the variable type, just like mostly in the 
  13160.       Toolkit for OS/2 Warp. Here are some examples: 
  13161.  
  13162.       type                example for variable names 
  13163.       BOOL                fVariable 
  13164.       SHORT               sVariable 
  13165.       USHORT              usVariable 
  13166.       LONG                lVariable 
  13167.       ULONG               ulVariable 
  13168.       CHAR                szVariable 
  13169.       PSZ                 pszVariable 
  13170.       PBYTE               pbVariable 
  13171.       PVOID               pvVariable 
  13172.  
  13173.       There are some exceptions (as always) for this rule, where other prefixes 
  13174.       are widely used. 
  13175.  
  13176.         -  If name types and thus resulting prefixes are very long, sometimes 
  13177.            shorter prefixes are being used. For example, when coding for 
  13178.            extended attributes, a pointer of type PFEA2LIST is mostly prefixed 
  13179.            with pfea2l. Also when using structures of DATETIME, very often the 
  13180.            variable or the prefix dt is used. 
  13181.         -  For types of the C compiler runtime, there also may be widely used 
  13182.            abbreviations that can also be used instead of the full type name. 
  13183.  
  13184.      Al include files shall follow the same layout. See the layout of existing 
  13185.       header files in the include directory. 
  13186.  
  13187.      In header files of the library, C++ comments (double slash) must not be 
  13188.       used. Although all makefiles of the toolkit use compiler flags allowing 
  13189.       such comments, the library headers should also be useable with programs, 
  13190.       where the programmes do not want to allow them. 
  13191.  
  13192.  
  13193. ΓòÉΓòÉΓòÉ 19.3. Source File Naming Conventions/Restrictions ΓòÉΓòÉΓòÉ
  13194.  
  13195. The intention of the Workplace Shell Toolkit is (with only few exceptions) to 
  13196. obey the 8.3 notation for all files in such a manner that a compiled version of 
  13197. the library can be installed on a FAT-formatted drive. 
  13198.  
  13199. For the IBM compilers, it is intended also be possible to compile the sample 
  13200. programs on that FAT drive. Note that this is not possible for the emx compiler 
  13201. using GNU make, because the makefiles for this are named GNUmake. As a 
  13202. workaround, one could unpack all files called GNUmakefile an a HPFS drive and 
  13203. copy them over the files called makefile on the FAT drive. This of course would 
  13204. lead to not being able to use the IBM compilers and NMAKE anymore with this 
  13205. installation. 
  13206.  
  13207. The 8.3 notation is to be obeyed within the following directories: 
  13208.  
  13209.  bin              containing the REXX scripts for supporting the make process 
  13210.  
  13211.  book             containing the resulting online documentation files 
  13212.  
  13213.  config           containing the configuration and help files for the make 
  13214.                   process 
  13215.  
  13216.  include          containing the header files of the library 
  13217.  
  13218.  bin              containing the resulting library file(s) with a binary 
  13219.                   distribution 
  13220.  
  13221.  samples          containing the sample programs. The only files being allowed 
  13222.                   not to comply to the 8.3 scheme are the files called 
  13223.                   GNUmakefile. 
  13224.  
  13225.  ship             containing some files being required to build a binary 
  13226.                   distribution 
  13227.  
  13228.  source\lib       containing the source files 
  13229.                   Despite of the fact that the source directory would not be 
  13230.                   shipped with a binary distribution, all .c files must be 
  13231.                   named exactly like the header files (and thus obey the 8.3 
  13232.                   scheme) in order not to break the build of the online help. 
  13233.  
  13234.  The following directories may contain filenames not containing 8.3 compliant 
  13235.  names, as they are only required to build the library and online doc files, 
  13236.  and not being shipped with a binary distribution: 
  13237.  
  13238.  compile          containing the intermediate files for compiling the library 
  13239.                   and samples 
  13240.  
  13241.                   The subdirectory gcc contains files of the toolkit adapted to 
  13242.                   the GNU compiler. 
  13243.  
  13244.  ipf              containing the intermediate files for compiling the docs 
  13245.  
  13246.  source\book      containing the source files 
  13247.  
  13248.  
  13249. ΓòÉΓòÉΓòÉ 19.4. Source Code Categories ΓòÉΓòÉΓòÉ
  13250.  
  13251. Two types of source code categories exist within the Workplace Shell Toolkit: 
  13252.  
  13253.  minor     This category is for the so called little helper or utility 
  13254.            functions. 
  13255.            The following applies to functions falling into a minor category: 
  13256.  
  13257.                the name of the source and the include file for that category 
  13258.                 starts with wtku, leaving four more characters for distincting 
  13259.                 between this and other files of a minor category. 
  13260.                the include file for such category has to be included by wtku.h 
  13261.                the include symbol for such category has to start with 
  13262.                 INCL_WTKUTL 
  13263.                the included symbol for such category has to be 
  13264.                 WTKUTLxxxxxx_INCLUDED and defines the text being used in the 
  13265.                 online help within the functions overview page. This text must 
  13266.                 include the term "helper functions" in order to distinct 
  13267.                 between minor and major categories. The text being defined by 
  13268.                 this symbol is being used as a headline for the category within 
  13269.                 the Workplace Shell Toolkit Functions Overview. 
  13270.  
  13271.  major     This category is for the so called major APIs, each consisting of a 
  13272.            lot of related functions being desinged to support a special task. 
  13273.            The following applies to functions falling into a major category: 
  13274.  
  13275.                the name of the source and the include file for that category 
  13276.                 starts with wtk, leaving five more characters for distincting 
  13277.                 between this and other files of a minor category. 
  13278.                the include file for such category has to be included at the 
  13279.                 end of wtk.h 
  13280.                the include symbol for such category has to start with INCL_WTK 
  13281.                the included symbol for such category has to be 
  13282.                 WTKxxxxxx_INCLUDED and defines the text being used in the 
  13283.                 online help within the functions overview page. This text must 
  13284.                 NOT include the term "helper functions" in order to distinct 
  13285.                 between minor and major categories. The text being defined by 
  13286.                 this symbol is being used as a headline for the category within 
  13287.                 the Workplace Shell Toolkit Functions Overview. 
  13288.  
  13289.  
  13290. ΓòÉΓòÉΓòÉ 19.5. Adding functions to existing files of the library source ΓòÉΓòÉΓòÉ
  13291.  
  13292. The following applies, if you want to add new functions to existing source 
  13293. files of the the Workplace Shell Toolkit: 
  13294.  
  13295.      determine, wether your functions fall into an existing category. If you 
  13296.       have to only add a few functions, they possibly fall into an existing 
  13297.       category. If you add some more to a lot of functions, they very likely 
  13298.       require a new category, and it might be useful to introduce a new major 
  13299.       category. 
  13300.       If they fall into a category that already exists, read further here. If 
  13301.       they fall into a non-existing category, see 
  13302.  
  13303.            Adding new files to the library source 
  13304.  
  13305.      Please read, (and mostly obey) the Source Code Notation Conventions. 
  13306.  
  13307.      Please make sure that new functions do not interfere with existing ones. 
  13308.       A good way to ensure this is to ask the project team ! 
  13309.  
  13310.      If your new function(s) make sense to be part of an already existing 
  13311.       category, add your function to an existing source file. If you are not 
  13312.       sure about wether this is the case, or wether you should open a new 
  13313.       category, ask the project team ! More, you should extend the sample 
  13314.       program for that category in order to let your new function(s) be 
  13315.       automatically tested. 
  13316.  
  13317.      Last, but not least, you should well add documentation comments to the 
  13318.       source files, so that the online help can be generated properly. The make 
  13319.       process for the online help will generate warnings for each function or 
  13320.       parameter of a function, for that no documentation comment exists. 
  13321.  
  13322.  
  13323. ΓòÉΓòÉΓòÉ 19.5.1. Modifying an existing source file ΓòÉΓòÉΓòÉ
  13324.  
  13325. If you add a single function or only a few functions, which fall into an 
  13326. existing source code category, adding a new function is fairly easy. In order 
  13327. to have fairly the same layout, it is recommended to copy an existing function 
  13328. and modify it. Please make sure that you also modify the documentation 
  13329. comments. 
  13330.  
  13331. In most cases it makes sense to not just append the new function(s) at the end 
  13332. of the source file, but rather place it beneath certain existing functions in 
  13333. order to group functions, where they serve the same task or belong together in 
  13334. any other sense. In general, the functions shall be placed in the same order as 
  13335. their prototypes in the header file corresponding to the source file. 
  13336.  
  13337. You also have to add the function prototype to the header file corresponding to 
  13338. the source file that you have added your new function(s) to. 
  13339.  
  13340. If your code required new internal datatypes, thus only be used by your code, 
  13341. place them before the first (helper) function. Only datatypes and structures 
  13342. being used by the caller of your code are to be placed in the header file 
  13343. corresponding to the source file. 
  13344. See source\lib\wtkset.c as an example for a source file introducing datatypes 
  13345. being used internally. 
  13346.  
  13347. See also 
  13348.  
  13349.       Source Code Notation Conventions 
  13350.  
  13351.  
  13352. ΓòÉΓòÉΓòÉ 19.5.2. Modifying an existing header file ΓòÉΓòÉΓòÉ
  13353.  
  13354. If you add a single function or only a few functions, which fall into an 
  13355. existing source code category, add the prototype(s) of the new function(s) to 
  13356. the header file. 
  13357.  
  13358. If you need to introduce new datataypes that are being used by the caller of 
  13359. your code, place them before the first prototype. 
  13360. See include\wtkset.h as an example for a header file introducing datatypes 
  13361. being used by the caller of an API. 
  13362.  
  13363. In most cases it makes sense to not just append the prototype(s) of the new 
  13364. function(s) at the end of the header file, but rather place it beneath certain 
  13365. existing functions in order to group functions, where they serve the same task 
  13366. or belong together in any other sense. In general, the prototypes of the 
  13367. functions shall be placed in the same order as their code appears in the code 
  13368. file corresponding to the header file. 
  13369.  
  13370. See also 
  13371.  
  13372.       Source Code Notation Conventions 
  13373.  
  13374.  
  13375. ΓòÉΓòÉΓòÉ 19.5.3. Extending an existing sample progam ΓòÉΓòÉΓòÉ
  13376.  
  13377. If you add a single function, or only a few functions, which fall into an 
  13378. existing source code category, extend the sample program for that category in 
  13379. order to let your new function(s) be automatically tested. 
  13380.  
  13381. See the existing sample programs in the subdirectory samples as examples. 
  13382.  
  13383. At least some code should be added that tests, wether the code works ok. With 
  13384. some APIs, it is also important to test, wether the API fails under a certain 
  13385. condition. 
  13386.  
  13387. VIO sample programs should always return zero, if all works well, because 
  13388. otherwise a make run from the top level makefile would also break out because 
  13389. of the non-zero return code. This breaks the method of testing all VIO sample 
  13390. programs with one make call. 
  13391. So if an API is expected to fail, set rc to NO_ERROR to ignore the error. 
  13392.  
  13393. Workplace Shell sample programs are not being installed with make run. The user 
  13394. has to (de)install them with 
  13395.  
  13396.       make (de)install 
  13397.  
  13398.  See the make file of the WPS sample program in the subdirectory 
  13399.  samples\settings\wps as an example. 
  13400.  
  13401.  
  13402. ΓòÉΓòÉΓòÉ 19.6. Adding new files to the library source ΓòÉΓòÉΓòÉ
  13403.  
  13404. The following applies, if you want to add new functions to the Workplace Shell 
  13405. Toolkit, where you are required to add new source files to the library : 
  13406.  
  13407.      determine, wether your functions fall into an existing category. If they 
  13408.       fall into a category that do not already exists, read further here. If 
  13409.       they fall into an existing category, see 
  13410.  
  13411.            Adding functions to existing files of the library source 
  13412.  
  13413.      When creating a new category, determine the type of category that should 
  13414.       be created. 
  13415.       If you have to only add a few functions, they should possibly form a 
  13416.       minor category. If you add some more to a lot of functions, it might make 
  13417.       more sense to open a major category. A good way to be sure of that is to 
  13418.       ask the project team ! 
  13419.  
  13420.      Please read, (and mostly obey) the Source Code Notation Conventions. 
  13421.  
  13422.      Please make sure that new functions do not interfere with existing ones. 
  13423.       A good way to ensure this is to ask the project team ! 
  13424.  
  13425.      Opening a new category requires to add completely new files to the 
  13426.       Workplace Shell Toolkit. This most likely will also require you to add a 
  13427.       completely new sample program in order to let your new function(s) be 
  13428.       automatically tested. 
  13429.  
  13430.      Last, but not least, you should well add documentation comments to the 
  13431.       source files, so that the online help can be generated properly. The make 
  13432.       process for the online help will generate warnings for each function or 
  13433.       parameter of a function, for that no documentation comment exists. 
  13434.  
  13435.  
  13436. ΓòÉΓòÉΓòÉ 19.6.1. Create a new source file ΓòÉΓòÉΓòÉ
  13437.  
  13438. If you introduce a new source code category, this requires to add a completely 
  13439. new source file to the Workplace Shell Toolkit. 
  13440.  
  13441. In order to have fairly the same layout, it is recommended to copy an existing 
  13442. source file, remore all functions out of it, modify the comments and includes 
  13443. and then add the code of your functions to them. Please make sure that you also 
  13444. add documentation comments, when you are done. 
  13445.  
  13446. Building a toolkit for others to use, it is very important to think about how 
  13447. the function prototypes could look like, before you actually code it, so it is 
  13448. mostly a good strategy to also create the new header file before actually start 
  13449. the coding. 
  13450.  
  13451. Please also try to make the API look and feel like a "normal" OS/2 API. Surely 
  13452. not all of the OS/2 APIs are well designed, but it also would be a bad thing, 
  13453. if the API of the Workplace Shell Toolkit would be too different from them. 
  13454.  
  13455. See also 
  13456.  
  13457.       Source Code Notation Conventions 
  13458.  
  13459.  
  13460. ΓòÉΓòÉΓòÉ 19.6.2. Create a new header file ΓòÉΓòÉΓòÉ
  13461.  
  13462. If you introduce a new source code category, this requires to add a completely 
  13463. new header file to the Workplace Shell Toolkit. 
  13464.  
  13465. In order to have fairly the same layout, it is recommended to copy an existing 
  13466. header file, remore all prototypes out of it, modify the comments, include and 
  13467. included symbol definitions (very important !!!!) and then add the prototypes 
  13468. of your functions to them. 
  13469.  
  13470. Building a toolkit for others to use, it is very important to think about how 
  13471. the function prototypes could look like, before you actually code it. 
  13472.  
  13473. Please also try to make the API look and feel like a "normal" OS/2 API. Surely 
  13474. not all of the OS/2 APIs are well designed, but it also would be a bad thing, 
  13475. if the API of the Workplace Shell Toolkit would be too different from it. 
  13476.  
  13477. See also 
  13478.  
  13479.       Source Code Notation Conventions 
  13480.  
  13481.  
  13482. ΓòÉΓòÉΓòÉ 19.6.3. Extending the makefiles for new source files ΓòÉΓòÉΓòÉ
  13483.  
  13484. If you introduce a new source code category, this requires to extend the 
  13485. makefiles, so that your new source module is being compiled and being placed 
  13486. into the library of the Workplace Shell Toolkit. 
  13487.  
  13488. For that, you have to add the following to both the makefile and the 
  13489. GNUmakefile: 
  13490.  
  13491.      add the object module to the macro OBJS 
  13492.      add a dependency for your object module, so that it is recompiled, if the 
  13493.       header file changes 
  13494.  
  13495.  Note: 
  13496.  
  13497.      Do not edit the GNUmakefile with an editor that replaces tabs with blanks 
  13498.       (like TEDIT), as GNU make requires commands within rules to be preceeded 
  13499.       by at least one tab. 
  13500.      within a makefile, the object module and header file needs to be 
  13501.       prepended with the path, where the file has to be written or read. For 
  13502.       this, use the macros already being used for existing entries. 
  13503.      within a GNUmakefile, the object module and header file MUST NOT be 
  13504.       prepended with any path. Also here see the existing entries and add the 
  13505.       new entry according to these. 
  13506.  
  13507.  Of course it makes sense to test with all supported compilers, wether the 
  13508.  library is being properly compiled, including your new module. If you do not 
  13509.  have all supported compilers available, ask the project team to help you. 
  13510.  
  13511.  
  13512. ΓòÉΓòÉΓòÉ 19.6.4. Create a new sample program ΓòÉΓòÉΓòÉ
  13513.  
  13514. When opening a new source category you are required to create a new sample 
  13515. program that tests your new function(s) automatically. For this, a sample 
  13516. program should call all of your functions at least once (and do somethimg 
  13517. senseful, of course). The following topics are important, when creating a new 
  13518. sample program: 
  13519.  
  13520.  
  13521. Creating a VIO sample program 
  13522.  
  13523. For all categories, at least a VIO sample program should be created. If some of 
  13524. your APIs cannot be executed outside a SOM environment like for the settings 
  13525. manager API, the VIO sample programm can leave them out. A good way to be able 
  13526. to test at least some of the functions is to use dummy pointers instead of real 
  13527. SOM self pointers, where possible. For this the library code should not call 
  13528. real SOM APIs in DEBUG mode, where possible. See macro OBJECTVALID() in 
  13529. source\lib\wtkset.c as an example how to avoid calling SOM methods in DEBUG 
  13530. mode. 
  13531.  
  13532. VIO sample programs should always return zero, if all works well, because 
  13533. otherwise a make run from the top level makefile would also break out because 
  13534. of the non-zero return code. This breaks the method of testing all VIO sample 
  13535. programs with one make call. 
  13536. So if an API is expected to fail, set rc to NO_ERROR to ignore the error. 
  13537.  
  13538.  
  13539. Creating a sample Workplace Shell Class 
  13540.  
  13541. For testing certain APIs, it cannot be avoided to code real SOM/Workplace Shell 
  13542. classes. See the WPS sample for the settings manager in the directory 
  13543. samples\settings\wps as an example. 
  13544.  
  13545.  
  13546. Calling all functions of a category 
  13547.  
  13548. If a function itself calls several functions of the same category at a time, 
  13549. for testing purposes a call to this function is sufficient to regard also the 
  13550. called functions as tested (Example: WtkGetNextEaValue calling WtkReadEa, 
  13551. WtkFindFirstEaValue, WtkFindNextEaValue and WtkCloseEa). Nevertheless it might 
  13552. still make sense to implement also calls to the indirectly tested functions in 
  13553. order to provide also a code sample to the users of the library. 
  13554.  
  13555.  
  13556. Choosing a name for the program 
  13557.  
  13558. Each sample program has a subdirectory below samples. The name has to be unique 
  13559. among the samples, because all sample program executables are being created in 
  13560. the same subdirectory of compile. 
  13561. Therefore most sample programs and their directory are named as follows: 
  13562.  
  13563.      create a directory below samples with a name with up to seven characters 
  13564.      if you create both a vio and a WPS sample, create the subdirectories vio 
  13565.       and wps in that directory, otherwise use the directory itself for the vio 
  13566.       sample. 
  13567.      create at least 
  13568.         -  a source file named like the directory. For VIO samples, the name 
  13569.            has to be preceeded by an underscore. This will prevent to name 
  13570.            sample programs like existing OS/2 commands etc.. For WPS samples, 
  13571.            this does not apply, and you will call the main source files and 
  13572.            thus the WPS DLL anything line xxxcls.*. Also for such DLLs make 
  13573.            sure that the name is unique among all WPS class samples. Other 
  13574.            files being generated like resource files have also to be named 
  13575.            uniquely among all WPS samples. It is good practise to name all 
  13576.            generated files with the name of the testclass source file in order 
  13577.            to avoid any name problems. 
  13578.         -  a readme file named readme.1st, containing informations about the 
  13579.            sample program. Take a readme.1st of an existing sample program as a 
  13580.            template. 
  13581.         -  a makefile containing the rules and macros for use with NMAKE and 
  13582.            the IBM compilers. Take a makefile of an existing sample program as 
  13583.            a template. 
  13584.         -  a GNUmakefile containing the rules and macros for use with GNU make 
  13585.            and the emx compiler. Take a GNUmakefile of an existing sample 
  13586.            program as a template. 
  13587.  
  13588.  
  13589.  Things to care for when creating makefiles 
  13590.  
  13591.  As VIO sample programs are rather small, they mostly consist only of a single 
  13592.  C source file. So when taking the makefiles of an existing sample as a 
  13593.  template, you mostly have only to modify 
  13594.  
  13595.      the top comment line 
  13596.      the value of the macro DESCRIPTION 
  13597.      the value of the macro STEM 
  13598.  Of course the top comment line and the description of the makefile should have 
  13599.  an equivalent content, like in the existing samples. 
  13600.  
  13601.  In case of a WPS sample, things are much more complicated. Very important is 
  13602.  for example that the .c file being maintained by the SOM compiler is written 
  13603.  in the sample source directory, but all headers and module definition files in 
  13604.  the compile directory. Make sure to use the appropriate inference rules in 
  13605.  both makefiles. 
  13606.  
  13607.  It is recommended to use the existing WPS sample for the settings and details 
  13608.  manager in the samples\settings\wps directory as a template. 
  13609.  
  13610.  Note: 
  13611.  
  13612.      Do not edit the GNUmakefile with an editor that replaces tabs with blanks 
  13613.       (like TEDIT), as GNU make requires commands within rules to be preceeded 
  13614.       by at least one tab. 
  13615.  
  13616.  
  13617.  pseudotargets to be supported by makefiles of sample programs 
  13618.  
  13619.  VIO sample programs should at least support the following make pseudotargets: 
  13620.  
  13621.  all            create the sample program 
  13622.  run            run the sample program. Note that executables are not being 
  13623.                 created in the sample source directory, but below the compile 
  13624.                 subdirectory, so this is an easy way to call the program. 
  13625.  debug          load the sample program into the debugger. Note that this is 
  13626.                 not possible for emx compiled programs (yet?). 
  13627.  clean          delete all files being created by the makefile while compiling 
  13628.                 the sample program 
  13629.  
  13630.  Note: 
  13631.  
  13632.      Currently, some samples take a directory pathname as an argument in order 
  13633.       to there create temporary files and/or directories. Make sure that your 
  13634.       sample program receives the correct parameters when called by the 
  13635.       commands of the run and debug pseudotargets. 
  13636.  
  13637.  WPS sample classes should at least support the following make pseudotargets: 
  13638.  
  13639.  all            create the WPS sample class 
  13640.  install        register the sample class and optionally create an instance of 
  13641.                 the object class for testing purposes 
  13642.  deinstall      deregister the sample class 
  13643.  
  13644.  Note: 
  13645.  
  13646.      while the run and debug are not to be supported by the makefiles of a WPS 
  13647.       sample class, these targets should exist anyway and display a warning 
  13648.       message. 
  13649.  
  13650.  
  13651.  Add the sample to the top level makefiles 
  13652.  
  13653.  In order to enable the top level makefiles to build the new sample program, 
  13654.  extend the following parts both in makefile and GNUmakefile in the top level 
  13655.  directory: 
  13656.  
  13657.  add a new pseudo target for your sample program 
  13658.            take an existing pseudotarget as an example and modify the name and 
  13659.            the subdirectory within the commands. 
  13660.  
  13661.            Please place the new pseudotarget at the end of the appropriate 
  13662.            section: 
  13663.            VIO sample section 
  13664.                           only a VIO sample program exists for the source 
  13665.                           category 
  13666.            VIO and SOM sample section 
  13667.                           both a VIO and a SOM sample program exists for the 
  13668.                           source category 
  13669.            SOM sample section 
  13670.                           only a SOM sample program exists for the source 
  13671.                           category 
  13672.  
  13673.  
  13674.  macro ALL_SAMPLES 
  13675.            add the new pseudotarget to the list of pseudotargets for all 
  13676.            samples 
  13677.  macro VIO_SAMPLES 
  13678.            add the new pseudotarget to the list of pseudotargets for VIO 
  13679.            samples, if you add a VIO sample 
  13680.  macro SOM_SAMPLES 
  13681.            add the new pseudotarget to the list of pseudotargets for SOM 
  13682.            samples, if you add a SOM sample 
  13683.  
  13684.  
  13685. ΓòÉΓòÉΓòÉ 19.7. Adding online help comments for new functions ΓòÉΓòÉΓòÉ
  13686.  
  13687. After having added functions to the Toolkit for OS/2 Warp, you have to add 
  13688. documentation comments to the source file.  To do so, you add the follwoing 
  13689. before the function: 
  13690.  
  13691.      a C comment start 
  13692.  
  13693.            /* 
  13694.  
  13695.      a start tag line for the syntax comment of the function 
  13696.  
  13697.            @@functionname@SYNTAX 
  13698.  
  13699.       Following to that line, you enter the text explaining the syntax in IPF 
  13700.       style. This text should be as short and general as possible. 
  13701.  
  13702.       In order to have a consistent look and feel of the online documentation, 
  13703.       please do not use any IPF tags for the syntax explanation that modify the 
  13704.       text style (as highlighting, changing colors etc.). 
  13705.  
  13706.      for each parameter of the function a start tag line for the parameter 
  13707.  
  13708.            @@functionname@PARM@parametername@type 
  13709.  
  13710.       As type, please specify either in, out or inout. 
  13711.  
  13712.       Following to that line, you enter one (!) line for a brief comment. This 
  13713.       line is not meant to take only one line in the source file, but rather be 
  13714.       one line in terms of IPF source. This first IPF line is shown as a 
  13715.       comment in the syntax section for the function. Terminate that first IPF 
  13716.       line by a parameter break (:p.) on the first column of the line following 
  13717.       the text of this line. 
  13718.  
  13719.       Following to that first IPF line you can add more lines in order to give 
  13720.       further explanations about the parameter. 
  13721.  
  13722.       See existing documentation comments for similar variables as examples !!! 
  13723.  
  13724.      a start tag line for the return value of the function 
  13725.  
  13726.            @@functionname@RETURN 
  13727.  
  13728.       Following to that line, you enter one (!) IPF line for a brief comment. 
  13729.       (see explanation above). 
  13730.  
  13731.       Following to that first IPF line you can add more lines in order to give 
  13732.       further explanations about the parameter. 
  13733.  
  13734.       See existing documentation comments for similar return values as examples 
  13735.       !!! 
  13736.  
  13737.      a start tag line for the remarks for the function 
  13738.  
  13739.            @@functionname@REMARKS 
  13740.  
  13741.       Add IPF text to further describe the function. 
  13742.  
  13743.      a end tag line 
  13744.  
  13745.            @@ 
  13746.  
  13747.      a C comment end 
  13748.  
  13749.            */ 
  13750.  
  13751.  After having added all that for all the functions, that you added to the 
  13752.  Toolkit for OS/2 Warp, (re)build the library documentation in order to check, 
  13753.  wether your comments have properly been included. 
  13754.