home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / common.zip / COMMON.INF (.txt) < prev   
OS/2 Help File  |  1995-02-08  |  145KB  |  6,716 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Licensing agreement ΓòÉΓòÉΓòÉ
  3.  
  4. The term LICENSE is used to refer to the ASCII file containing a copy of this 
  5. license.  The term PACKAGE here is used to refer to the header files, the 
  6. libraries, the documentation, and LICENSE. The term AUTHOR is used to refer to 
  7. the developer of PACKAGE. 
  8.  
  9. PACKAGE is copyrighted (c) 1993-1995 by its AUTHOR, Lawrence W. Salomon, Jr. 
  10. and is the sole property of AUTHOR. 
  11.  
  12. You are hereby granted a license to use PACKAGE in your applications and freely 
  13. distribute PACKAGE if and only if the following condition(s) are met: 
  14.  
  15. o All files in PACKAGE are included in the distributed files and remain in 
  16.   their original form. 
  17.  
  18. o If the contents of the PACKAGE are distributed using any of the file 
  19.   compression programs available (PKZIP, ZIP, ZOO, etc.), LICENSE must not be 
  20.   included in the compressed file but instead must remain separate. 
  21.  
  22. By using any component or any part of any component of PACKAGE, you are 
  23. indicating that you agree to and are thereby bound to the terms of this 
  24. license. 
  25.  
  26.  
  27. ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ
  28.  
  29. Do you ever find yourself writing a new program and wishing that you already 
  30. had a routine to parse the command line?  Or how about a routine that performs 
  31. signal processing?  Or maybe a set of linked list functions?  Often times, I 
  32. have often been in this very situation, writing new code then discovering that 
  33. I have need of routines that should be fairly common. 
  34.  
  35. Instead of simply writing the routines for each application that required them, 
  36. I started maintaining my own software library of commonly used routines, which 
  37. you have here.  These routines provide easy access to a host of functions that 
  38. you used to have to write yourself. 
  39.  
  40. The functions are separated into groups, listed below: 
  41.  
  42. o Common routines 
  43. o Buffer routines 
  44. o Communication routines 
  45. o Debugging routines 
  46. o File routines 
  47. o Link-list routines 
  48. o Memory allocation routines 
  49. o Object handling routines 
  50. o Set routines 
  51. o Signal routines 
  52. o Sprite routines 
  53. o String routines 
  54. o Screen I/O routines 
  55. o Windowing routines 
  56.  
  57. Additionally, the following topics are also available: 
  58.  
  59. o Licensing agreement 
  60. o Using Common/2 in your applications 
  61. o About errors, bugs, and suggestions 
  62. o What's New in this Release 
  63.  
  64. A couple of notes are needed: 
  65.  
  66. o As you use Common/2, you may notice that the library seems to have been built 
  67.   out of "spare parts", because there is lacking a tight level of integration. 
  68.   This is true, and I hope to resolve this in the near future by taking such 
  69.   steps as having each function return an error code (like the kernel APIs), 
  70.   and combining the error codes (instead of having a group for the memory 
  71.   routines, another group for the object routines, etc.).  If you have any 
  72.   suggestions on how the library can be made to fit together better, I would be 
  73.   most interested in hearing them. 
  74.  
  75.  
  76. ΓòÉΓòÉΓòÉ 2.1. Using Common/2 in your applications ΓòÉΓòÉΓòÉ
  77.  
  78. Common/2 was compiled using IBM's C-Set++ compiler; compatibility with other 
  79. 32-bit compilers has not been tested.  It does require you to have the 
  80. Programmer's Toolkit installed on your machine or its functional equivalent, 
  81. however.  You should place the files common.h and cmndefs.h in a directory 
  82. specified by the INCLUDE environment variable.  Additionally, you should place 
  83. the .LIB files in a directory specified by the LIB environment variable and the 
  84. .DLL files in a directory specified by the LIBPATH environment variable. 
  85.  
  86. Note that <os2.h> must be included before including <common.h>.  Do not 
  87. explicitly include <cmndefs.h> because it is included by <common.h>.  As with 
  88. <os2.h>, before including <common.h> you should define the appropriate 
  89. constants to indicate which portions of the library you would like to use: 
  90.  
  91. INCL_CMNBUF         Buffer routines (CmnBuf) 
  92.  
  93. INCL_CMNCOM         Communication routines (CmnCom) 
  94.  
  95. INCL_CMNDBG         Debugging routines (CmnDbg) 
  96.  
  97. INCL_CMNFIL         File routines (CmnFil) 
  98.  
  99. INCL_CMNLST         Linked list routines (CmnLst) 
  100.  
  101. INCL_CMNMEM         Memory routines (CmnMem) 
  102.  
  103. INCL_CMNOBJ         Object routines (CmnObj) 
  104.  
  105. INCL_CMNSET         Set routines (CmnSet) 
  106.  
  107. INCL_CMNSIG         Signal routines (CmnSig) 
  108.  
  109. INCL_CMNSPR         Sprite routines (CmnSpr) 
  110.  
  111. INCL_CMNSTR         String routines (CmnStr) 
  112.  
  113. INCL_CMNVIO         VIO routines (CmnVio) 
  114.  
  115. INCL_CMNWIN         Window routines (CmnWin) 
  116.  
  117. INCL_COMMONALL      All sections 
  118.  
  119. The general purpose routines (those that begin with Cmn only) are always 
  120. included regardless of the constants defined. 
  121.  
  122. Obtaining the Source 
  123.  
  124. While the runtime has been placed on various networks and may be distributed 
  125. free-of-charge, the source to Common/2 has not been made public. If you are 
  126. interested in licensing the entire source or just a module or two for your 
  127. company, please contact the author. 
  128.  
  129.  
  130. ΓòÉΓòÉΓòÉ 2.2. About errors, bugs, and suggestions ΓòÉΓòÉΓòÉ
  131.  
  132. Often, when something doesn't quite work correctly, it is because the wrong 
  133. handle was passed to the function which returned the unexpected result. Before 
  134. crying "wolf", you should first call CmnQueryHandle to insure that you are 
  135. giving the function what it expects. 
  136.  
  137. If that still doesn't help, if you have some suggestions, if you have a set of 
  138. routines that you would like to donate to the library, or if you would like to 
  139. translate the programming reference and header files into other languages, feel 
  140. free to send me mail via the Internet.  My address is "os2man@panix.com".  If 
  141. you are describing what you think is a bug, please describe the steps needed to 
  142. recreate the problem and include code when possible. 
  143.  
  144.  
  145. ΓòÉΓòÉΓòÉ 2.3. What's New in this Release ΓòÉΓòÉΓòÉ
  146.  
  147. Changes resulting in release 1.7.0 include: 
  148.  
  149. o The typedefs PFNRECCOMP, PFNRECFUNC, PFNRECMED, PFNCMDARG, and PFNCMDERR were 
  150.   all changed so that the last parameter in each is a PVOID which is passed in 
  151.   to the function that uses these types.  The functions affected are listed 
  152.   below: 
  153.  
  154.    - CmnLstAddRecord 
  155.    - CmnLstAddUniqueRecord 
  156.    - CmnLstCopyList 
  157.    - CmnLstPruneList 
  158.    - CmnLstQuickSortList 
  159.    - CmnLstSearchRecord 
  160.    - CmnLstSortList 
  161.    - CmnLstTraverseList 
  162.    - CmnStrParseCommandLine 
  163.  
  164.   These functions accept the new parameter - pvData - at the end of their 
  165.   parameter list. 
  166.  
  167.   While I realize that this affects many people, I feel that the change is 
  168.   necessary, since the only way to communicate with the callbacks previously 
  169.   was through global variables.  These changes will allow any additional data 
  170.   that is needed by the callbacks to be passed in as a pointer to a (local) 
  171.   structure.  I extend my most sincere apologies for the effect that these 
  172.   changes will have; the changes affect me just as severely. 
  173.  
  174. Changes resulting in release 1.6.1 include: 
  175.  
  176. o The function CmnFilInstallDiskette was added. 
  177.  
  178. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 
  179.  
  180. Changes resulting in release 1.6.0 include: 
  181.  
  182. o The license was modified to allow the use of Common/2 in commercial 
  183.   applications. 
  184.  
  185. o Added #define's to avoid problems with case-sensitivity during linking. 
  186.  
  187. o Added code to properly draw overlaying sprites. 
  188.  
  189. o The functions CmnSprSetLayering() and CmnSprQueryLayering() were added to 
  190.   manipulate the layer of a sprite in the z-order. 
  191.  
  192. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 
  193.  
  194. Changes resulting in release 1.5.0 include: 
  195.  
  196. o The CmnBuf routines were added. 
  197.  
  198. o The functions CmnFilCopyDiskette() and CmnFilFormatDiskette() were added. 
  199.  
  200. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 
  201.  
  202. Changes resulting in release 1.4.0 include: 
  203.  
  204. o The library was moved from a .LIB to a .DLL in hopes of someday writing Rexx 
  205.   interfaces for some or all of the routines.  This impacted a number of 
  206.   things: 
  207.  
  208.    - The CmnVio routines, since CmnVioLoadMessage() assumes that messages will 
  209.      be bound (with MSGBIND) to the DLL and not the EXE file; if an EXE uses 
  210.      MSGBIND to bind its messages to itself, CmnVioLoadMessage() (and thus 
  211.      CmnVioDisplayMessage(), since it is dependent on the former) would return 
  212.      an error. 
  213.  
  214.    - If you write an application that uses non of the PM-dependent routines 
  215.      (CmnSpr and CmnWin), and tried to run the application in a non-PM 
  216.      environment (e.g. booting from the installation diskettes), OS/2 would 
  217.      return an error since, by virtue of the fact that your application is 
  218.      linked to the DLL, PM is required.  To alleviate this problem, the DLLs 
  219.      have multiplied from two to four, and a naming convention was established 
  220.      to allow for this. 
  221.  
  222.      The format of the DLL and LIB file names is CMN32te. "t" is the "threaded" 
  223.      option and can be S for single-threaded or M for multi-threaded.  "e" is 
  224.      the "environment" option and can be V for routines that do not require PM 
  225.      (VIO), or P for routines that do require PM. 
  226.  
  227. o 16-bit support was removed.  This was due to the fact that we're in the 
  228.   second release of a 32-bit OS/2, so 16-bit seemed rather redundant.  The code 
  229.   for all existing functions is still there, but no new development will make 
  230.   provisions for 16-bit compatibility, nor will the 16-bit version of the 
  231.   library be released in this package.  Should you need this, contact me via 
  232.   email. 
  233.  
  234. o The constant INCL_CMNLIB was renamed to INCL_COMMONALL, in the (admittedly 
  235.   unlikely) event that a CmnLib subsystem is added. 
  236.  
  237. o The constant SPL_ERROR was renamed to SPL_ERR_ERROR to avoid conflicts with 
  238.   the constant of the same name in <pmspl.h>. 
  239.  
  240. o Minor bugs with the CmnCom subsystem were fixed. 
  241.  
  242. o A minor bug with the CmnFilSearchFiles() function was fixed. 
  243.  
  244. o A minor bug with the CmnMemFreeMem() was fixed. 
  245.  
  246. o The CmnFilSplitFilename() function was added. 
  247.  
  248. o The CmnWinSavePosToBuffer() and CmnWinRestorePosFromBuffer() functions were 
  249.   added and the CmnWinSavePosition() and CmnWinRestorePosition() functions were 
  250.   modified to utilize these new functions. 
  251.  
  252. o The functions CmnStrPadString() and CmnStrStripSpace() were added. 
  253.  
  254. o The function CmnVioGetString() has been added. 
  255.  
  256. o The sprite subsystem (INCL_CMNSPR) was added. 
  257.  
  258. o All function pointer typedefs were modified to include the EXPENTRY attribute 
  259.   to allow for non-IBM compilers. 
  260.  
  261. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 
  262.  
  263. Changes resulting in releases prior to 1.4.0 were not documented. 
  264.  
  265.  
  266. ΓòÉΓòÉΓòÉ 3. Common routines ΓòÉΓòÉΓòÉ
  267.  
  268. The purpose of this group is to provide functions which apply to all of the 
  269. function groups.  Listed below are the functions which comprise this group: 
  270.  
  271. o CmnQueryHandle 
  272. o CmnQueryHandleInfo 
  273. o CmnQueryVersion 
  274. o CmnSetHandleInfo 
  275.  
  276.  
  277. ΓòÉΓòÉΓòÉ 3.1. CmnQueryHandle ΓòÉΓòÉΓòÉ
  278.  
  279. CmnQueryHandle 
  280.  
  281. Purpose 
  282.  
  283. This function returns the type of the specified handle. 
  284.  
  285. Syntax 
  286.  
  287. (USHORT)CmnQueryHandle(lhHandle);
  288.  
  289. Parameters 
  290.  
  291. lhHandle (LHANDLE) - specifies the handle to query. 
  292.  
  293. Returns 
  294.  
  295. This function returns one of the following values: 
  296.  
  297. QH_ERROR 
  298. QH_HCCCONNECT 
  299. QH_HCFSEARCH 
  300. QH_HCLLIST 
  301. QH_HCMMEM 
  302. QH_HCOOBJECT 
  303. QH_HCSSET 
  304. QH_HCSSIGNAL 
  305. QH_HCSPLAYGROUND 
  306. QH_HCSSPRITE 
  307.  
  308. Notes 
  309.  
  310. This function does not validate the accessability of the memory corresponding 
  311. to lhHandle.  Thus, a value that specifies an invalid memory location will 
  312. cause the application to trap. 
  313.  
  314. Related information 
  315.  
  316. o CmnQueryHandleInfo 
  317.  
  318.  
  319. ΓòÉΓòÉΓòÉ 3.2. CmnQueryHandleInfo ΓòÉΓòÉΓòÉ
  320.  
  321. CmnQueryHandleInfo 
  322.  
  323. Purpose 
  324.  
  325. This function returns information about the specified handle. 
  326.  
  327. Syntax 
  328.  
  329. (BOOL)CmnQueryHandleInfo(lhHandle,pvInfo);
  330.  
  331. Parameters 
  332.  
  333. lhHandle (LHANDLE) - specifies the handle to query. 
  334.  
  335. pvInfo (PVOID) - points to a handle-specific structure to be initialized.  On 
  336. return, this points to the initialized structure. 
  337.  
  338. Returns 
  339.  
  340. This function returns TRUE if the function is successful, or FALSE otherwise. 
  341.  
  342. Notes 
  343.  
  344. What pvInfo points to depends on the type of the handle specified: 
  345.  
  346. Handle type Buffer type 
  347.  
  348. HCCCONNECT pvInfo should point to a CCCONNECTINFO structure 
  349.  
  350. HCLLIST   pvInfo should point to a CLLISTINFO structure 
  351.  
  352. HCMMEM    pvInfo should point to a CMMEMINFO structure 
  353.  
  354. HCOOBJECT pvInfo should point to a COOBJECTINFO structure 
  355.  
  356. HCSSET    pvInfo should point to a CSSETINFO structure 
  357.  
  358. Related information 
  359.  
  360. o CCCONNECTINFO data type 
  361. o CLLISTINFO data type 
  362. o CMMEMINFO data type 
  363. o COOBJECTINFO data type 
  364. o CSSETINFO data type 
  365. o CmnQueryHandle 
  366. o CmnSetHandleInfo 
  367.  
  368.  
  369. ΓòÉΓòÉΓòÉ 3.3. CmnQueryVersion ΓòÉΓòÉΓòÉ
  370.  
  371. CmnQueryVersion 
  372.  
  373. Purpose 
  374.  
  375. This function returns the major, minor, and revision numbers of the library. 
  376.  
  377. Syntax 
  378.  
  379. (VOID)CmnQueryVersion(pusMajor,pusMinor,pusRev);
  380.  
  381. Parameters 
  382.  
  383. pusMajor (PUSHORT) - points to the variable to receive the major version number 
  384.  
  385. pusMinor (PUSHORT) - points to the variable to receive the minor version number 
  386.  
  387. pusRev (PUSHORT) - points to the variable to receive the revision version 
  388. number 
  389.  
  390.  
  391. ΓòÉΓòÉΓòÉ 3.4. CmnSetHandleInfo ΓòÉΓòÉΓòÉ
  392.  
  393. CmnSetHandleInfo 
  394.  
  395. Purpose 
  396.  
  397. This function sets certain attributes about the specified handle. 
  398.  
  399. Syntax 
  400.  
  401. (BOOL)CmnSetHandleInfo(lhHandle,pvInfo);
  402.  
  403. Parameters 
  404.  
  405. lhHandle (LHANDLE) - specifies the handle to query. 
  406.  
  407. pvInfo (PVOID) - points to a handle-specific structure containing the 
  408. information to set. 
  409.  
  410. Returns 
  411.  
  412. This function returns TRUE if the function is successful, or FALSE otherwise. 
  413.  
  414. Notes 
  415.  
  416. What pvInfo points to depends on the type of the handle specified: 
  417.  
  418. Handle type Buffer type 
  419.  
  420. HCCCONNECT pvInfo should point to a CCCONNECTINFO structure 
  421.  
  422. Related information 
  423.  
  424. o CCCONNECTINFO data type 
  425. o CmnQueryHandle 
  426. o CmnQueryHandleInfo 
  427.  
  428.  
  429. ΓòÉΓòÉΓòÉ 4. Buffer routines ΓòÉΓòÉΓòÉ
  430.  
  431. The purpose of this group is to provide functionality that modifies entire 
  432. buffers which can be comprised of any type of data.  This group could 
  433. eventually be expanded to provide a text buffer engine to be used in building 
  434. editor applications. 
  435.  
  436. Listed below are the functions which comprise this group: 
  437.  
  438. o CmnBufCompressBytes 
  439. o CmnBufDecompressBytes 
  440. o CmnBufDecryptBytes 
  441. o CmnBufEncryptBytes 
  442.  
  443.  
  444. ΓòÉΓòÉΓòÉ 4.1. CmnBufCompressBytes ΓòÉΓòÉΓòÉ
  445.  
  446. CmnBufCompressBytes 
  447.  
  448. Purpose 
  449.  
  450. This function attempts to compress the contents of a buffer. 
  451.  
  452. Syntax 
  453.  
  454. (BOOL)CmnBufCompressBytes(pbInBuf,ulSzInBuf,pbOutBuf,pulSzOutBuf);
  455.  
  456. Parameters 
  457.  
  458. pbInBuf (PBYTE) - points to the buffer containing the data to be compressed. 
  459.  
  460. ulSzInBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 
  461.  
  462. pbOutBuf (PBYTE) - points to the buffer to hold the compressed data. 
  463.  
  464. pulSzOutBuf (PULONG) - points to the variable specifying the size of the buffer 
  465. pointed to by pbOutBuf.  On return, the variable contains the size of the 
  466. compressed data. 
  467.  
  468. Returns 
  469.  
  470. This function returns TRUE if successful, or FALSE otherwise. 
  471.  
  472. Notes 
  473.  
  474. CmnBufCompressBytes uses a run-length-encoding algorithm when compressing the 
  475. data.  While this algorithm is not expensive in CPU time consumed, it is not 
  476. very good at compressing either and it is not guaranteed that the size of the 
  477. compressed data will be less than the size of the original data. 
  478.  
  479. If you specify NULL for pbOutBuf, no data is written, but pulSzOutBuf will 
  480. still be updated; so, you could specify NULL first to determine the size of the 
  481. buffer needed before actually compressing the data. 
  482.  
  483. Related information 
  484.  
  485. o CmnBufDecompressBytes 
  486.  
  487.  
  488. ΓòÉΓòÉΓòÉ 4.2. CmnBufDecompressBytes ΓòÉΓòÉΓòÉ
  489.  
  490. CmnBufDecompressBytes 
  491.  
  492. Purpose 
  493.  
  494. This function decompresses the contents of a buffer which was compressed 
  495. previously using CmnBufCompressBytes. 
  496.  
  497. Syntax 
  498.  
  499. (BOOL) CmnBufDecompressBytes(pbInBuf,ulSzInBuf,pbOutBuf,pulSzOutBuf);
  500.  
  501. Parameters 
  502.  
  503. pbInBuf (PBYTE) - points to the buffer containing the data to be decompressed. 
  504.  
  505. ulSzInBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 
  506.  
  507. pbOutBuf (PBYTE) - points to the buffer to hold the decompressed data. 
  508.  
  509. pulSzOutBuf (PULONG) - points to the variable specifying the size of the buffer 
  510. pointed to by pbOutBuf.  On return, the variable contains the size of the 
  511. decompressed data. 
  512.  
  513. Returns 
  514.  
  515. This function returns TRUE if successful, or FALSE otherwise. 
  516.  
  517. Notes 
  518.  
  519. There is no error checking to insure that the buffer was compressed with 
  520. CmnBufCompressBytes.  This responsibility is left to the application designer. 
  521.  
  522. Related information 
  523.  
  524. o CmnBufCompressBytes 
  525.  
  526.  
  527. ΓòÉΓòÉΓòÉ 4.3. CmnBufDecryptBytes ΓòÉΓòÉΓòÉ
  528.  
  529. CmnBufDecryptBytes 
  530.  
  531. Purpose 
  532.  
  533. This function decrypts the contents of a buffer which was encrypted previously 
  534. using CmnBufEncryptBytes. 
  535.  
  536. Syntax 
  537.  
  538. (BOOL)CmnBufDecryptBytes(pbInBuf,ulSzBuf,pbOutBuf);
  539.  
  540. Parameters 
  541.  
  542. pbInBuf (PBYTE) - points to the buffer containing the data to be decrypted. 
  543.  
  544. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 
  545.  
  546. pbOutBuf (PBYTE) - points to the buffer to contain the decrypted data. 
  547.  
  548. Returns 
  549.  
  550. This function returns TRUE if successful, or FALSE otherwise. 
  551.  
  552. Notes 
  553.  
  554. There is no error checking to insure that the buffer was encrypted with 
  555. CmnBufEncryptBytes.  This responsibility is left to the application designer. 
  556.  
  557. Related information 
  558.  
  559. o CmnBufEncryptBytes 
  560.  
  561.  
  562. ΓòÉΓòÉΓòÉ 4.4. CmnBufEncryptBytes ΓòÉΓòÉΓòÉ
  563.  
  564. CmnBufEncryptBytes 
  565.  
  566. Purpose 
  567.  
  568. This function encrypts a buffer using the NSS algorithm. 
  569.  
  570. Syntax 
  571.  
  572. (BOOL)CmnBufEncryptBytes(pbInBuf,ulSzBuf,pbOutBuf);
  573.  
  574. Parameters 
  575.  
  576. pbInBuf (PBYTE) - points to the buffer containing the data to be encrypted. 
  577.  
  578. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pbInBuf. 
  579.  
  580. pbOutBuf (PBYTE) - points to the buffer to contain the encrypted data. 
  581.  
  582. Returns 
  583.  
  584. This function returns TRUE if successful, or FALSE otherwise. 
  585.  
  586. Notes 
  587.  
  588. NSS is an acronym for not-so-secure and describes the strength of the algorithm 
  589. used.  The encrypted data is always of the same length as the original data. 
  590. It is suggested that this function be used in conjunction with the function 
  591. CmnBufCompressBytes to result in data that will not so easily be decyphered. 
  592.  
  593. Related information 
  594.  
  595. o CmnBufDecryptBytes 
  596.  
  597.  
  598. ΓòÉΓòÉΓòÉ 5. Communication routines ΓòÉΓòÉΓòÉ
  599.  
  600. The purpose of this group is to provide easy to use communication routines for 
  601. client/server application development.  The bidirectional connections are 
  602. implemented via named pipes and can thus work locally or over a LAN. 
  603.  
  604. A client simply opens a connection and starts reading and/or writing to it, 
  605. while a server waits for a connection and reads/writes to a private connection 
  606. which is derived from the "control connection" (see the pseudocode below). This 
  607. yields three connection types: 
  608.  
  609.  1. Client 
  610.  2. Server 
  611.  3. Server-connect 
  612.  
  613. /* Client */
  614. HCCCONNECT hccConnect;
  615.  
  616. CmnComOpenConnection(...,&hccConnect);
  617. CmnComReadData(hccConnect,...);
  618. CmnComWriteData(hccConnect,...);
  619. CmnComSendControl(hccConnect,CSC_CTRL_CLOSE);
  620. CmnComCloseConnection(&hccConnect);
  621. /* ------------------------------------------------ */
  622. /* Server */
  623. HCCCONNECT hccServer;
  624. HCCCONNECT hccConnect;
  625.  
  626. CmnComOpenConnection(...,&hccServer);
  627.  
  628. CmnComWaitConnection(hccServer,&hccConnect);
  629. /****************************************************/
  630. /* For peer-to-peer, we would close hccServer after */
  631. /* establishing a data connection with a client     */
  632. /****************************************************/
  633. CmnComReadData(hccConnect,...);
  634. CmnComWriteData(hccConnect,...);
  635. CmnComSendControl(hccConnect,CSC_CLOSE);
  636. CmnComCloseConnection(&hccServer);
  637.  
  638. CmnComCloseConnection(&hccConnect);
  639.  
  640. Using this implementation strategy has two advantages:  1) it is very easy to 
  641. create client/server or peer-to-peer applications and 2) programmers familiar 
  642. with TCP/IP will find this very familiar. 
  643.  
  644. Data is written in the form of packets, allowing for a handshaking protocol to 
  645. be used by the functions.  This insures that the other end receives the data 
  646. written into the connection. 
  647.  
  648. Listed below are the functions which comprise this group: 
  649.  
  650. o CmnComCloseConnection 
  651. o CmnComOpenConnection 
  652. o CmnComQueryData 
  653. o CmnComReadData 
  654. o CmnComSendControl 
  655. o CmnComWaitConnection 
  656. o CmnComWriteData 
  657.  
  658.  
  659. ΓòÉΓòÉΓòÉ 5.1. CmnComCloseConnection ΓòÉΓòÉΓòÉ
  660.  
  661. CmnComCloseConnection 
  662.  
  663. Purpose 
  664.  
  665. Closes a connection. 
  666.  
  667. Syntax 
  668.  
  669. (COMERROR)CmnComCloseConnection(phccConnect)
  670.  
  671. Parameters 
  672.  
  673. phccConnect (PHCCCONNECT) - points to the variable specifying the handle of the 
  674. connection.  On return, this variable contains NULL. 
  675.  
  676. Returns 
  677.  
  678. This function returns one of the following values: 
  679.  
  680. COM_ERR_NOERROR 
  681. COM_ERR_BADHANDLE 
  682.  
  683. Notes 
  684.  
  685. Use CmnComCloseConnection to close a specific connection.  Note that closing a 
  686. server connection does not close any private data connections that were 
  687. established from the server connection. 
  688.  
  689. It is recommended to send a CSC_CLOSE control code to indicate to the 
  690. application on the other side that the connection is about to be closed. 
  691.  
  692. Related information 
  693.  
  694. o HCCCONNECT data type 
  695. o CmnComOpenConnection 
  696. o CmnComSendControl 
  697.  
  698.  
  699. ΓòÉΓòÉΓòÉ 5.2. CmnComOpenConnection ΓòÉΓòÉΓòÉ
  700.  
  701. CmnComOpenConnection 
  702.  
  703. Purpose 
  704.  
  705. Creates a new connection handle based upon the information provided. 
  706.  
  707. Syntax 
  708.  
  709. (COMERROR)CmnComOpenConnection(pcoiInfo,phccConnect)
  710.  
  711. Parameters 
  712.  
  713. pcoiInfo (PCCOPENINFO) - points to a CCOPENINFO structure which describes the 
  714. connection to be created.  This parameter is required.  On return, the usAttr 
  715. field specifies the type of connection that was established (e.g. client, 
  716. server, or server-connect). 
  717.  
  718. phccConnect (PHCCCONNECT) - points to the variable which receives the new 
  719. connection handle. 
  720.  
  721. Returns 
  722.  
  723. This function returns one of the following values: 
  724.  
  725. COM_ERR_NOERROR 
  726. COM_ERR_BADARGUMENT 
  727. COM_ERR_CC_CLOSE 
  728. COM_ERR_CC_RESET 
  729. COM_ERR_ERROR 
  730. COM_ERR_INITFAILED 
  731. COM_ERR_NOCONNECTION 
  732. COM_ERR_NOMEMORY 
  733. COM_ERR_READFAILED 
  734. COM_ERR_TIMEOUT 
  735.  
  736. Notes 
  737.  
  738. Use CmnComOpenConnection to create a new connection.  If the achMachine field 
  739. of the CCOPENINFO structure is empty, then the connection is a local one.  Note 
  740. that the timeout value (the lTimeout field) is changeable via CmnSetHandleInfo. 
  741. This allows you to set a timeout now until a connection is established and then 
  742. change it later for data retrieval. 
  743.  
  744. Server connections cannot be read from or written to.  Instead, they are used 
  745. to call CmnComWaitConnection to establish a server-connect connection for data 
  746. transfer. 
  747.  
  748. Related information 
  749.  
  750. o CCOPENINFO data type 
  751. o HCCCONNECT data type 
  752. o CmnComCloseConnection 
  753. o CmnComWaitConnection 
  754.  
  755.  
  756. ΓòÉΓòÉΓòÉ 5.3. CmnComQueryData ΓòÉΓòÉΓòÉ
  757.  
  758. CmnComQueryData 
  759.  
  760. Purpose 
  761.  
  762. Checks to see if data is available for reading. 
  763.  
  764. Syntax 
  765.  
  766. (COMERROR)CmnComQueryData(hccConnect,pulData)
  767.  
  768. Parameters 
  769.  
  770. hccConnect (HCCCONNECT) - specifies the connection handle. 
  771.  
  772. pulData (PULONG) - points to the variable which receives the number of bytes 
  773. available. 
  774.  
  775. Returns 
  776.  
  777. This function returns one of the following values: 
  778.  
  779. COM_ERR_NOERROR 
  780. COM_ERR_BADHANDLE 
  781.  
  782. Notes 
  783.  
  784. Use CmnComQueryData to determine if data is available on the connection for 
  785. reading.  Note that if the application writes data to the connection and the 
  786. receiving end does not read the data before this function is called, pusData 
  787. will return 0 bytes available. 
  788.  
  789. Related information 
  790.  
  791. o HCCCONNECT data type 
  792. o CmnComReadData 
  793. o CmnComWriteData 
  794.  
  795.  
  796. ΓòÉΓòÉΓòÉ 5.4. CmnComReadData ΓòÉΓòÉΓòÉ
  797.  
  798. CmnComReadData 
  799.  
  800. Purpose 
  801.  
  802. Reads data from a connection and sends an acknowledgement to the other end of 
  803. the connection. 
  804.  
  805. Syntax 
  806.  
  807. (COMERROR)CmnComReadData(hccConnect,pvBuf,pulSzBuf)
  808.  
  809. Parameters 
  810.  
  811. hccConnect (HCCCONNECT) - specifies the connection handle. 
  812.  
  813. pvBuf (PVOID) - points to the buffer to receive the data. 
  814.  
  815. pulSzBuf (PULONG) - points to the variable specifying the size of the buffer 
  816. pointed to by pvBuf.  On return, this variable contains the number of bytes 
  817. actually read from the connection. 
  818.  
  819. Returns 
  820.  
  821. This function returns one of the following values: 
  822.  
  823. COM_ERR_NOERROR 
  824. COM_ERR_BADDATA 
  825. COM_ERR_BADHANDLE 
  826. COM_ERR_BUFFERTOOLARGE 
  827. COM_ERR_CC_CLOSE 
  828. COM_ERR_CC_RESET 
  829. COM_ERR_ERROR 
  830. COM_ERR_INITFAILED 
  831. COM_ERR_READFAILED 
  832. COM_ERR_TIMEOUT 
  833.  
  834. Notes 
  835.  
  836. Use CmnComReadData to read data from a connection.  Note that if the buffer 
  837. specified is not large enough to contain the data in the current packet, the 
  838. additional bytes are discarded.  Thus, if a predetermined, fixed data length is 
  839. not used, it is highly recommended that CmnComQueryData is called to retrieve 
  840. the size of the current packet.  If there is no data at the front of the 
  841. connection for the application to read, this function waits until there is data 
  842. or until a timeout occurs. 
  843.  
  844. For 16-bit applications, there is a limit of 61440 bytes that can be read in 
  845. one call. 
  846.  
  847. Note that if the other end sends a control code, no data is placed into pvBuf 
  848. but the appropriate COM_ERR_CC_* code is returned instead. 
  849.  
  850. Related information 
  851.  
  852. o HCCCONNECT data type 
  853. o CmnComQueryData 
  854. o CmnComSendControl 
  855. o CmnComWriteData 
  856.  
  857.  
  858. ΓòÉΓòÉΓòÉ 5.5. CmnComSendControl ΓòÉΓòÉΓòÉ
  859.  
  860. CmnComSendControl 
  861.  
  862. Purpose 
  863.  
  864. This function sends a control code to the other end of the connection. 
  865.  
  866. Syntax 
  867.  
  868. (COMERROR)CmnComSendControl(hccConnect,ulCtrlCode)
  869.  
  870. Parameters 
  871.  
  872. hccConnect (HCCCONNECT) - specifies the connection handle. 
  873.  
  874. ulCtrlCode (ULONG) - specifies a CSC_* control code. 
  875.  
  876. Returns 
  877.  
  878. This function returns one of the following values: 
  879.  
  880. COM_ERR_NOERROR 
  881. COM_ERR_BADACK 
  882. COM_ERR_BADCONTROL 
  883. COM_ERR_BADHANDLE 
  884. COM_ERR_NOTIMPLEMENTED 
  885. COM_ERR_WRITEFAILED 
  886.  
  887. Notes 
  888.  
  889. Use CmnComSendControl to send a control code to the other end of the 
  890. connection.  "Control codes" are predefined data packets which indicate that a 
  891. particular action is to be performed.  For CSC_CLOSE control codes, it is 
  892. conceivable that the other end of the connection is able to close the 
  893. connection before the packet acknowledgement is read by this end.  Thus, a 
  894. return value of COM_ERR_BADACK should be accounted for in your application 
  895. code. It is highly recommended that a CSC_CLOSE control code is sent before 
  896. closing the connection to allow the other end to perform any necessary cleanup 
  897. (such as reading any data that is expected). 
  898.  
  899. Note that this function unconditionally waits for an acknowledgement. 
  900.  
  901. Related information 
  902.  
  903. o CSC_ constants 
  904. o HCCCONNECT data type 
  905.  
  906.  
  907. ΓòÉΓòÉΓòÉ 5.6. CmnComWaitConnection ΓòÉΓòÉΓòÉ
  908.  
  909. CmnComWaitConnection 
  910.  
  911. Purpose 
  912.  
  913. Waits for a connection from a client. 
  914.  
  915. Syntax 
  916.  
  917. (COMERROR)CmnComWaitConnection(hccServer,phccConnect)
  918.  
  919. Parameters 
  920.  
  921. hccServer (HCCCONNECT) - specifies the server connection handle. 
  922.  
  923. phccConnect (PHCCCONNECT) - points to the variable which receives the created 
  924. server-connect connection handle. 
  925.  
  926. Returns 
  927.  
  928. This function returns one of the following values: 
  929.  
  930. COM_ERR_NOERROR 
  931. COM_ERR_BADHANDLE 
  932. COM_ERR_ERROR 
  933. COM_ERR_INITFAILED 
  934. COM_ERR_NOMEMORY 
  935. COM_ERR_NONEFREE 
  936. COM_ERR_NOTSERVER 
  937. COM_ERR_TIMEOUT 
  938. COM_ERR_WRITEFAILED 
  939.  
  940. Notes 
  941.  
  942. Use CmnComWaitConnection to listen for a connection by a client. When this 
  943. happens, a server-connect connection is created for data exchange between the 
  944. applications.  This allows the hccServer handle to continue to listen for other 
  945. connections via subsequent calls to this function.  If peer-to-peer 
  946. communications are desired, CmnComCloseConnection can be called to close the 
  947. server connection so that no further data connections are established. 
  948.  
  949. A server may have up to 256 associated server-connect connections spawned from 
  950. it, but this may exceed a system-imposed limit. 
  951.  
  952. Related information 
  953.  
  954. o HCCCONNECT data type 
  955. o CmnComCloseConnection 
  956.  
  957.  
  958. ΓòÉΓòÉΓòÉ 5.7. CmnComWriteData ΓòÉΓòÉΓòÉ
  959.  
  960. CmnComWriteData 
  961.  
  962. Purpose 
  963.  
  964. Writes data to a connection and waits for an acknowledgement from the other end 
  965. of the connection. 
  966.  
  967. Syntax 
  968.  
  969. (COMERROR)CmnComWriteData(hccConnect,pvBuf,ulSzBuf)
  970.  
  971. Parameters 
  972.  
  973. hccConnect (HCCCONNECT) - specifies the connection handle. 
  974.  
  975. pvBuf (PVOID) - points to the buffer containing the data to write. 
  976.  
  977. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pvBuf. 
  978.  
  979. Returns 
  980.  
  981. This function returns one of the following values: 
  982.  
  983. COM_ERR_NOERROR 
  984. COM_ERR_BADACK 
  985. COM_ERR_BADHANDLE 
  986. COM_ERR_BUFFERTOOLARGE 
  987. COM_ERR_WRITEFAILED 
  988.  
  989. Notes 
  990.  
  991. Use CmnComWriteData to write data to a connection. Acknowledgement receipt is 
  992. handled transparently by the function. 
  993.  
  994. For 16-bit applications, there is a limit of 61440 bytes that can be written in 
  995. one call. 
  996.  
  997. Related information 
  998.  
  999. o HCCCONNECT data type 
  1000. o CmnComReadData 
  1001.  
  1002.  
  1003. ΓòÉΓòÉΓòÉ 6. Debugging routines ΓòÉΓòÉΓòÉ
  1004.  
  1005. The purpose of this group is to provide aid in debugging your applications. 
  1006. While they are not anything spectacular, I have found them helpful from time to 
  1007. time. 
  1008.  
  1009. Listed below are the functions which comprise this group: 
  1010.  
  1011. o CmnDbgWriteBinary 
  1012. o CmnDbgWriteRecord 
  1013. o CmnDbgWriteText 
  1014.  
  1015.  
  1016. ΓòÉΓòÉΓòÉ 6.1. CmnDbgWriteBinary ΓòÉΓòÉΓòÉ
  1017.  
  1018. CmnDbgWriteBinary 
  1019.  
  1020. Purpose 
  1021.  
  1022. This function writes the contents of a buffer to a file. 
  1023.  
  1024. Syntax 
  1025.  
  1026. (SHORT)CmnDbgWriteBinary(pvFile,
  1027.                          usFileType,
  1028.                          pvBuf,
  1029.                          usSzBuf);
  1030.  
  1031. Parameters 
  1032.  
  1033. pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
  1034. in <stdio.h>). 
  1035.  
  1036. usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
  1037. pvFile. 
  1038.  
  1039. pvBuf (PVOID) - points to the buffer to be written. 
  1040.  
  1041. usSzBuf (USHORT) - specifies the size of the buffer pointed to by pvBuf. 
  1042.  
  1043. Returns 
  1044.  
  1045. This function returns the number of bytes successfully written, or DWT_ERROR 
  1046. otherwise. 
  1047.  
  1048. Notes 
  1049.  
  1050. Use CmnDbgWriteBinary to write the contents of a buffer to a specific file. 
  1051. The format of the output is a combination of hexadecimal on the left side with 
  1052. ASCII representation on the right with a vertical line separating the two. 
  1053. Unprintable characters (as defined by the function isprint) are displayed as 
  1054. periods in the ASCII output. 
  1055.  
  1056. Related information 
  1057.  
  1058. o DWT_TYPE_ constants 
  1059. o CmnDbgWriteText 
  1060.  
  1061.  
  1062. ΓòÉΓòÉΓòÉ 6.2. CmnDbgWriteRecord ΓòÉΓòÉΓòÉ
  1063.  
  1064. CmnDbgWriteRecord 
  1065.  
  1066. Purpose 
  1067.  
  1068. This function writes the contents of a structure to a file. 
  1069.  
  1070. Syntax 
  1071.  
  1072. (SHORT)CmnDbgWriteRecord(pvFile,
  1073.                          usFileType,
  1074.                          pcFormat,
  1075.                          usNumRecs,
  1076.                          pbBuf);
  1077.  
  1078. Parameters 
  1079.  
  1080. pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
  1081. in <stdio.h>). 
  1082.  
  1083. usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
  1084. pvFile. 
  1085.  
  1086. pcFormat (PCSLINEDESC) - points to an array of CSLINEDESC structures describing 
  1087. the format of the structure to be written. 
  1088.  
  1089. usNumRecs (USHORT) - specifies the number of records pointed to by pcFormat. 
  1090.  
  1091. pbBuf (PBYTE) - points to the structure to write. 
  1092.  
  1093. Returns 
  1094.  
  1095. This function returns the number of fields in the structure successfully 
  1096. written, or DWT_ERROR otherwise. 
  1097.  
  1098. Notes 
  1099.  
  1100. Use CmnDbgWriteRecord to write the contents of a record to a specific file. 
  1101. This function calls CmnDbgWriteText to actually write the results, so the file 
  1102. is guaranteed to be flushed after every field is output. 
  1103.  
  1104. Related information 
  1105.  
  1106. o DWT_TYPE_ constants 
  1107. o CSLINEDESC data type 
  1108. o CmnDbgWriteText 
  1109.  
  1110.  
  1111. ΓòÉΓòÉΓòÉ 6.3. CmnDbgWriteText ΓòÉΓòÉΓòÉ
  1112.  
  1113. CmnDbgWriteText 
  1114.  
  1115. Purpose 
  1116.  
  1117. This function writes text to a specified file. 
  1118.  
  1119. Syntax 
  1120.  
  1121. (SHORT)CmnDbgWriteText(pvFile,usFileType,pchFmt,...);
  1122.  
  1123. Parameters 
  1124.  
  1125. pvFile (PVOID) - points to either the file name or a FILE structure (as defined 
  1126. in <stdio.h>). 
  1127.  
  1128. usFileType (USHORT) - specifies a DWT_TYPE_ constant describing the contents of 
  1129. pvFile. 
  1130.  
  1131. pchFmt (PCHAR) - points to the format string (as in the C printf routine). 
  1132.  
  1133. ... (va_list) - specifies any additional arguments referred to by pchFmt 
  1134.  
  1135. Returns 
  1136.  
  1137. This function returns the number of characters successfully written, or 
  1138. DWT_ERROR otherwise. 
  1139.  
  1140. Notes 
  1141.  
  1142. Use CmnDbgWriteText to write information to a file.  By specifying 
  1143. DWT_TYPE_FILE for usFileType, you can use a predefined stream (stdout, stderr) 
  1144. or any other file that is already opened. Specifying DWT_TYPE_NAME indicates 
  1145. that this function should open the file in append mode and close it before 
  1146. returning. 
  1147.  
  1148. o DWT_TYPE_ constants 
  1149.  
  1150.  
  1151. ΓòÉΓòÉΓòÉ 7. File routines ΓòÉΓòÉΓòÉ
  1152.  
  1153. The purpose of this group is to provide functions which help you perform common 
  1154. tasks without a lot of the work. 
  1155.  
  1156. Listed below are the functions which comprise this group: 
  1157.  
  1158. o CmnFilCopyDiskette 
  1159. o CmnFilCreateSearch 
  1160. o CmnFilDestroySearch 
  1161. o CmnFilFormatDiskette 
  1162. o CmnFilInstallDiskette 
  1163. o CmnFilQueryExtAttribute 
  1164. o CmnFilQueryLabel 
  1165. o CmnFilSearchFiles 
  1166. o CmnFilSetExtAttribute 
  1167. o CmnFilSplitFilename 
  1168.  
  1169.  
  1170. ΓòÉΓòÉΓòÉ 7.1. CmnFilCopyDiskette ΓòÉΓòÉΓòÉ
  1171.  
  1172. CmnFilCopyDiskette 
  1173.  
  1174. Purpose 
  1175.  
  1176. This function copies the contents of a diskette onto another diskette. 
  1177.  
  1178. Syntax 
  1179.  
  1180. (BOOL)CmnFilCopyDiskette(chSrc,chDest,ulOptions,pfnCallback,pvUser);
  1181.  
  1182. Parameters 
  1183.  
  1184. chSrc (CHAR) - specifies the source drive and can be upper- or lower-case. 
  1185.  
  1186. chDest (CHAR) - specifies the destination drive and can be upper- or 
  1187. lower-case. 
  1188.  
  1189. ulOptions (ULONG) - one or more FCD_OPT_* constants controlling the behavior of 
  1190. this function. 
  1191.  
  1192. pfnCallback (PFNDISKIO) - points to a callback function.  See below for more 
  1193. information. 
  1194.  
  1195. pvUser (PVOID) - pointer to user data which is passed to pfnCallback. 
  1196.  
  1197. Returns 
  1198.  
  1199. This function returns TRUE if successful, or FALSE otherwise. 
  1200.  
  1201. Notes 
  1202.  
  1203. Use CmnFilCopyDiskette to copy one diskette onto another.  The power of this 
  1204. function is in the use of pfnCallback; this callback function is called by 
  1205. CmnFilCopyDiskette in various times for various reasons.  See the items listed 
  1206. below for more information on the specifics of each constant. 
  1207.  
  1208. Related information 
  1209.  
  1210. o FCD_TYPE_ constants 
  1211. o FCD_MSG_ constants 
  1212. o FCD_ERR_ constants 
  1213. o PFNDISKIO function 
  1214.  
  1215.  
  1216. ΓòÉΓòÉΓòÉ 7.2. CmnFilCreateSearch ΓòÉΓòÉΓòÉ
  1217.  
  1218. CmnFilCreateSearch 
  1219.  
  1220. Purpose 
  1221.  
  1222. This function creates a search handle for use in subsequent calls to 
  1223. CmnFilSearchFiles. 
  1224.  
  1225. Syntax 
  1226.  
  1227. (BOOL)CmnFilCreateSearch(pchMask,ulAttr,phcSearch);
  1228.  
  1229. Parameters 
  1230.  
  1231. pchMask (PCHAR) - points to the file mask to be used when searching for the 
  1232. files. 
  1233.  
  1234. ulAttr (ULONG) - specifies a combination of FCS_ATTR_ constants which specify 
  1235. the types of files to search for. 
  1236.  
  1237. phcSearch (PHCFSEARCH) - on return, this points to the variable containing the 
  1238. created search handle. 
  1239.  
  1240. Returns 
  1241.  
  1242. This function returns TRUE if successful, or FALSE otherwise. 
  1243.  
  1244. Notes 
  1245.  
  1246. Use CmnFilCreateSearch to create a search handle for use in calls to 
  1247. CmnFilSearchFiles.  Note that, unlike DosFindFirst, "normal" files (those with 
  1248. no special attributes) are not searched for unless FCS_ATTR_NORMAL is specified 
  1249. in ulAttr. 
  1250.  
  1251. Related information 
  1252.  
  1253. o FCS_ATTR_ constants 
  1254. o HCFSEARCH data type 
  1255. o CmnFilSearchFiles 
  1256.  
  1257.  
  1258. ΓòÉΓòÉΓòÉ 7.3. CmnFilDestroySearch ΓòÉΓòÉΓòÉ
  1259.  
  1260. CmnFilDestroySearch 
  1261.  
  1262. Purpose 
  1263.  
  1264. This function destroys a search handle created by CmnFilCreateSearch. 
  1265.  
  1266. Syntax 
  1267.  
  1268. (BOOL)CmnFilDestroySearch(hcSearch);
  1269.  
  1270. Parameters 
  1271.  
  1272. phcSearch (PHCFSEARCH) - points to the variable specifying the search handle to 
  1273. destroy.  On return, this variable contains NULL. 
  1274.  
  1275. Returns 
  1276.  
  1277. This function returns TRUE if successful, or FALSE otherwise. 
  1278.  
  1279. Notes 
  1280.  
  1281. Use CmnFilDestroySearch to free any resources consumed by the search functions. 
  1282.  
  1283. Related information 
  1284.  
  1285. o HCFSEARCH data type 
  1286. o CmnFilCreateSearch 
  1287.  
  1288.  
  1289. ΓòÉΓòÉΓòÉ 7.4. CmnFilFormatDiskette ΓòÉΓòÉΓòÉ
  1290.  
  1291. CmnFilFormatDiskette 
  1292.  
  1293. Purpose 
  1294.  
  1295. This function formats a diskette. 
  1296.  
  1297. Syntax 
  1298.  
  1299. (BOOL)CmnFilFormatDiskette(chDrive,pfiInfo,pfnCallback,pvUser);
  1300.  
  1301. Parameters 
  1302.  
  1303. chDrive (CHAR) - specifies the drive in which the diskette to be formatted is 
  1304. placed. 
  1305.  
  1306. pfiInfo (PCFFORMATINFO) - points to a CFFORMATINFO structure specifying the 
  1307. format parameters to be used.  If NULL the parameters for the diskette are used 
  1308. (if the diskette is already formatted), or the defaults for the drive are used 
  1309. (if the diskette is not already formatted). 
  1310.  
  1311. pfnCallback (PFNDISKIO) - points to a callback function.  See below for more 
  1312. information. 
  1313.  
  1314. pvUser (PVOID) - pointer to user data which is passed to pfnCallback. 
  1315.  
  1316. Returns 
  1317.  
  1318. This function returns TRUE if successful, or FALSE otherwise. 
  1319.  
  1320. Notes 
  1321.  
  1322. Use CmnFilFormatDiskette to format a diskette.  The power of this function is 
  1323. in the use of pfnCallback; this callback function is called by 
  1324. CmnFilFormatDiskette in various times for various reasons.  See the items 
  1325. listed below for more information on the specifics of each constant. 
  1326.  
  1327. The boot sector that is written to the diskette consists of a program at offset 
  1328. 0x40 (which is jumped to by the first two bytes of the boot sector), which 
  1329. loads and displays an ASCIIZ string beginning at offset 0x80.  The default 
  1330. message placed there is a NULL-string.  To specify your own string to be 
  1331. displayed, you need to read track 0, head 0, sector 0, and copy your string 
  1332. into the buffer containing the sector's data at the correct offset, and then 
  1333. write the new contents to track 0, head 0, sector 0. 
  1334.  
  1335. When determining the string to be written, be aware that - on the rarely found 
  1336. machines with single-head, single-density floppy drives - you only have 30 
  1337. bytes (including the terminating 0) for the string's contents. 
  1338.  
  1339. Related information 
  1340.  
  1341. o FCD_TYPE_ constants 
  1342. o FCD_MSG_ constants 
  1343. o FCD_ERR_ constants 
  1344. o CFFORMATINFO data type 
  1345. o PFNDISKIO function 
  1346.  
  1347.  
  1348. ΓòÉΓòÉΓòÉ 7.5. CmnFilInstallDiskette ΓòÉΓòÉΓòÉ
  1349.  
  1350. CmnFilInstallDiskette 
  1351.  
  1352. Purpose 
  1353.  
  1354. This function performs operations with respect to an installation diskette for 
  1355. an application. 
  1356.  
  1357. Syntax 
  1358.  
  1359. (ULONG)CmnFilInstallDiskette(pchFile,
  1360.                              pchVendor,
  1361.                              pchApp,
  1362.                              pchName,
  1363.                              pulNumLicenses,
  1364.                              ulRequest);
  1365.  
  1366. Parameters 
  1367.  
  1368. pchFile (PCHAR) - points to the name of the file to contain the installation 
  1369. data. 
  1370.  
  1371. pchVendor (PCHAR) - points to the name of the vendor of the application. 
  1372.  
  1373. pchApp (PCHAR) - points to the name of the application. 
  1374.  
  1375. pchName (PCHAR) - points to an arbitrary name for the installation data. 
  1376.  
  1377. pulNumLicenses (PULONG) - points to a variable specifying the number of 
  1378. licenses.  See below. 
  1379.  
  1380. ulRequest (ULONG) - specifies a function to be performed. 
  1381.  
  1382. Returns 
  1383.  
  1384. CFID_ERR_NOERROR if successful, a CFID_ERR_* constant otherwise. 
  1385.  
  1386. Notes 
  1387.  
  1388. Use CmnFilInstallDiskette to perform installation verification and other 
  1389. related functions.  The function to be performed is specified in ulRequest and 
  1390. can be one of the following: 
  1391.  
  1392. CFID_REQ_CREATE     Initializes the file whose name is specified in pchFile to 
  1393.                     contain a specific number of licenses. 
  1394. CFID_REQ_DECREMENT  Decrements the number of available licenses. 
  1395. CFID_REQ_INCREMENT  Increments the number of available licenses. 
  1396. CFID_REQ_QUERY      Returns the number of available licenses. 
  1397.  
  1398. For CFID_REQ_CREATE, pulNumLicenses should be initialized to specify the total 
  1399. number of licenses for the application.  For the other functions, the value is 
  1400. ignored.  For all functions, this variable contains the updated number of 
  1401. available licenses on return. 
  1402.  
  1403.  
  1404. ΓòÉΓòÉΓòÉ 7.6. CmnFilQueryExtAttribute ΓòÉΓòÉΓòÉ
  1405.  
  1406. CmnFilQueryExtAttribute 
  1407.  
  1408. Purpose 
  1409.  
  1410. This function queries the value of an extended attribute written by 
  1411. CmnFilSetExtAttribute. 
  1412.  
  1413. Syntax 
  1414.  
  1415. (BOOL)CmnFilQueryExtAttribute(pchFile,
  1416.                               pchVendor,
  1417.                               pchAppl,
  1418.                               pchName,
  1419.                               pusAttr,
  1420.                               pbValue,
  1421.                               pusSzValue);
  1422.  
  1423. Parameters 
  1424.  
  1425. pchFile (PCHAR) - points to the name of the file containing the extended 
  1426. attributes to query. 
  1427.  
  1428. pchVendor (PCHAR) - points to the name of the vendor whose application wrote 
  1429. the extended attribute or an FEA_ constant. 
  1430.  
  1431. pchAppl (PCHAR) - points to the name of the application which wrote the 
  1432. extended attribute. 
  1433.  
  1434. pchName (PCHAR) - points to the name of the extended attribute. 
  1435.  
  1436. pusAttr (PUSHORT) - points to the attribute of the extended attribute. 
  1437.  
  1438. pbValue (PBYTE) - points to a buffer to receive the results. On return, the 
  1439. buffer contains the value of the extended attribute. 
  1440.  
  1441. pusSzValue (PUSHORT) - points to a variable specifying the size of pbValue.  On 
  1442. return, this points to the number of bytes copied to the buffer. 
  1443.  
  1444. Returns 
  1445.  
  1446. This function returns TRUE if successful, or FALSE otherwise. 
  1447.  
  1448. Notes 
  1449.  
  1450. Use CmnFilQueryExtAttribute to query an extended attribute of a file.  Because 
  1451. this call (and CmnFilSetExtAttribute) enforces the convention stated in the IBM 
  1452. Programming Toolkit's "Programming Guide", this function is only guaranteed to 
  1453. return meaningful results if the extended attribute was originally written by 
  1454. CmnFilSetExtAttribute. 
  1455.  
  1456. If an FEA_ constant is specified for pchVendor, pchAppl and pchName are 
  1457. ignored. 
  1458.  
  1459. Related information 
  1460.  
  1461. o FEA_ constants 
  1462. o CmnFilSetExtAttribute 
  1463.  
  1464.  
  1465. ΓòÉΓòÉΓòÉ 7.7. CmnFilQueryLabel ΓòÉΓòÉΓòÉ
  1466.  
  1467. CmnFilQueryLabel 
  1468.  
  1469. Purpose 
  1470.  
  1471. This function returns the label on the diskette in the specified drive. 
  1472.  
  1473. Syntax 
  1474.  
  1475. (BOOL)CmnFilQueryLabel(chDrive,pchLabel);
  1476.  
  1477. Parameters 
  1478.  
  1479. chDrive (CHAR) - specifies the drive to query. 
  1480.  
  1481. pchLabel (PCHAR) - points to the buffer to hold the label.  On return, this 
  1482. buffer holds the diskette label if successful. 
  1483.  
  1484. Returns 
  1485.  
  1486. This function returns TRUE if successful, or FALSE otherwise. 
  1487.  
  1488. Notes 
  1489.  
  1490. Use CmnFilQueryLabel to determine the label of the diskette in the specified 
  1491. drive.  This function will not cause a "hard error" popup to appear if no 
  1492. diskette is in the drive; instead, this function will return FALSE. 
  1493.  
  1494.  
  1495. ΓòÉΓòÉΓòÉ 7.8. CmnFilSearchFiles ΓòÉΓòÉΓòÉ
  1496.  
  1497. CmnFilSearchFiles 
  1498.  
  1499. Purpose 
  1500.  
  1501. This function returns the next file found that has the characteristics 
  1502. specified when the search handle was created. 
  1503.  
  1504. Syntax 
  1505.  
  1506. (LONG)CmnFilSearchFiles(hcSearch,pchBuf,ulSzBuf);
  1507.  
  1508. Parameters 
  1509.  
  1510. hcSearch (HCFSEARCH) - specifies the search handle. 
  1511.  
  1512. pchBuf (PCHAR) - points to a buffer to receive the results.  On return, the 
  1513. buffer contains the fully qualified name of the next file found. 
  1514.  
  1515. ulSzBuf (ULONG) - specifies the size of pchBuf. 
  1516.  
  1517. Returns 
  1518.  
  1519. This function returns the attribute of the file found as a combination of 
  1520. FCS_ATTR_ constants if successful, FSF_NOFILES if no more files were found that 
  1521. match the criteria, or FSF_ERROR if an error occurred. 
  1522.  
  1523. Notes 
  1524.  
  1525. Use CmnFilSearchFiles to search for the next file that exactly matches the 
  1526. criteria (file mask and attribute) specified in the search handle. Note that 
  1527. the attribute match must be exact (i.e. not a subset).  For example, if file 
  1528. "A" has the archive, hidden, system, and read-only attributes set, it will not 
  1529. be found unless you specify all four of its attributes. 
  1530.  
  1531. Related information 
  1532.  
  1533. o FCS_ATTR_ constants 
  1534. o HCFSEARCH data type 
  1535. o CmnFilCreateSearch 
  1536.  
  1537.  
  1538. ΓòÉΓòÉΓòÉ 7.9. CmnFilSetExtAttribute ΓòÉΓòÉΓòÉ
  1539.  
  1540. CmnFilSetExtAttribute 
  1541.  
  1542. Purpose 
  1543.  
  1544. This function writes an extended attribute to the specified file. 
  1545.  
  1546. Syntax 
  1547.  
  1548. (BOOL)CmnFilSetExtAttribute(pchFile,
  1549.                             usAttr,
  1550.                             pchVendor,
  1551.                             pchAppl,
  1552.                             pchName,
  1553.                             pbValue,
  1554.                             usSzValue);
  1555.  
  1556. Parameters 
  1557.  
  1558. pchFile (PCHAR) - points to the name of the file containing the extended 
  1559. attributes to set. 
  1560.  
  1561. usAttr (USHORT) - points to the attribute of the extended attribute. 
  1562.  
  1563. pchVendor (PCHAR) - points to the name of the vendor whose application is 
  1564. writing the extended attribute or an FEA_ constant. 
  1565.  
  1566. pchAppl (PCHAR) - points to the name of the application which is writing the 
  1567. extended attribute. 
  1568.  
  1569. pchName (PCHAR) - points to the name of the extended attribute. 
  1570.  
  1571. pbValue (PBYTE) - points to a buffer containing the value of the extended 
  1572. attribute. 
  1573.  
  1574. usSzValue (USHORT) - specifies the size of pbValue. 
  1575.  
  1576. Returns 
  1577.  
  1578. This function returns TRUE if successful, or FALSE otherwise. 
  1579.  
  1580. Notes 
  1581.  
  1582. Use CmnFilSetExtAttribute to write an extended attribute to a file.  Since this 
  1583. function enforces the convention stated in the IBM Programming Toolkit's 
  1584. "Programming Guide", you should use CmnFilQueryExtAttribute to read the 
  1585. extended attribute when needed or insure that the code is aware of the added 
  1586. information written. 
  1587.  
  1588. Related information 
  1589.  
  1590. If an FEA_ constant is specified for pchVendor, pchAppl and pchName are 
  1591. ignored. 
  1592.  
  1593. o FEA_ constants 
  1594. o CmnFilQueryExtAttribute 
  1595.  
  1596.  
  1597. ΓòÉΓòÉΓòÉ 7.10. CmnFilSplitFilename ΓòÉΓòÉΓòÉ
  1598.  
  1599. CmnFilSplitFilename 
  1600.  
  1601. Purpose 
  1602.  
  1603. This function splits a filename into its various components. 
  1604.  
  1605. Syntax 
  1606.  
  1607. (BOOL)CmnFilSplitFilename(pchFile,pchDrive,pchPath,pchName);
  1608.  
  1609. Parameters 
  1610.  
  1611. pchFile (PCHAR) - points to the name of the file to be split 
  1612.  
  1613. pchDrive (PCHAR) - points to the buffer to receive the drive 
  1614.  
  1615. pchPath (PCHAR) - points to the buffer to receive the path 
  1616.  
  1617. pchName (PCHAR) - points to the buffer to receive the name 
  1618.  
  1619. Returns 
  1620.  
  1621. This function returns TRUE if successful, or FALSE otherwise. 
  1622.  
  1623. Notes 
  1624.  
  1625. pchDrive, pchPath, or pchName can be NULL if you are not interested in that 
  1626. component. 
  1627.  
  1628. pchDrive will always end in a colon (':'). 
  1629.  
  1630. pchPath will always end with a backslash ('\'). 
  1631.  
  1632.  
  1633. ΓòÉΓòÉΓòÉ 8. Link-list routines ΓòÉΓòÉΓòÉ
  1634.  
  1635. The purpose of this group is to provide a complete linked list implementation 
  1636. which is limited only by the amount of memory in your system. I have defined a 
  1637. list to be a set of homogeneous items; thus, each item in the list is of a 
  1638. fixed size, which is declared when the list is created.  Also, each item is 
  1639. doubly linked to provide quick access to any record from anywhere in the list. 
  1640. While this imposes an extra four bytes per record, the performance gains 
  1641. outweigh the additional memory required. 
  1642.  
  1643. Note that the links are hidden from the record; this is good in that if you 
  1644. want to have a list of integers, you do not have to define a structure to hold 
  1645. the integer and the links.  Additionally, this hides the implementation of the 
  1646. list from the developer, so if it changes (and it has before) the developer 
  1647. does not need to do anything other than recompile. 
  1648.  
  1649. Listed below are the functions which comprise this group: 
  1650.  
  1651. o CmnLstAddRecord 
  1652. o CmnLstAddUniqueRecord 
  1653. o CmnLstCopyList 
  1654. o CmnLstCreateList 
  1655. o CmnLstDeleteList 
  1656. o CmnLstDeleteRecord 
  1657. o CmnLstDestroyList 
  1658. o CmnLstMoveRecord 
  1659. o CmnLstPruneList 
  1660. o CmnLstQueryRecord 
  1661. o CmnLstQueryRecordCount 
  1662. o CmnLstQueryRelative 
  1663. o CmnLstQuickSortList 
  1664. o CmnLstSearchRecord 
  1665. o CmnLstSortList 
  1666. o CmnLstTraverseList 
  1667.  
  1668.  
  1669. ΓòÉΓòÉΓòÉ 8.1. CmnLstAddRecord ΓòÉΓòÉΓòÉ
  1670.  
  1671. CmnLstAddRecord 
  1672.  
  1673. Purpose 
  1674.  
  1675. This function adds a record to a linked list. 
  1676.  
  1677. Syntax 
  1678.  
  1679. (BOOL)CmnLstAddRecord(hclList,pvRecord,pfnSort,ppvResult,pvData);
  1680.  
  1681. Parameters 
  1682.  
  1683. hclList (HCLLIST) - handle of the linked list to add to. 
  1684.  
  1685. pvRecord (PVOID) - points to the record to add. 
  1686.  
  1687. pfnSort (PFNRECCOMP) - points to the function which defines the sort order or 
  1688. an LAR_ constant. 
  1689.  
  1690. ppvResult (PVOID *) - points to the variable which receives the pointer to the 
  1691. inserted record.  This can be NULL. 
  1692.  
  1693. pvData (PVOID) - points to application defined data which is passed to pfnSort 
  1694. as the third parameter. 
  1695.  
  1696. Returns 
  1697.  
  1698. This function returns TRUE if successful, or FALSE otherwise. 
  1699.  
  1700. Notes 
  1701.  
  1702. Use CmnLstAddRecord to add a record to a linked list in the order defined by 
  1703. pfnSort.  Since the linked list routines maintain their own copy of the 
  1704. records, ppvResult can optionally be specified to receive the pointer to the 
  1705. record within the list. pfnSort either points to a function which defines the 
  1706. placement of the record within the list or specifies an LAR_ constant. 
  1707.  
  1708. Note that if uniqueness must be enforced, you should instead use 
  1709. CmnLstAddUniqueRecord. 
  1710.  
  1711. Related information 
  1712.  
  1713. o LAR_ constants 
  1714. o HCLLIST data type 
  1715. o PFNRECCOMP function 
  1716. o CmnLstAddUniqueRecord 
  1717.  
  1718.  
  1719. ΓòÉΓòÉΓòÉ 8.2. CmnLstAddUniqueRecord ΓòÉΓòÉΓòÉ
  1720.  
  1721. CmnLstAddUniqueRecord 
  1722.  
  1723. Purpose 
  1724.  
  1725. This function adds a record to a linked list only if it did not exist 
  1726. previously. 
  1727.  
  1728. Syntax 
  1729.  
  1730. (USHORT)CmnLstAddUniqueRecord(hclList,
  1731.                               pvRecord,
  1732.                               pfnSearch,
  1733.                               pfnSort,
  1734.                               ppvResult,
  1735.                               pvData);
  1736.  
  1737. Parameters 
  1738.  
  1739. hclList (HCLLIST) - handle of the linked list to add to. 
  1740.  
  1741. pvRecord (PVOID) - points to the record to add. 
  1742.  
  1743. pfnSearch (PFNRECCOMP) - points to the function which determines the equality 
  1744. of two records. 
  1745.  
  1746. pfnSort (PFNRECCOMP) - points to the function which defines the sort order. 
  1747.  
  1748. ppvResult (PVOID *) - points to the variable which receives the pointer to the 
  1749. inserted record.  This can be NULL. 
  1750.  
  1751. pvData (PVOID) - points to application defined data which is passed to 
  1752. pfnSearch and pfnSort as the third parameter. 
  1753.  
  1754. Returns 
  1755.  
  1756. This function returns LAUR_NOERROR if successful, LAUR_EXISTS if the record 
  1757. existed in the list prior to this call, or LAUR_ERROR if an error occurred. 
  1758.  
  1759. Notes 
  1760.  
  1761. Use CmnLstAddUniqueRecord to add a record in a linked list, while guaranteeing 
  1762. uniqueness within the list.  Since the linked list routines maintain their own 
  1763. copy of the records, ppvResult can optionally be specified to receive the 
  1764. pointer to the record within the list. pfnSort either points to a function 
  1765. which defines the placement of the record within the list or specifies an LAR_ 
  1766. constant. pnfSearch points to a function which determines whether or not two 
  1767. records are equal and is required. 
  1768.  
  1769. Related information 
  1770.  
  1771. o LAR_ constants 
  1772. o HCLLIST data type 
  1773. o PFNRECCOMP function 
  1774.  
  1775.  
  1776. ΓòÉΓòÉΓòÉ 8.3. CmnLstCopyList ΓòÉΓòÉΓòÉ
  1777.  
  1778. CmnLstCopyList 
  1779.  
  1780. Purpose 
  1781.  
  1782. This function copies the contents of one list into another list. 
  1783.  
  1784. Syntax 
  1785.  
  1786. (BOOL)CmnLstCopyList(hclList,hclCopy,pfnSort,pvData);
  1787.  
  1788. Parameters 
  1789.  
  1790. hclList (HCLLIST) - handle of the linked list to copy to. 
  1791.  
  1792. hclCopy (HCLLIST) - handle of the linked list to copy from. 
  1793.  
  1794. pfnSort (PFNRECCOMP) - points to the function which defines the sort order. 
  1795.  
  1796. pvData (PVOID) - points to application defined data which is passed to pfnSort 
  1797. as the third parameter. 
  1798.  
  1799. Returns 
  1800.  
  1801. This function returns TRUE if successful, or FALSE otherwise. 
  1802.  
  1803. Notes 
  1804.  
  1805. Use CmnLstCopyList to copy the contents of one list into another.  While this 
  1806. can be used to append a list to another, this function is frequently used to 
  1807. simply copy a list so that modifications to the original list can be recovered. 
  1808.  
  1809. Related information 
  1810.  
  1811. o HCLLIST data type 
  1812.  
  1813.  
  1814. ΓòÉΓòÉΓòÉ 8.4. CmnLstCreateList ΓòÉΓòÉΓòÉ
  1815.  
  1816. CmnLstCreateList 
  1817.  
  1818. Purpose 
  1819.  
  1820. This function creates a linked list handle for use in subsequent calls to the 
  1821. CmnLst functions. 
  1822.  
  1823. Syntax 
  1824.  
  1825. (BOOL)CmnLstCreateList(usSzRecord,phclList);
  1826.  
  1827. Parameters 
  1828.  
  1829. usSzRecord (USHORT) - specifies the size of each record in the linked list. 
  1830.  
  1831. phclList (PHCLLIST) - points to the variable which receives the created linked 
  1832. list handle. 
  1833.  
  1834. Returns 
  1835.  
  1836. This function returns TRUE if successful, or FALSE otherwise. 
  1837.  
  1838. Notes 
  1839.  
  1840. Use CmnLstCreateList to create a linked list handle which can be used in other 
  1841. CmnLst functions.  Note that only linked lists of fixed record size are 
  1842. supported, although specifying the maximum size of any record and then storing 
  1843. the actual size in the record itself would work (albeit very 
  1844. memory-inefficient). 
  1845.  
  1846. Since the records do not contain the link information directly, do not specify 
  1847. this in usSzRecord. 
  1848.  
  1849. Related information 
  1850.  
  1851. o HCLLIST data type 
  1852. o CmnLstDestroyList 
  1853.  
  1854.  
  1855. ΓòÉΓòÉΓòÉ 8.5. CmnLstDeleteList ΓòÉΓòÉΓòÉ
  1856.  
  1857. CmnLstDeleteList 
  1858.  
  1859. Purpose 
  1860.  
  1861. This function deletes the contents of a linked list. 
  1862.  
  1863. Syntax 
  1864.  
  1865. (BOOL)CmnLstDeleteList(hclList);
  1866.  
  1867. Parameters 
  1868.  
  1869. hclList (HCLLIST) - handle of the linked list to delete. 
  1870.  
  1871. Returns 
  1872.  
  1873. This function returns TRUE if successful, or FALSE otherwise. 
  1874.  
  1875. Notes 
  1876.  
  1877. Use CmnLstDeleteList to delete the contents of a linked list. Note that the 
  1878. list still "exists" after this call; it is simply emptied of its contents.  To 
  1879. destroy a list, use CmnLstDestroyList. 
  1880.  
  1881. Related information 
  1882.  
  1883. o HCLLIST data type 
  1884. o CmnLstDestroyList 
  1885.  
  1886.  
  1887. ΓòÉΓòÉΓòÉ 8.6. CmnLstDeleteRecord ΓòÉΓòÉΓòÉ
  1888.  
  1889. CmnLstDeleteRecord 
  1890.  
  1891. Purpose 
  1892.  
  1893. This function deletes a record from a linked list. 
  1894.  
  1895. Syntax 
  1896.  
  1897. (BOOL)CmnLstDeleteRecord(hclList,pvRecord);
  1898.  
  1899. Parameters 
  1900.  
  1901. hclList (HCLLIST) - handle of the linked list to delete from. 
  1902.  
  1903. pvRecord (PVOID) - points to the record to delete. 
  1904.  
  1905. Returns 
  1906.  
  1907. This function returns TRUE if successful, or FALSE otherwise. 
  1908.  
  1909. Notes 
  1910.  
  1911. Use CmnLstDeleteRecord to delete a specific record from a linked list.  This 
  1912. function adjusts the links in the list and frees the memory consumed by the 
  1913. record (but does not free any memory which is pointed to by any fields in the 
  1914. record).  To delete the entire list, use CmnLstDeleteList. 
  1915.  
  1916. Related information 
  1917.  
  1918. o HCLLIST data type 
  1919. o CmnLstDeleteList 
  1920.  
  1921.  
  1922. ΓòÉΓòÉΓòÉ 8.7. CmnLstDestroyList ΓòÉΓòÉΓòÉ
  1923.  
  1924. CmnLstDestroyList 
  1925.  
  1926. Purpose 
  1927.  
  1928. This function deletes the contents of a linked list and destroys the handle to 
  1929. the linked list. 
  1930.  
  1931. Syntax 
  1932.  
  1933. (BOOL)CmnLstDestroyList(phclList);
  1934.  
  1935. Parameters 
  1936.  
  1937. phclList (PHCLLIST) - points to the variable specifying the handle of the 
  1938. linked list to delete.  On return, this variable contains NULL. 
  1939.  
  1940. Returns 
  1941.  
  1942. This function returns TRUE if successful, or FALSE otherwise. 
  1943.  
  1944. Notes 
  1945.  
  1946. Use CmnLstDestroyList to destroy a linked list handle.  All records are delete 
  1947. via a call to CmnLstDeleteList before destroying the handle. 
  1948.  
  1949. Related information 
  1950.  
  1951. o HCLLIST data type 
  1952. o CmnLstCreateList 
  1953. o CmnLstDeleteList 
  1954.  
  1955.  
  1956. ΓòÉΓòÉΓòÉ 8.8. CmnLstMoveRecord ΓòÉΓòÉΓòÉ
  1957.  
  1958. CmnLstMoveRecord 
  1959.  
  1960. Purpose 
  1961.  
  1962. This function moves a record to a position relative to another record. 
  1963.  
  1964. Syntax 
  1965.  
  1966. (BOOL)CmnLstMoveRecord(hclList,pvMove,pvWhere,sRelative);
  1967.  
  1968. Parameters 
  1969.  
  1970. hclList (HCLLIST) - handle of the linked list. 
  1971.  
  1972. pvMove (PVOID) - pointer to the record to move 
  1973.  
  1974. pvWhere (PVOID) - pointer to the record specifying the new location 
  1975.  
  1976. sRelative (SHORT) - either LQR_PREVIOUS or LQR_NEXT specifying immediately 
  1977. before or after pvWhere, respectively. 
  1978.  
  1979. Returns 
  1980.  
  1981. This function returns TRUE if successful, or FALSE otherwise. 
  1982.  
  1983. Notes 
  1984.  
  1985. Use CmnLstMoveRecord to move a record before or after another record in a 
  1986. linked list. 
  1987.  
  1988. Related information 
  1989.  
  1990. o HCLLIST data type 
  1991.  
  1992.  
  1993. ΓòÉΓòÉΓòÉ 8.9. CmnLstPruneList ΓòÉΓòÉΓòÉ
  1994.  
  1995. CmnLstPruneList 
  1996.  
  1997. Purpose 
  1998.  
  1999. This function traverses a linked list and deletes the records that meet the 
  2000. specified criteria. 
  2001.  
  2002. Syntax 
  2003.  
  2004. (BOOL)CmnLstPruneList(hclList,pvRecord,pfnSearch,pvData);
  2005.  
  2006. hclList (HCLLIST) - handle of the linked list to prune. 
  2007.  
  2008. pvSearch (PVOID) - points to a buffer specifying the search criteria.  This is 
  2009. passed to pfnSearch as the second parameter. 
  2010.  
  2011. pfnSearch (PFNRECCOMP) - points to a function which determines whether or not a 
  2012. record matches the criteria. 
  2013.  
  2014. pvData (PVOID) - points to application defined data which is passed to 
  2015. pfnSearch as the third parameter. 
  2016.  
  2017. Returns 
  2018.  
  2019. This function returns TRUE if successful, or FALSE otherwise. 
  2020.  
  2021. Notes 
  2022.  
  2023. Use CmnLstPruneList to remove only those records which meet a specific set of 
  2024. criteria from a linked list.  This is typically used after calling 
  2025. CmnLstCopyList to remove all but the records of interest from the copied list. 
  2026.  
  2027. Related information 
  2028.  
  2029. o HCLLIST data type 
  2030. o PFNRECCOMP function 
  2031. o CmnLstSearchRecord 
  2032.  
  2033.  
  2034. ΓòÉΓòÉΓòÉ 8.10. CmnLstQueryRecord ΓòÉΓòÉΓòÉ
  2035.  
  2036. CmnLstQueryRecord 
  2037.  
  2038. Purpose 
  2039.  
  2040. This function returns a pointer to the specified element in a linked list. 
  2041.  
  2042. Syntax 
  2043.  
  2044. (PVOID)CmnLstQueryRecord(hclList,sNumRecord);
  2045.  
  2046. Parameters 
  2047.  
  2048. hclList (HCLLIST) - handle of the linked list to query. 
  2049.  
  2050. sNumRecord (SHORT) - specifies the 0-based index of the record desired. 
  2051.  
  2052. Returns 
  2053.  
  2054. This function returns a pointer to the desired record if successful, or NULL 
  2055. otherwise. 
  2056.  
  2057. Notes 
  2058.  
  2059. Use CmnLstQueryRecord to query a specific record number from a linked list. 
  2060. Note that, if the record desired precedes or follows a previously queried 
  2061. record, it is much more efficient to instead use CmnLstQueryRelative.  This is 
  2062. an especially prominent condition in loop-based processing: 
  2063.  
  2064. usNumRecs=CmnLstQueryRecordCount(hclList);
  2065. for (usIndex=0; usIndex<usNumRecs; usIndex++) {
  2066.    prRecord=CmnLstQueryRecord(hclList,usIndex);
  2067.       :
  2068. } /* endfor */
  2069. should instead be coded as 
  2070.  
  2071. usNumRecs=CmnLstQueryRecordCount(hclList);
  2072. for (usIndex=0; usIndex<usNumRecs; usIndex++) {
  2073.    if (usIndex==0) {
  2074.       prRecord=CmnLstQueryRecord(hclList,0);
  2075.    } else {
  2076.       prRecord=CmnLstQueryRelative(prRecord,LQR_NEXT);
  2077.    } /* endif */
  2078.       :
  2079. } /* endfor */
  2080.  
  2081. Related information 
  2082.  
  2083. o HCLLIST data type 
  2084. o CmnLstQueryRelative 
  2085.  
  2086.  
  2087. ΓòÉΓòÉΓòÉ 8.11. CmnLstQueryRecordCount ΓòÉΓòÉΓòÉ
  2088.  
  2089. CmnLstQueryRecordCount 
  2090.  
  2091. Purpose 
  2092.  
  2093. This function queries the number of records in a linked list. 
  2094.  
  2095. Syntax 
  2096.  
  2097. (SHORT)CmnLstQueryRecordCount(hclList);
  2098.  
  2099. Parameters 
  2100.  
  2101. hclList (HCLLIST) - handle of the linked list to query. 
  2102.  
  2103. Returns 
  2104.  
  2105. This function returns the number of records in the linked list if successful, 
  2106. or LQRC_ERROR otherwise. 
  2107.  
  2108. Notes 
  2109.  
  2110. Use CmnLstQueryRecordCount to query the number of records in a linked list. 
  2111. Note that this call is expensive in terms of execution time, so it should not 
  2112. be used as the terminating condition of a loop.  Instead, store the number of 
  2113. records in a local variable prior to entering the loop and use the variable 
  2114. instead.  For example, 
  2115.  
  2116. for (usIndex=0; usIndex<CmnLstQueryRecordCount(hclList); usIndex++) {
  2117.    :
  2118. } /* endfor */
  2119. should instead be coded as 
  2120.  
  2121. usNumRecs=CmnLstQueryRecordCount(hclList);
  2122. for (usIndex=0; usIndex<usNumRecs; usIndex++) {
  2123.    :
  2124. } /* endfor */
  2125.  
  2126. Related information 
  2127.  
  2128. o HCLLIST data type 
  2129.  
  2130.  
  2131. ΓòÉΓòÉΓòÉ 8.12. CmnLstQueryRelative ΓòÉΓòÉΓòÉ
  2132.  
  2133. CmnLstQueryRelative 
  2134.  
  2135. Purpose 
  2136.  
  2137. This function queries either the previous or the next record from a specified 
  2138. record. 
  2139.  
  2140. Syntax 
  2141.  
  2142. (PVOID)CmnLstQueryRelative(pvRecord,sWhich);
  2143.  
  2144. Parameters 
  2145.  
  2146. pvRecord (PVOID) - points to the record to query. 
  2147.  
  2148. sWhich (SHORT) - specifies an LQR_ constant. 
  2149.  
  2150. Returns 
  2151.  
  2152. This function returns the relative record if successful, or NULL if the record 
  2153. prior to the head of the list or record following the tail of the list was 
  2154. specified or an error occurred. 
  2155.  
  2156. Notes 
  2157.  
  2158. Use CmnLstQueryRelative to query either the previous or the next record from a 
  2159. specified record.  While this call is very fast, it does not attempt to 
  2160. validate that the record actually belongs to any list; this responsibility is 
  2161. left to the programmer. 
  2162.  
  2163. Related information 
  2164.  
  2165. o LQR_ constants 
  2166. o HCLLIST data type 
  2167.  
  2168.  
  2169. ΓòÉΓòÉΓòÉ 8.13. CmnLstQuickSortList ΓòÉΓòÉΓòÉ
  2170.  
  2171. CmnLstQuickSortList 
  2172.  
  2173. Purpose 
  2174.  
  2175. This function sorts a linked list using a version of the "quick sort" algorithm 
  2176. modified for use with linked lists. 
  2177.  
  2178. Syntax 
  2179.  
  2180. (BOOL)CmnLstQuickSortList(hclList,pfnMedian,pfnCompare,pvData);
  2181.  
  2182. Parameters 
  2183.  
  2184. hclList (HCLLIST) - handle of the list to sort. 
  2185.  
  2186. pfnMedian (PFNRECMED) - points to the function which defines the median of the 
  2187. list. 
  2188.  
  2189. pfnCompare (PFNRECCOMP) - points to the function which determines whether or 
  2190. not two records are equal. 
  2191.  
  2192. pvData (PVOID) - points to application defined data which is passed to 
  2193. pfnMedian and pfnCompare as the third parameter. 
  2194.  
  2195. Returns 
  2196.  
  2197. This function returns TRUE if successful, or FALSE otherwise. 
  2198.  
  2199. Notes 
  2200.  
  2201. Use CmnLstQuickSortList to quickly sort a linked list. Unfortunately, since the 
  2202. records of the linked list are rarely in a contiguous block of memory, this 
  2203. function is not as quick as would be expected, although it is much faster than 
  2204. using CmnLstSortList, which uses a bubble-sort implementation. 
  2205.  
  2206. This speed does not come without its downside - this function consumes a lot of 
  2207. both stack space (due to the recursive nature of the algorithm) and heap space 
  2208. (since each partition must be stored in a temporary list). 
  2209.  
  2210. Related information 
  2211.  
  2212. o HCLLIST data type 
  2213. o PFNRECMED function 
  2214. o PFNRECCOMP function 
  2215.  
  2216.  
  2217. ΓòÉΓòÉΓòÉ 8.14. CmnLstSearchRecord ΓòÉΓòÉΓòÉ
  2218.  
  2219. CmnLstSearchRecord 
  2220.  
  2221. Purpose 
  2222.  
  2223. This function searches a linked list for a record which matches the search 
  2224. criteria. 
  2225.  
  2226. Syntax 
  2227.  
  2228. (PVOID)CmnLstSearchRecord(pvRecord,pvSearch,pfnSearch,pvData);
  2229.  
  2230. Parameters 
  2231.  
  2232. pvRecord (PVOID) - points to the first record to begin searching with. 
  2233.  
  2234. pvSearch (PVOID) - points to a buffer specifying the search criteria.  This is 
  2235. passed to pfnSearch as the second parameter. 
  2236.  
  2237. pfnSearch (PFNRECCOMP) - points to a function which determines whether or not a 
  2238. record matches the criteria. 
  2239.  
  2240. pvData (PVOID) - points to application defined data which is passed to 
  2241. pfnSearch as the third parameter. 
  2242.  
  2243. Returns 
  2244.  
  2245. This function returns a pointer to the first record on or after pvRecord which 
  2246. matches the search criteria if successful, or NULL otherwise. 
  2247.  
  2248. Notes 
  2249.  
  2250. Use CmnLstSearchRecord to search a linked list for records matching specified 
  2251. search criteria.  Typically, pvSearch is simply a pointer to a record of the 
  2252. same type that comprises the linked list with the pertinet fields initialized 
  2253. to the values to be compared against every record on or after pvRecord. 
  2254. pfnSearch then compares these fields and returns the appropriate value. 
  2255.  
  2256. Related information 
  2257.  
  2258. o HCLLIST data type 
  2259. o PFNRECCOMP function 
  2260.  
  2261.  
  2262. ΓòÉΓòÉΓòÉ 8.15. CmnLstSortList ΓòÉΓòÉΓòÉ
  2263.  
  2264. CmnLstSortList 
  2265.  
  2266. Purpose 
  2267.  
  2268. This function sorts a linked list using a version of the "bubble" sort 
  2269. algorithm modified for use with linked lists. 
  2270.  
  2271. Syntax 
  2272.  
  2273. (BOOL)CmnLstSortList(hclList,pfnSort,pvData);
  2274.  
  2275. Parameters 
  2276.  
  2277. hclList (HCLLIST) - handle of the list to sort. 
  2278.  
  2279. pfnSort (PFNRECCOMP) - points to the function which determines whether or not 
  2280. two records are equal. 
  2281.  
  2282. pvData (PVOID) - points to application defined data which is passed to pfnSort 
  2283. as the third parameter. 
  2284.  
  2285. Returns 
  2286.  
  2287. This function returns TRUE if successful, or FALSE otherwise. 
  2288.  
  2289. Notes 
  2290.  
  2291. Use CmnLstSortList to sort a linked list.  Although no extra resources are 
  2292. consumed (with the exception of stack space for local variables), the algorithm 
  2293. is extremely slow.  For sorts that require less time (and are not concerned 
  2294. with the consumption of resources), use CmnLstQuickSortList instead. 
  2295.  
  2296. Related information 
  2297.  
  2298. o HCLLIST data type 
  2299. o PFNRECCOMP function 
  2300. o CmnLstQuickSortList 
  2301.  
  2302.  
  2303. ΓòÉΓòÉΓòÉ 8.16. CmnLstTraverseList ΓòÉΓòÉΓòÉ
  2304.  
  2305. CmnLstTraverseList 
  2306.  
  2307. Purpose 
  2308.  
  2309. This function traverses a linked list. 
  2310.  
  2311. Syntax 
  2312.  
  2313. (BOOL)CmnLstTraverseList(hclList,pfnFunc,pvData);
  2314.  
  2315. Parameters 
  2316.  
  2317. hclList (HCLLIST) - handle of the list to traverse. 
  2318.  
  2319. pfnFunc (PFNRECFUNC) - points to a function which is called for each record in 
  2320. the linked list. 
  2321.  
  2322. pvData (PVOID) - points to application defined data which is passed to pfnFunc 
  2323. as the second parameter. 
  2324.  
  2325. Returns 
  2326.  
  2327. This function returns TRUE if successful, or FALSE otherwise. 
  2328.  
  2329. Notes 
  2330.  
  2331. Use CmnLstTraverseList to traverse a linked list for debugging purposes.  For 
  2332. every record in the linked list, pfnFunc is called, giving the application the 
  2333. ability to write the contents of the record to the screen, a file, a 
  2334. communication port, etc..  When used in conjunction with CmnDbgWriteRecord, a 
  2335. linked list dump can be easily generated with minimal code. 
  2336.  
  2337. Related information 
  2338.  
  2339. o HCLLIST data type 
  2340. o PFNRECFUNC function 
  2341. o CmnDbgWriteRecord 
  2342.  
  2343.  
  2344. ΓòÉΓòÉΓòÉ 9. Memory allocation routines ΓòÉΓòÉΓòÉ
  2345.  
  2346. The purpose of this group is to provide memory allocation routines which are 
  2347. easy to use and provide functionality above that provided by the C run-time 
  2348. library.  The routines use the DosSubAlloc and DosSubFree kernel functions for 
  2349. the suballocation of the individual heaps, so there are no free lists that are 
  2350. maintained by these routines (less code means less bugs). 
  2351.  
  2352. A useful function is the CmnQueryHandleInfo function which returns the total 
  2353. amount of memory in use by a memory manager handle. 
  2354.  
  2355. Listed below are the functions which comprise this group: 
  2356.  
  2357. o CmnMemAllocate 
  2358. o CmnMemFree 
  2359. o CmnMemInitialize 
  2360. o CmnMemQueryMemSize 
  2361. o CmnMemReset 
  2362. o CmnMemTerminate 
  2363.  
  2364.  
  2365. ΓòÉΓòÉΓòÉ 9.1. CmnMemAllocate ΓòÉΓòÉΓòÉ
  2366.  
  2367. CmnMemAllocate 
  2368.  
  2369. Purpose 
  2370.  
  2371. This function allocates a block of memory of a specified size. 
  2372.  
  2373. Syntax 
  2374.  
  2375. (MEMERROR)CmnMemAllocate(hcmMem,ulSzBuf,ppvBuf);
  2376.  
  2377. Parameters 
  2378.  
  2379. hcmMem (HCMMEM) - handle of the memory manager instance. 
  2380.  
  2381. ulSzBuf (ULONG) - specifies the size of the memory block requested. 
  2382.  
  2383. ppvBuf (PVOID *) - points to the variable which receives the pointer to the 
  2384. allocated memory. 
  2385.  
  2386. Returns 
  2387.  
  2388. This function returns one of the following values: 
  2389.  
  2390. MEM_ERR_NOERROR 
  2391. MEM_ERR_BADHANDLE 
  2392. MEM_ERR_NOMEMORY 
  2393. MEM_ERR_SIZETOOLARGE 
  2394.  
  2395. Notes 
  2396.  
  2397. The algorithm used by the function is to attempt to allocate the specified 
  2398. amount of memory from those heaps which already are being used.  If the request 
  2399. cannot be satisfied and there is at least one heap slot that is not in use, 
  2400. then a new heap is created and the memory requested is allocated from the new 
  2401. heap. 
  2402.  
  2403. Related information 
  2404.  
  2405. o HCMMEM data type 
  2406. o CmnMemFree 
  2407. o CmnMemReset 
  2408.  
  2409.  
  2410. ΓòÉΓòÉΓòÉ 9.2. CmnMemFree ΓòÉΓòÉΓòÉ
  2411.  
  2412. CmnMemFree 
  2413.  
  2414. Purpose 
  2415.  
  2416. This function frees a block of memory previously allocated with CmnMemAllocate. 
  2417.  
  2418. Syntax 
  2419.  
  2420. (MEMERROR)CmnMemFree(hcmMem,pvBuf);
  2421.  
  2422. Parameters 
  2423.  
  2424. hcmMem (HCMMEM) - handle of the memory manager instance. 
  2425.  
  2426. pvBuf (PVOID) - pointer to the memory block to free 
  2427.  
  2428. Returns 
  2429.  
  2430. This function returns one of the following values: 
  2431.  
  2432. MEM_ERR_NOERROR 
  2433. MEM_ERR_BADHANDLE 
  2434. MEM_ERR_BADPOINTER 
  2435. MEM_ERR_ERROR 
  2436.  
  2437. Notes 
  2438.  
  2439. Because of the dynamic committal strategy used by the memory routines, a 
  2440. reference count is maintained for each heap that is in use and it is updated 
  2441. whenever either CmnMemAllocate or CmnMemFree is called. When this function 
  2442. determines that the reference count is zero, it deallocates the memory used by 
  2443. the heap and marks the heap as "empty". 
  2444.  
  2445. Related information 
  2446.  
  2447. o HCMMEM data type 
  2448. o CmnMemAllocate 
  2449. o CmnMemReset 
  2450.  
  2451.  
  2452. ΓòÉΓòÉΓòÉ 9.3. CmnMemInitialize ΓòÉΓòÉΓòÉ
  2453.  
  2454. CmnMemInitialize 
  2455.  
  2456. Purpose 
  2457.  
  2458. This function creates an instance of the memory manager. 
  2459.  
  2460. Syntax 
  2461.  
  2462. (MEMERROR)CmnMemInitialize(pcmiInfo,phcmMem);
  2463.  
  2464. Parameters 
  2465.  
  2466. pcmiInfo (PCMMEMINFO) - points to a CMMEMINFO structure which describes the 
  2467. desired characteristics of the instance.  If NULL, the defaults are used (see 
  2468. below). 
  2469.  
  2470. phcmMem (PHCMMEM) - points to the variable which receives the created instance 
  2471. of the memory manager. 
  2472.  
  2473. Returns 
  2474.  
  2475. This function returns one of the following values: 
  2476.  
  2477. MEM_ERR_NOERROR 
  2478. MEM_ERR_NOMEMORY 
  2479.  
  2480. Notes 
  2481.  
  2482. The heaps are subdivided by the CmnMemAllocate and CmnMemFree routines using 
  2483. the DosSubAlloc and DosSubFree APIs.  Allowing for housekeeping data kept by 
  2484. both the system and the memory manager, the amount of allocatable memory will 
  2485. be less than the value of ulSzHeaps (how much less depends on the number of 
  2486. allocations have been made from a particular heap). 
  2487.  
  2488. Related information 
  2489.  
  2490. o HCMMEM data type 
  2491. o CMMEMINFO data type 
  2492. o CmnMemReset 
  2493. o CmnMemTerminate 
  2494.  
  2495.  
  2496. ΓòÉΓòÉΓòÉ 9.4. CmnMemQueryMemSize ΓòÉΓòÉΓòÉ
  2497.  
  2498. CmnMemQueryMemSize 
  2499.  
  2500. Purpose 
  2501.  
  2502. This function returns the size of the specified memory block. 
  2503.  
  2504. Syntax 
  2505.  
  2506. (ULONG)CmnMemQueryMemSize(pvBuf);
  2507.  
  2508. Parameters 
  2509.  
  2510. pvBuf (PVOID) - points to a memory block previously allocated by 
  2511. CmnMemAllocate. 
  2512.  
  2513. Returns 
  2514.  
  2515. This function returns the size of the memory block specified. 
  2516.  
  2517. Notes 
  2518.  
  2519. This function does no validity checks to insure that pvBuf was indeed allocated 
  2520. with CmnMemAllocate. 
  2521.  
  2522. Related information 
  2523.  
  2524. o CmnMemAllocate 
  2525.  
  2526.  
  2527. ΓòÉΓòÉΓòÉ 9.5. CmnMemReset ΓòÉΓòÉΓòÉ
  2528.  
  2529. CmnMemReset 
  2530.  
  2531. Purpose 
  2532.  
  2533. This function resets the specified instance of the memory manager to its 
  2534. initial state. 
  2535.  
  2536. Syntax 
  2537.  
  2538. (MEMERROR)CmnMemReset(hcmMem);
  2539.  
  2540. Parameters 
  2541.  
  2542. hcmMem (HCMMEM) - handle of the memory manager instance. 
  2543.  
  2544. Returns 
  2545.  
  2546. This function returns one of the following values: 
  2547.  
  2548. MEM_ERR_NOERROR 
  2549. MEM_ERR_BADHANDLE 
  2550.  
  2551. Notes 
  2552.  
  2553. This function returns all memory to the system and reinitializes all of the 
  2554. internal heaps to the "empty" state. 
  2555.  
  2556. Related information 
  2557.  
  2558. o HCMMEM data type 
  2559. o CmnMemInitialize 
  2560. o CmnMemTerminate 
  2561.  
  2562.  
  2563. ΓòÉΓòÉΓòÉ 9.6. CmnMemTerminate ΓòÉΓòÉΓòÉ
  2564.  
  2565. CmnMemTerminate 
  2566.  
  2567. Purpose 
  2568.  
  2569. This function destroys the specified instance of the memory manager. 
  2570.  
  2571. Syntax 
  2572.  
  2573. (MEMERROR)CmnMemTerminate(phcmMem);
  2574.  
  2575. Parameters 
  2576.  
  2577. phcmMem (PHCMMEM) - points to the variable specifying the handle of the memory 
  2578. manager instance to destroy.  On return, this contains NULL. 
  2579.  
  2580. Returns 
  2581.  
  2582. This function returns one of the following values: 
  2583.  
  2584. MEM_ERR_NOERROR 
  2585. MEM_ERR_BADHANDLE 
  2586. MEM_ERR_ERROR 
  2587.  
  2588. Notes 
  2589.  
  2590. This function first calls CmnMemReset to return all allocated memory to the 
  2591. system. 
  2592.  
  2593. Related information 
  2594.  
  2595. o HCMMEM data type 
  2596. o CmnMemInitialize 
  2597. o CmnMemReset 
  2598.  
  2599.  
  2600. ΓòÉΓòÉΓòÉ 10. Object handling routines ΓòÉΓòÉΓòÉ
  2601.  
  2602. The purpose of this group is to provide object handling routines.  An "object" 
  2603. is an abstract concept that is defined by an application.  No structure is 
  2604. imposed on the objects except with regards to their names. Because of this, the 
  2605. APIs are limited in the functionality they can provide. 
  2606.  
  2607. I have hopes of modifying this group to allow for objects that are distributed 
  2608. across a network, but am not sure that I will have the time or the resources to 
  2609. fulfill this vision. 
  2610.  
  2611. Listed below are the functions which comprise this group: 
  2612.  
  2613. o CmnObjCreateObject 
  2614. o CmnObjDestroyObject 
  2615. o CmnObjInitialize 
  2616. o CmnObjObjectFromName 
  2617. o CmnObjQueryObject 
  2618. o CmnObjQueryObjectData 
  2619. o CmnObjReset 
  2620. o CmnObjSetObjectData 
  2621. o CmnObjTerminate 
  2622.  
  2623.  
  2624. ΓòÉΓòÉΓòÉ 10.1. CmnObjCreateObject ΓòÉΓòÉΓòÉ
  2625.  
  2626. CmnObjCreateObject 
  2627.  
  2628. Purpose 
  2629.  
  2630. This function creates a new object. 
  2631.  
  2632. Syntax 
  2633.  
  2634. (OBJERROR)CmnObjCreateObject(hcoParent,pchName,phcoResult)
  2635.  
  2636. Parameters 
  2637.  
  2638. hcoParent (HCOOBJECT) - handle of the parent object. 
  2639.  
  2640. pchName (PCHAR) - points to the desired subname of the object. 
  2641.  
  2642. phcoResult (PHCOOBJECT) - points to the variable that receives the newly 
  2643. created object handle. 
  2644.  
  2645. Returns 
  2646.  
  2647. This function returns one of the following values: 
  2648.  
  2649. OBJ_ERR_NOERROR 
  2650. OBJ_ERR_BADARGUMENT 
  2651. OBJ_ERR_BADHANDLE 
  2652. OBJ_ERR_BADNAME 
  2653. OBJ_ERR_INITFAILED 
  2654. OBJ_ERR_NOMEMORY 
  2655. OBJ_ERR_NOTROOT 
  2656.  
  2657. Notes 
  2658.  
  2659. Use CmnObjCreateObject to create a new object whose parent is specified by 
  2660. hcoParent.  The "subname" can contain any characters except backslashes (see 
  2661. CmnObjObjectFromName). 
  2662.  
  2663. Related information 
  2664.  
  2665. o HCOOBJECT data type 
  2666. o CmnObjDestroyObject 
  2667.  
  2668.  
  2669. ΓòÉΓòÉΓòÉ 10.2. CmnObjDestroyObject ΓòÉΓòÉΓòÉ
  2670.  
  2671. CmnObjDestroyObject 
  2672.  
  2673. Purpose 
  2674.  
  2675. This function destroys an object. 
  2676.  
  2677. Syntax 
  2678.  
  2679. (OBJERROR)CmnObjDestroyObject(phcoObject)
  2680.  
  2681. Parameters 
  2682.  
  2683. phcoObject (PHCOOBJECT) - points to the variable specifying the handle of the 
  2684. object to destroy.  On return, this variable contains NULL 
  2685.  
  2686. Returns 
  2687.  
  2688. This function returns one of the following values: 
  2689.  
  2690. OBJ_ERR_NOERROR 
  2691. OBJ_ERR_BADARGUMENT 
  2692. OBJ_ERR_BADHANDLE 
  2693. OBJ_ERR_NOMEMORY 
  2694. OBJ_ERR_NOTROOT 
  2695. OBJ_ERR_OBJECTCORRUPTED 
  2696.  
  2697. Notes 
  2698.  
  2699. Use CmnObjDestroyObject to destroy an object previously created with 
  2700. CmnObjCreateObject.  Any data (see CmnObjSetObjectData) is disposed of and the 
  2701. memory is returned to the system.  It is an error if the root object is 
  2702. specified in phcoObject. 
  2703.  
  2704. For objects with children, the children become adopted children of the object's 
  2705. parent. 
  2706.  
  2707. Related information 
  2708.  
  2709. o HCOOBJECT data type 
  2710. o CmnObjCreateObject 
  2711.  
  2712.  
  2713. ΓòÉΓòÉΓòÉ 10.3. CmnObjInitialize ΓòÉΓòÉΓòÉ
  2714.  
  2715. CmnObjInitialize 
  2716.  
  2717. Purpose 
  2718.  
  2719. This function initializes an instance of the object manager and creates the 
  2720. root object. 
  2721.  
  2722. Syntax 
  2723.  
  2724. (OBJERROR)CmnObjInitialize(pcoriInfo,phcoRoot)
  2725.  
  2726. Parameters 
  2727.  
  2728. pcoriInfo (PCOROOTINFO) - points to a COROOTINFO structure containing desired 
  2729. characteristics of the root object.  If NULL, the default values are used. 
  2730.  
  2731. phcoRoot (PHCOOBJECT) - points to the variable to receive the handle of the 
  2732. root object. 
  2733.  
  2734. Returns 
  2735.  
  2736. This function returns one of the following values: 
  2737.  
  2738. OBJ_ERR_NOERROR 
  2739. OBJ_ERR_BADNAME 
  2740. OBJ_ERR_INITFAILED 
  2741. OBJ_ERR_NOMEMORY 
  2742.  
  2743. Notes 
  2744.  
  2745. Use CmnObjInitialize to create a root object handle which can be used in 
  2746. subsequent calls to other object functions.  The achServer field of the 
  2747. COROOTINFO structure is unused at this time and could possibly disappear in the 
  2748. future. 
  2749.  
  2750. Related information 
  2751.  
  2752. o HCOOBJECT data type 
  2753. o CmnObjTerminate 
  2754.  
  2755.  
  2756. ΓòÉΓòÉΓòÉ 10.4. CmnObjObjectFromName ΓòÉΓòÉΓòÉ
  2757.  
  2758. CmnObjObjectFromName 
  2759.  
  2760. Purpose 
  2761.  
  2762. This function finds an object with a given name. 
  2763.  
  2764. Syntax 
  2765.  
  2766. (OBJERROR)CmnObjObjectFromName(hcoObject,pchName,phcoResult)
  2767.  
  2768. Parameters 
  2769.  
  2770. hcoObject (HCOOBJECT) - handle of the object to search from. 
  2771.  
  2772. pchName (PCHAR) - points to the name of the object to search for. 
  2773.  
  2774. phcoResult (PHCOOBJECT) - points to the variable which receives the handle of 
  2775. the object if found. 
  2776.  
  2777. Returns 
  2778.  
  2779. This function returns one of the following values: 
  2780.  
  2781. OBJ_ERR_NOERROR 
  2782. OBJ_ERR_BADHANDLE 
  2783. OBJ_ERR_NOTFOUND 
  2784.  
  2785. Notes 
  2786.  
  2787. The object name structure is extremely similar to the directory/filename 
  2788. structure of the file system.  Each object has a subname which, when combined 
  2789. with the subnames of its ancestors, produces a fully qualified name; each 
  2790. subname is separated by a backslash. 
  2791.  
  2792. pchName can specify either a name relative to the specified object, or it can 
  2793. specify an absolute name by prepending it with a backslash. Also, as with the 
  2794. file system, you can specify "." and ".." to indicate the current object and 
  2795. its parent, respectively. 
  2796.  
  2797. For example, if you have the following objects with the given relationships 
  2798.  
  2799.                         root
  2800.                         /  \
  2801.                  child1      child2
  2802.                  /  |          |  \
  2803.             child3 child4  child5 child6
  2804.  
  2805. the following calls return the indicated results: 
  2806.  
  2807. CmnObjObjectFromName(root,"child1\\child4") returns child4. 
  2808.  
  2809. CmnObjObjectFromName(child3,"..\\..\\child2\\child5") returns child5. 
  2810.  
  2811. CmnObjObjectFromName(child4,"..\\child3\\..\\child4\\..\\..") returns root. 
  2812.  
  2813. CmnObjObjectFromName(root,"..") returns an error. 
  2814.  
  2815. Related information 
  2816.  
  2817. o HCOOBJECT data type 
  2818. o CmnObjQueryObject 
  2819.  
  2820.  
  2821. ΓòÉΓòÉΓòÉ 10.5. CmnObjQueryObject ΓòÉΓòÉΓòÉ
  2822.  
  2823. CmnObjQueryObject 
  2824.  
  2825. Purpose 
  2826.  
  2827. This function returns an object related to the specified object in the 
  2828. specified way. 
  2829.  
  2830. Syntax 
  2831.  
  2832. (OBJERROR)CmnObjQueryObject(hcoObject,sQuery,phcoResult)
  2833.  
  2834. Parameters 
  2835.  
  2836. hcoObject (HCOOBJECT) - handle of the object to query. 
  2837.  
  2838. sQuery (SHORT) - specifies an OQO constant. 
  2839.  
  2840. phcoResult (PHCOOBJECT) - points to the variable which receives the related 
  2841. object handle. 
  2842.  
  2843. Returns 
  2844.  
  2845. This function returns one of the following values: 
  2846.  
  2847. OBJ_ERR_NOERROR 
  2848. OBJ_ERR_BADARGUMENT 
  2849. OBJ_ERR_BADHANDLE 
  2850. OBJ_ERR_NOTROOT 
  2851.  
  2852. Notes 
  2853.  
  2854. When used with the usNumChildren field of the COOBJECTINFO structure returned 
  2855. by CmnQueryHandleInfo, the OQO_FIRSTCHILD and OQO_NEXT constants can be used to 
  2856. traverse the entire object tree. 
  2857.  
  2858. Note that calling this function with OQO_ROOT is faster that calling 
  2859. CmnObjObjectFromName with "\\", because the latter calls this function. 
  2860.  
  2861. Related information 
  2862.  
  2863. o HCOOBJECT data type 
  2864. o CmnObjObjectFromName 
  2865. o CmnObjQueryObjectData 
  2866. o CmnQueryHandleInfo 
  2867.  
  2868.  
  2869. ΓòÉΓòÉΓòÉ 10.6. CmnObjQueryObjectData ΓòÉΓòÉΓòÉ
  2870.  
  2871. CmnObjQueryObjectData 
  2872.  
  2873. Purpose 
  2874.  
  2875. This function returns the object-specific data. 
  2876.  
  2877. Syntax 
  2878.  
  2879. (OBJERROR)CmnObjQueryObjectData(hcoObject,pvBuffer,pulSzBuf)
  2880.  
  2881. Parameters 
  2882.  
  2883. hcoObject (HCOOBJECT) - handle of the object to query. 
  2884.  
  2885. pvBuffer (PVOID) - points to the buffer to receive the data. If NULL, this 
  2886. function will return the number of bytes needed in pulSzBuf. 
  2887.  
  2888. pulSzBuf (PULONG) - points to the variable containing the size of the buffer 
  2889. pointed to by pvBuffer.  On exit, this variable contains the number of bytes 
  2890. written. 
  2891.  
  2892. Returns 
  2893.  
  2894. This function returns one of the following values: 
  2895.  
  2896. OBJ_ERR_NOERROR 
  2897. OBJ_ERR_BADHANDLE 
  2898.  
  2899. Notes 
  2900.  
  2901. This function should not be confused with CmnQueryHandleInfo, which returns 
  2902. information about the object's current attributes, which does include the 
  2903. object data.  Instead, this function returns only the data that was previously 
  2904. set with the CmnObjSetObjectData function. 
  2905.  
  2906. Related information 
  2907.  
  2908. o HCOOBJECT data type 
  2909. o CmnQueryHandleInfo 
  2910. o CmnObjSetObjectData 
  2911.  
  2912.  
  2913. ΓòÉΓòÉΓòÉ 10.7. CmnObjReset ΓòÉΓòÉΓòÉ
  2914.  
  2915. CmnObjReset 
  2916.  
  2917. Purpose 
  2918.  
  2919. This function deletes all children of the specified root object. 
  2920.  
  2921. Syntax 
  2922.  
  2923. (OBJERROR)CmnObjReset(hcoRoot)
  2924.  
  2925. Parameters 
  2926.  
  2927. hcoRoot (HCOOBJECT) - handle of the root object. 
  2928.  
  2929. Returns 
  2930.  
  2931. This function returns one of the following values: 
  2932.  
  2933. OBJ_ERR_NOERROR 
  2934. OBJ_ERR_BADARGUMENT 
  2935. OBJ_ERR_BADHANDLE 
  2936. OBJ_ERR_BADROOTHANDLE 
  2937. OBJ_ERR_NOTROOT 
  2938.  
  2939. Notes 
  2940.  
  2941. Use CmnObjReset to delete all children objects and their object-data and return 
  2942. the memory to the system. 
  2943.  
  2944. Related information 
  2945.  
  2946. o HCOOBJECT data type 
  2947. o CmnObjTerminate 
  2948.  
  2949.  
  2950. ΓòÉΓòÉΓòÉ 10.8. CmnObjSetObjectData ΓòÉΓòÉΓòÉ
  2951.  
  2952. CmnObjSetObjectData 
  2953.  
  2954. Purpose 
  2955.  
  2956. This function sets the object-specific data. 
  2957.  
  2958. Syntax 
  2959.  
  2960. (OBJERROR)CmnObjSetObjectData(hcoObject,pvBuffer,ulSzBuf)
  2961.  
  2962. Parameters 
  2963.  
  2964. hcoObject (HCOOBJECT) - handle of the object. 
  2965.  
  2966. pvBuffer (PVOID) - points to the buffer from which the data is copied. 
  2967.  
  2968. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pvBuffer. 
  2969.  
  2970. Returns 
  2971.  
  2972. This function returns one of the following values: 
  2973.  
  2974. OBJ_ERR_NOERROR 
  2975. OBJ_ERR_BADARGUMENT 
  2976. OBJ_ERR_BADHANDLE 
  2977. OBJ_ERR_NOMEMORY 
  2978. OBJ_ERR_NOTROOT 
  2979. OBJ_ERR_SIZETOOLARGE 
  2980.  
  2981. Notes 
  2982.  
  2983. Use CmnObjSetObjectData to set any object-specific data which can then be later 
  2984. queried using CmnObjQueryObjectData or by examining the pvData field of the 
  2985. COOBJECTINFO structure returned from CmnQueryHandleInfo. 
  2986.  
  2987. Related information 
  2988.  
  2989. o HCOOBJECT data type 
  2990. o CmnObjQueryObjectData 
  2991. o CmnQueryHandleInfo 
  2992.  
  2993.  
  2994. ΓòÉΓòÉΓòÉ 10.9. CmnObjTerminate ΓòÉΓòÉΓòÉ
  2995.  
  2996. CmnObjTerminate 
  2997.  
  2998. Purpose 
  2999.  
  3000. This function destroys the object manager instance. 
  3001.  
  3002. Syntax 
  3003.  
  3004. (OBJERROR)CmnObjTerminate(phcoRoot)
  3005.  
  3006. Parameters 
  3007.  
  3008. phcoRoot (PHCOOBJECT) - handle of the root object. 
  3009.  
  3010. Returns 
  3011.  
  3012. This function returns one of the following values: 
  3013.  
  3014. OBJ_ERR_NOERROR 
  3015. OBJ_ERR_BADARGUMENT 
  3016. OBJ_ERR_BADHANDLE 
  3017. OBJ_ERR_BADROOTHANDLE 
  3018. OBJ_ERR_NOTROOT 
  3019.  
  3020. Notes 
  3021.  
  3022. Use CmnObjTerminate to destroy the root's children (via CmnObjReset) and to 
  3023. destroy the root object. 
  3024.  
  3025. Related information 
  3026.  
  3027. o HCOOBJECT data type 
  3028. o CmnObjInitialize 
  3029. o CmnObjReset 
  3030.  
  3031.  
  3032. ΓòÉΓòÉΓòÉ 11. Set routines ΓòÉΓòÉΓòÉ
  3033.  
  3034. The purpose of this group is to provide a complete set implementation. Unlike 
  3035. some programming languages, the sets are not limited to 256 elements but 
  3036. instead have a limit of approximately 520000 elements per set (for the 32-bit 
  3037. version of the library, this could conceivably be raised significantly, since 
  3038. the limit mentioned is due to the segmented architecture of 16-bit programs. 
  3039. If you are developing a 32-bit application and have a need for a higher limit, 
  3040. please let me know). Due to the fact that the sets are (currently) implemented 
  3041. as bit-maps, you should also find the performance to be very good. 
  3042.  
  3043. Listed below are the functions which comprise this group: 
  3044.  
  3045. o CmnSetClearElement 
  3046. o CmnSetClearSet 
  3047. o CmnSetCombineSets 
  3048. o CmnSetCreateSet 
  3049. o CmnSetDestroySet 
  3050. o CmnSetFindElement 
  3051. o CmnSetIntersectSets 
  3052. o CmnSetInvertElement 
  3053. o CmnSetInvertSet 
  3054. o CmnSetQueryElement 
  3055. o CmnSetQueryEqualSets 
  3056. o CmnSetSetElement 
  3057. o CmnSetSetSet 
  3058.  
  3059.  
  3060. ΓòÉΓòÉΓòÉ 11.1. CmnSetClearElement ΓòÉΓòÉΓòÉ
  3061.  
  3062. CmnSetClearElement 
  3063.  
  3064. Purpose 
  3065.  
  3066. This function clears an element in a set. 
  3067.  
  3068. Syntax 
  3069.  
  3070. (BOOL)CmnSetClearElement(hcsSet,ulElement);
  3071.  
  3072. Parameters 
  3073.  
  3074. hcsSet (HCSSET) - handle of the set. 
  3075.  
  3076. ulElement (ULONG) - specifies the 0-based element to clear. 
  3077.  
  3078. Returns 
  3079.  
  3080. This function returns TRUE if successful, or FALSE otherwise. 
  3081.  
  3082. Notes 
  3083.  
  3084. Use CmnSetClearElement to clear an element from a set.  To clear all of the 
  3085. elements in a set, use CmnSetClearSet. 
  3086.  
  3087. Related information 
  3088.  
  3089. o HCSSET data type 
  3090. o CmnSetClearSet 
  3091.  
  3092.  
  3093. ΓòÉΓòÉΓòÉ 11.2. CmnSetClearSet ΓòÉΓòÉΓòÉ
  3094.  
  3095. CmnSetClearSet 
  3096.  
  3097. Purpose 
  3098.  
  3099. This function clears all of the elements in a set. 
  3100.  
  3101. Syntax 
  3102.  
  3103. (BOOL)CmnSetClearSet(hcsSet);
  3104.  
  3105. Parameters 
  3106.  
  3107. hcsSet (HCSSET) - handle of the set to clear. 
  3108.  
  3109. Returns 
  3110.  
  3111. This function returns TRUE if successful, or FALSE otherwise. 
  3112.  
  3113. Notes 
  3114.  
  3115. Use CmnSetClearSet to clear all of the elements in a set. To clear a single 
  3116. element, use CmnSetClearElement. 
  3117.  
  3118. This call is fast in terms of execution time. 
  3119.  
  3120. Related information 
  3121.  
  3122. o HCSSET data type 
  3123. o CmnSetClearElement 
  3124.  
  3125.  
  3126. ΓòÉΓòÉΓòÉ 11.3. CmnSetCombineSets ΓòÉΓòÉΓòÉ
  3127.  
  3128. CmnSetCombineSets 
  3129.  
  3130. Purpose 
  3131.  
  3132. This function creates a new set containing all of the elements set from two 
  3133. sets. 
  3134.  
  3135. Syntax 
  3136.  
  3137. (HCSSET)CmnSetCombineSets(hcsSet1,hcsSet2);
  3138.  
  3139. Parameters 
  3140.  
  3141. hcsSet1 (HCSSET) - handle of a set to combine. 
  3142.  
  3143. hcsSet2 (HCSSET) - handle of a set to combine. 
  3144.  
  3145. Returns 
  3146.  
  3147. This function returns a handle to the resulting set if successful, or NULL 
  3148. otherwise. 
  3149.  
  3150. Notes 
  3151.  
  3152. Use CmnSetCombineSets to perform a union of two sets.  Note that the two sets 
  3153. do not have to be of equal size. 
  3154.  
  3155. To perform an intersection of two sets, use CmnSetIntersectSets. 
  3156.  
  3157. Related information 
  3158.  
  3159. o HCSSET data type 
  3160. o CmnSetIntersectSets 
  3161.  
  3162.  
  3163. ΓòÉΓòÉΓòÉ 11.4. CmnSetCreateSet ΓòÉΓòÉΓòÉ
  3164.  
  3165. CmnSetCreateSet 
  3166.  
  3167. Purpose 
  3168.  
  3169. This function creates a new set handle for use in subsequent calls to the 
  3170. CmnSet functions. 
  3171.  
  3172. Syntax 
  3173.  
  3174. (BOOL)CmnSetCreateSet(ulMaxElems,phcsSet);
  3175.  
  3176. Parameters 
  3177.  
  3178. ulMaxElems (ULONG) - specifies the maximum number of elements the set is to 
  3179. hold. 
  3180.  
  3181. phcsSet (PHCSSET) - points to the variable to receive the created set handle. 
  3182.  
  3183. Returns 
  3184.  
  3185. This function returns TRUE if successful, or FALSE otherwise. 
  3186.  
  3187. Notes 
  3188.  
  3189. Use CmnSetCreateSet to create a new set for use in subsequent calls to the 
  3190. CmnSet functions.  Note that there is currently an upper limit of 522240 for 
  3191. ulMaxElems. 
  3192.  
  3193. Related information 
  3194.  
  3195. o HCSSET data type 
  3196. o CmnSetDestroySet 
  3197.  
  3198.  
  3199. ΓòÉΓòÉΓòÉ 11.5. CmnSetDestroySet ΓòÉΓòÉΓòÉ
  3200.  
  3201. CmnSetDestroySet 
  3202.  
  3203. Purpose 
  3204.  
  3205. This function destroys a set handle. 
  3206.  
  3207. Syntax 
  3208.  
  3209. (BOOL)CmnSetDestroySet(phcsSet);
  3210.  
  3211. Parameters 
  3212.  
  3213. phcsSet (PHCSSET) - points to the variable containing the handle of the set to 
  3214. destroy.  On return, the variable contains NULL. 
  3215.  
  3216. Returns 
  3217.  
  3218. This function returns TRUE if successful, or FALSE otherwise. 
  3219.  
  3220. Notes 
  3221.  
  3222. Use CmnSetDestroySet to destroy a handle to a set and return any memory to the 
  3223. system. 
  3224.  
  3225. Related information 
  3226.  
  3227. o HCSSET data type 
  3228. o CmnSetCreateSet 
  3229.  
  3230.  
  3231. ΓòÉΓòÉΓòÉ 11.6. CmnSetFindElement ΓòÉΓòÉΓòÉ
  3232.  
  3233. CmnSetFindElement 
  3234.  
  3235. Purpose 
  3236.  
  3237. This function finds the nth element in a set that is either set or clear. 
  3238.  
  3239. Syntax 
  3240.  
  3241. (LONG)CmnSetFindElement(hcsSet,ulNumber,usType)
  3242.  
  3243. Parameters 
  3244.  
  3245. hcsSet (HCSSET) - handle of the set. 
  3246.  
  3247. ulNumber (ULONG) - specifies the nth element to find. 
  3248.  
  3249. usType (USHORT) - specifies a SFE_ constant. 
  3250.  
  3251. Returns 
  3252.  
  3253. This function returns the index of the element found, SFE_NOTFOUND if the nth 
  3254. element was not found, or SFE_ERROR if an error occurred. 
  3255.  
  3256. Notes 
  3257.  
  3258. Use CmnSetFindElement to find the nth element set or clear in a set (i.e. the 
  3259. 3rd clear element). 
  3260.  
  3261. Related information 
  3262.  
  3263. o HCSSET data type 
  3264. o CmnSetClearElement 
  3265. o CmnSetSetElement 
  3266.  
  3267.  
  3268. ΓòÉΓòÉΓòÉ 11.7. CmnSetIntersectSets ΓòÉΓòÉΓòÉ
  3269.  
  3270. CmnSetIntersectSets 
  3271.  
  3272. Purpose 
  3273.  
  3274. This function creates a new set containing elements that were set in both of 
  3275. the specified sets. 
  3276.  
  3277. Syntax 
  3278.  
  3279. (HCSSET)CmnSetIntersectSets(hcsSet1,hcsSet2);
  3280.  
  3281. Parameters 
  3282.  
  3283. hcsSet1 (HCSSET) - handle of a set to intersect. 
  3284.  
  3285. hcsSet2 (HCSSET) - handle of a set to intersect. 
  3286.  
  3287. Returns 
  3288.  
  3289. This function returns a handle to the resulting set if successful, or NULL 
  3290. otherwise. 
  3291.  
  3292. Notes 
  3293.  
  3294. Use CmnSetIntersectSets to perform an intersection of two sets. Note that the 
  3295. two sets do not have to be of equal size. 
  3296.  
  3297. Related information 
  3298.  
  3299. o HCSSET data type 
  3300. o CmnSetCombineSets 
  3301.  
  3302.  
  3303. ΓòÉΓòÉΓòÉ 11.8. CmnSetInvertElement ΓòÉΓòÉΓòÉ
  3304.  
  3305. CmnSetInvertElement 
  3306.  
  3307. Purpose 
  3308.  
  3309. This function inverts the state of an element in a set. 
  3310.  
  3311. Syntax 
  3312.  
  3313. (BOOL)CmnSetInvertElement(hcsSet,ulElement);
  3314.  
  3315. Parameters 
  3316.  
  3317. hcsSet (HCSSET) - handle of the set. 
  3318.  
  3319. ulElement (ULONG) - specifies the 0-based element to invert. 
  3320.  
  3321. Returns 
  3322.  
  3323. This function returns TRUE if successful, or FALSE otherwise. 
  3324.  
  3325. Notes 
  3326.  
  3327. Use CmnSetInvertElement to invert an element in a set.  That is, if it was set, 
  3328. it is cleared (and vice versa).  To invert an entire set, use CmnSetInvertSet. 
  3329.  
  3330. Related information 
  3331.  
  3332. o HCSSET data type 
  3333. o CmnSetInvertSet 
  3334.  
  3335.  
  3336. ΓòÉΓòÉΓòÉ 11.9. CmnSetInvertSet ΓòÉΓòÉΓòÉ
  3337.  
  3338. CmnSetInvertSet 
  3339.  
  3340. Purpose 
  3341.  
  3342. This function inverts the state of all of the elements in a set. 
  3343.  
  3344. Syntax 
  3345.  
  3346. (BOOL)CmnSetInvertSet(hcsSet);
  3347.  
  3348. Parameters 
  3349.  
  3350. hcsSet (HCSSET) - handle of the set to invert. 
  3351.  
  3352. Returns 
  3353.  
  3354. This function returns TRUE if successful, or FALSE otherwise. 
  3355.  
  3356. Notes 
  3357.  
  3358. Use CmnSetInvertSet to invert all of the elements of a set.  To invert a single 
  3359. element, use CmnSetInvertElement. 
  3360.  
  3361. This call is fast in terms of execution time. 
  3362.  
  3363. Related information 
  3364.  
  3365. o HCSSET data type 
  3366. o CmnSetInvertElement 
  3367.  
  3368.  
  3369. ΓòÉΓòÉΓòÉ 11.10. CmnSetQueryElement ΓòÉΓòÉΓòÉ
  3370.  
  3371. CmnSetQueryElement 
  3372.  
  3373. Purpose 
  3374.  
  3375. This function queries the state of an element in a set. 
  3376.  
  3377. Syntax 
  3378.  
  3379. (SHORT)CmnSetQueryElement(hcsSet,ulElement);
  3380.  
  3381. Parameters 
  3382.  
  3383. hcsSet (HCSSET) - handle of the set to query. 
  3384.  
  3385. ulElement (ULONG) - specifies the 0-based element to query. 
  3386.  
  3387. Returns 
  3388.  
  3389. This function returns SQE_SET if the element is set, SQE_CLEAR if the element 
  3390. is cleared, or SQE_ERROR if an error occurred. 
  3391.  
  3392. Notes 
  3393.  
  3394. Use CmnSetQueryElement to query the state of an element. 
  3395.  
  3396. Related information 
  3397.  
  3398. o HCSSET data type 
  3399.  
  3400.  
  3401. ΓòÉΓòÉΓòÉ 11.11. CmnSetQueryEqualSets ΓòÉΓòÉΓòÉ
  3402.  
  3403. CmnSetQueryEqualSets 
  3404.  
  3405. Purpose 
  3406.  
  3407. This function determines whether or not two sets are equal. 
  3408.  
  3409. Syntax 
  3410.  
  3411. (SHORT)CmnSetQueryEqualSets(hcsSet1,hcsSet2);
  3412.  
  3413. Parameters 
  3414.  
  3415. hcsSet1 (HCSSET) - handle of a set to compare. 
  3416.  
  3417. hcsSet2 (HCSSET) - handle of a set to compare. 
  3418.  
  3419. Returns 
  3420.  
  3421. This function returns SQES_EQUAL if the sets have the same number of elements 
  3422. and the same elements are set in both sets, SQES_NOTEQUAL if the sets do not 
  3423. have the same number of elements or the same elements are not set in both sets, 
  3424. or SQES_ERROR if an error occurred. 
  3425.  
  3426. Notes 
  3427.  
  3428. Use CmnSetQueryEqualSets to determine whether or not two sets are equal. 
  3429.  
  3430. This call is fast in terms of execution time. 
  3431.  
  3432. Related information 
  3433.  
  3434. o HCSSET data type 
  3435.  
  3436.  
  3437. ΓòÉΓòÉΓòÉ 11.12. CmnSetSetElement ΓòÉΓòÉΓòÉ
  3438.  
  3439. CmnSetSetElement 
  3440.  
  3441. Purpose 
  3442.  
  3443. This function sets an element in a set. 
  3444.  
  3445. Syntax 
  3446.  
  3447. (BOOL)CmnSetSetElement(hcsSet,ulElement);
  3448.  
  3449. Parameters 
  3450.  
  3451. hcsSet (HCSSET) - handle of the set. 
  3452.  
  3453. ulElement (ULONG) - specifies the 0-based element to set. 
  3454.  
  3455. Returns 
  3456.  
  3457. This function returns TRUE if successful, or FALSE otherwise. 
  3458.  
  3459. Notes 
  3460.  
  3461. Use CmnSetSetElement to set an element in a set.  To set all of the elements in 
  3462. a set, use CmnSetSetSet. 
  3463.  
  3464. Related information 
  3465.  
  3466. o HCSSET data type 
  3467. o CmnSetSetSet 
  3468.  
  3469.  
  3470. ΓòÉΓòÉΓòÉ 11.13. CmnSetSetSet ΓòÉΓòÉΓòÉ
  3471.  
  3472. CmnSetSetSet 
  3473.  
  3474. Purpose 
  3475.  
  3476. This function sets all of the elements in a set. 
  3477.  
  3478. Syntax 
  3479.  
  3480. (BOOL)CmnSetSetSet(hcsSet);
  3481.  
  3482. Parameters 
  3483.  
  3484. hcsSet (HCSSET) - handle of the set to set. 
  3485.  
  3486. Returns 
  3487.  
  3488. This function returns TRUE if successful, or FALSE otherwise. 
  3489.  
  3490. Notes 
  3491.  
  3492. Use CmnSetSetSet to set all of the elements in a set. To set a single element, 
  3493. use CmnSetSetElement. 
  3494.  
  3495. This call is fast in terms of execution time. 
  3496.  
  3497. Related information 
  3498.  
  3499. o HCSSET data type 
  3500. o CmnSetSetElement 
  3501.  
  3502.  
  3503. ΓòÉΓòÉΓòÉ 12. Signal routines ΓòÉΓòÉΓòÉ
  3504.  
  3505. The purpose of this group is to provide an easy method of communication between 
  3506. different threads in an application.  Signals can either be via 32-bit values 
  3507. or individual bits in a 32-bit word, and can be waited on like you can with 
  3508. semaphores.  Unfortunately, since this functions are not system-wide objects, 
  3509. they cannot be used for interprocess communication. 
  3510.  
  3511. Listed below are the functions which comprise this group: 
  3512.  
  3513. o CmnSigClearAllSignalBits 
  3514. o CmnSigClearSignalBit 
  3515. o CmnSigCreateSignal 
  3516. o CmnSigCreateSignalList 
  3517. o CmnSigDestroySignal 
  3518. o CmnSigDestroySignalList 
  3519. o CmnSigQuerySignal 
  3520. o CmnSigQuerySignalId 
  3521. o CmnSigQuerySignalValue 
  3522. o CmnSigSetAllSignalBits 
  3523. o CmnSigSetAllSignalValues 
  3524. o CmnSigSetSignalBit 
  3525. o CmnSigSetSignalValue 
  3526. o CmnSigWaitAllSignalBits 
  3527. o CmnSigWaitAllSignalValues 
  3528. o CmnSigWaitSignalBit 
  3529. o CmnSigWaitSignalValue 
  3530.  
  3531.  
  3532. ΓòÉΓòÉΓòÉ 12.1. CmnSigClearAllSignalBits ΓòÉΓòÉΓòÉ
  3533.  
  3534. CmnSigClearAllSignalBits 
  3535.  
  3536. Purpose 
  3537.  
  3538. This function clears all of the specified bits in all of the signal handles in 
  3539. a signal list. 
  3540.  
  3541. Syntax 
  3542.  
  3543. (BOOL)CmnSigClearAllSignalBits(hcsList,ulSignal);
  3544.  
  3545. Parameters
  3546.  
  3547. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  3548.  
  3549. ulSignal (ULONG) - specifies one or more bits to clear. 
  3550.  
  3551. Returns 
  3552.  
  3553. This function returns TRUE if successful, or FALSE otherwise. 
  3554.  
  3555. Notes 
  3556.  
  3557. Use CmnSigClearAllSignalBits to clear all of the specified bits in all of the 
  3558. signal handles in a signal list.  To clear specified bits from a single signal 
  3559. handle, use CmnSigClearSignalBit. 
  3560.  
  3561. Related information 
  3562.  
  3563. o HCSSIGNALLIST data type 
  3564. o CmnSigClearSignalBit 
  3565. o CmnSigSetAllSignalBits 
  3566.  
  3567.  
  3568. ΓòÉΓòÉΓòÉ 12.2. CmnSigClearSignalBit ΓòÉΓòÉΓòÉ
  3569.  
  3570. CmnSigClearSignalBit 
  3571.  
  3572. Purpose 
  3573.  
  3574. This function clears one or more bits in a signal. 
  3575.  
  3576. Syntax 
  3577.  
  3578. (BOOL)CmnSigClearSignalBit(hcSignal,ulSignal);
  3579.  
  3580. Parameters 
  3581.  
  3582. hcSignal (HCSSIGNAL) - handle to the signal. 
  3583.  
  3584. ulSignal (ULONG) - specifies one or more bits to clear. 
  3585.  
  3586. Returns 
  3587.  
  3588. This function returns TRUE if successful, or FALSE otherwise. 
  3589.  
  3590. Notes 
  3591.  
  3592. Use CmnSigClearSignalBit to clear one or more bits from a signal. 
  3593.  
  3594. Related information 
  3595.  
  3596. o HCSSIGNAL data type 
  3597. o CmnSigSetSignalBit 
  3598.  
  3599.  
  3600. ΓòÉΓòÉΓòÉ 12.3. CmnSigCreateSignal ΓòÉΓòÉΓòÉ
  3601.  
  3602. CmnSigCreateSignal 
  3603.  
  3604. Purpose 
  3605.  
  3606. This function creates a signal handle within a signal list. 
  3607.  
  3608. Syntax 
  3609.  
  3610. (BOOL)CmnSigCreateSignal(hcsList,ulId,phcSignal);
  3611.  
  3612. Parameters 
  3613.  
  3614. hcsList (HCSSIGNALLIST) - handle to the signal list to which the signal handle 
  3615. will belong. 
  3616.  
  3617. ulId (ULONG) - specified the identifer of the signal handle. This must be 
  3618. unique. 
  3619.  
  3620. phcSignal (PHCSSIGNAL) - points to the variable to receive the created signal 
  3621. handle. 
  3622.  
  3623. Returns 
  3624.  
  3625. This function returns TRUE if successful, or FALSE otherwise. 
  3626.  
  3627. Notes 
  3628.  
  3629. Use CmnSigCreateSignal to create a signal handle for use in subsequent calls to 
  3630. the CmnSig routines.  ulId must be a unique identifier within the signal list. 
  3631.  
  3632. Note that because this function requires the handle to a signal list, 
  3633. CmnSigCreateSignalList must be called prior to using this function. 
  3634.  
  3635. Related information 
  3636.  
  3637. o HCSSIGNALLIST data type 
  3638. o HCSSIGNAL data type 
  3639. o CmnSigCreateSignalList 
  3640. o CmnSigDestroySignal 
  3641.  
  3642.  
  3643. ΓòÉΓòÉΓòÉ 12.4. CmnSigCreateSignalList ΓòÉΓòÉΓòÉ
  3644.  
  3645. CmnSigCreateSignalList 
  3646.  
  3647. Purpose 
  3648.  
  3649. This function creates a signal list handle from which signal handles can be 
  3650. created. 
  3651.  
  3652. Syntax 
  3653.  
  3654. (BOOL)CmnSigCreateSignalList(phcsList);
  3655.  
  3656. Parameters 
  3657.  
  3658. phcsList (PHCSSIGNALLIST) - points to the variable that receives the created 
  3659. signal list handle. 
  3660.  
  3661. Returns 
  3662.  
  3663. This function returns TRUE if successful, or FALSE otherwise. 
  3664.  
  3665. Notes 
  3666.  
  3667. Use CmnSigCreateSignalList to create a signal list handle. After this is 
  3668. created, CmnSigCreateSignal can be called to create signal handles to be used 
  3669. in other CmnSig functions. 
  3670.  
  3671. Related information 
  3672.  
  3673. o HCSSIGNALLIST data type 
  3674. o CmnSigCreateSignal 
  3675. o CmnSigDestroySignalList 
  3676.  
  3677.  
  3678. ΓòÉΓòÉΓòÉ 12.5. CmnSigDestroySignal ΓòÉΓòÉΓòÉ
  3679.  
  3680. CmnSigDestroySignal 
  3681.  
  3682. Purpose 
  3683.  
  3684. This function destroys a signal handle. 
  3685.  
  3686. Syntax 
  3687.  
  3688. (BOOL)CmnSigDestroySignal(phcSignal);
  3689.  
  3690. Parameters 
  3691.  
  3692. phcSignal (PHCSSIGNAL) - points to the variable which specifies the handle of 
  3693. the signal to destroy.  On return, this variable contains NULL. 
  3694.  
  3695. Returns 
  3696.  
  3697. This function returns TRUE if successful, or FALSE otherwise. 
  3698.  
  3699. Notes 
  3700.  
  3701. Use CmnSigDestroySignal to destroy a signal handle.  This call is not required 
  3702. prior to calling CmnSigDestroySignalList because it will destroy all signal 
  3703. handles belong to the signal list. 
  3704.  
  3705. Related information 
  3706.  
  3707. o HCSSIGNAL data type 
  3708. o CmnSigCreateSignal 
  3709.  
  3710.  
  3711. ΓòÉΓòÉΓòÉ 12.6. CmnSigDestroySignalList ΓòÉΓòÉΓòÉ
  3712.  
  3713. CmnSigDestroySignalList 
  3714.  
  3715. Purpose 
  3716.  
  3717. This function destroys a signal list. 
  3718.  
  3719. Syntax 
  3720.  
  3721. (BOOL)CmnSigDestroySignalList(phcsList);
  3722.  
  3723. Parameters 
  3724.  
  3725. phcsList (PHCSSIGNALLIST) - points to the variable which specifies the handle 
  3726. of the signal list to destroy.  On return, this variable contains NULL. 
  3727.  
  3728. Returns 
  3729.  
  3730. This function returns TRUE if successful, or FALSE otherwise. 
  3731.  
  3732. Notes 
  3733.  
  3734. Use CmnSigDestroySignalList to destroy a signal list and all associated signal 
  3735. handles. 
  3736.  
  3737. Related information 
  3738.  
  3739. o HCSSIGNALLIST data type 
  3740. o CmnSigCreateSignalList 
  3741.  
  3742.  
  3743. ΓòÉΓòÉΓòÉ 12.7. CmnSigQuerySignal ΓòÉΓòÉΓòÉ
  3744.  
  3745. CmnSigQuerySignal 
  3746.  
  3747. Purpose 
  3748.  
  3749. This function queries a signal list for a signal handle with a specific 
  3750. identifier. 
  3751.  
  3752. Syntax 
  3753.  
  3754. (BOOL)CmnSigQuerySignal(hcsList,ulId,phcSignal);
  3755.  
  3756. Parameters 
  3757.  
  3758. hcsList (HCSSIGNALLIST) - handle to the signal list to query. 
  3759.  
  3760. ulId (ULONG) - specifies the identifier of the signal handle desired. 
  3761.  
  3762. phcSignal (PHCSSIGNAL) - points to the variable to receive the result.  On 
  3763. return, the variable contains the signal handle with the specified identifier. 
  3764.  
  3765. Returns 
  3766.  
  3767. This function returns TRUE if successful, or FALSE otherwise. 
  3768.  
  3769. Notes 
  3770.  
  3771. Use CmnSigQuerySignal to query a signal list for the signal handle that was 
  3772. created with the specified identifier. 
  3773.  
  3774. Related information 
  3775.  
  3776. o HCSSIGNAL data type 
  3777. o HCSSIGNALLIST data type 
  3778. o CmnSigCreateSignal 
  3779. o CmnSigQuerySignalId 
  3780.  
  3781.  
  3782. ΓòÉΓòÉΓòÉ 12.8. CmnSigQuerySignalId ΓòÉΓòÉΓòÉ
  3783.  
  3784. CmnSigQuerySignalId 
  3785.  
  3786. Purpose 
  3787.  
  3788. This function returns the identifier of a signal handle. 
  3789.  
  3790. Syntax 
  3791.  
  3792. (BOOL)CmnSigQuerySignalId(hcSignal,pulId);
  3793.  
  3794. Parameters 
  3795.  
  3796. hcSignal (HCSSIGNAL) - handle to the signal. 
  3797.  
  3798. pulId (PULONG) - points to the variable that receives the identifier of the 
  3799. signal handle. 
  3800.  
  3801. Returns 
  3802.  
  3803. This function returns TRUE if successful, or FALSE otherwise. 
  3804.  
  3805. Notes 
  3806.  
  3807. Use CmnSigQuerySignalId to query the identifier of a signal handle.  This 
  3808. identifier is specified when the signal handle is created. 
  3809.  
  3810. Related information 
  3811.  
  3812. o HCSSIGNAL data type 
  3813. o CmnSigCreateSignal 
  3814.  
  3815.  
  3816. ΓòÉΓòÉΓòÉ 12.9. CmnSigQuerySignalValue ΓòÉΓòÉΓòÉ
  3817.  
  3818. CmnSigQuerySignalValue 
  3819.  
  3820. Purpose 
  3821.  
  3822. This function queries the current value of a signal handle. 
  3823.  
  3824. Syntax 
  3825.  
  3826. (BOOL)CmnSigQuerySignalValue(hcSignal,pulSignal);
  3827.  
  3828. Parameters 
  3829.  
  3830. hcSignal (HCSSIGNAL) - handle to the signal. 
  3831.  
  3832. pulSignal (PULONG) - points to the variable that receives the value of the 
  3833. signal handle. 
  3834.  
  3835. Returns 
  3836.  
  3837. This function returns TRUE if successful, or FALSE otherwise. 
  3838.  
  3839. Notes 
  3840.  
  3841. Use CmnSigQuerySignalValue to query the current value of a signal handle. 
  3842.  
  3843. Related information 
  3844.  
  3845. o HCSSIGNAL data type 
  3846. o CmnSigSetSignalValue 
  3847.  
  3848.  
  3849. ΓòÉΓòÉΓòÉ 12.10. CmnSigSetAllSignalBits ΓòÉΓòÉΓòÉ
  3850.  
  3851. CmnSigSetAllSignalBits 
  3852.  
  3853. Purpose 
  3854.  
  3855. This function sets specific bits in all signals in a signal list. 
  3856.  
  3857. Syntax 
  3858.  
  3859. (BOOL)CmnSigSetAllSignalBits(hcsList,ulSignal);
  3860.  
  3861. Parameters
  3862.  
  3863. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  3864.  
  3865. ulSignal (ULONG) - specifies one or more bits to set. 
  3866.  
  3867. Returns 
  3868.  
  3869. This function returns TRUE if successful, or FALSE otherwise. 
  3870.  
  3871. Notes 
  3872.  
  3873. Use CmnSigSetAllSignalBits to set a specific set of bits in all signals in a 
  3874. signal list.  This could be used to reset the acknowledgement signal from 
  3875. multiple threads by the initiator of the inter-thread conversation. 
  3876.  
  3877. Related information 
  3878.  
  3879. o HCSSIGNALLIST data type 
  3880. o CmnSigClearAllSignalBits 
  3881. o CmnSigSetAllSignalValues 
  3882.  
  3883.  
  3884. ΓòÉΓòÉΓòÉ 12.11. CmnSigSetAllSignalValues ΓòÉΓòÉΓòÉ
  3885.  
  3886. CmnSigSetAllSignalValues 
  3887.  
  3888. Purpose 
  3889.  
  3890. This function sets all of the signal values in a signal list to a specific 
  3891. value. 
  3892.  
  3893. Syntax 
  3894.  
  3895. (BOOL)CmnSigSetAllSignalValues(hcsList,ulSignal);
  3896.  
  3897. Parameters
  3898.  
  3899. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  3900.  
  3901. ulSignal (ULONG) - specifies the new signal value. 
  3902.  
  3903. Returns 
  3904.  
  3905. This function returns TRUE if successful, or FALSE otherwise. 
  3906.  
  3907. Notes 
  3908.  
  3909. Use CmnSigSetAllSignalValues to set all of the signal values in a signal list 
  3910. to a specific value.  This could be used to reset the acknowledgement signal 
  3911. from multiple threads by the initiator of the inter-thread conversation. 
  3912.  
  3913. Related information 
  3914.  
  3915. o HCSSIGNALLIST data type 
  3916. o CmnSigSetAllSignalBits 
  3917.  
  3918.  
  3919. ΓòÉΓòÉΓòÉ 12.12. CmnSigSetSignalValue ΓòÉΓòÉΓòÉ
  3920.  
  3921. CmnSigSetSignalValue 
  3922.  
  3923. Purpose 
  3924.  
  3925. This function sets the current value of a signal handle. 
  3926.  
  3927. Syntax 
  3928.  
  3929. (BOOL)CmnSigSetSignalValue(hcSignal,ulSignal);
  3930.  
  3931. Parameters 
  3932.  
  3933. hcSignal (HCSSIGNAL) - handle to the signal. 
  3934.  
  3935. ulSignal (ULONG) - specifies the new value of the signal. 
  3936.  
  3937. Returns 
  3938.  
  3939. This function returns TRUE if successful, or FALSE otherwise. 
  3940.  
  3941. Notes 
  3942.  
  3943. Use CmnSigSetSignalValue to set the current value of a signal value.  To set or 
  3944. clear individual bits of the signal value, use CmnSigSetSignalBit and 
  3945. CmnSigClearSignalBit. 
  3946.  
  3947. Related information 
  3948.  
  3949. o HCSSIGNAL data type 
  3950. o CmnSigClearSignalBit 
  3951. o CmnSigQuerySignalValue 
  3952. o CmnSigSetSignalBit 
  3953.  
  3954.  
  3955. ΓòÉΓòÉΓòÉ 12.13. CmnSigSetSignalBit ΓòÉΓòÉΓòÉ
  3956.  
  3957. CmnSigSetSignalBit 
  3958.  
  3959. Purpose 
  3960.  
  3961. This function sets one or more bits in a signal. 
  3962.  
  3963. Syntax 
  3964.  
  3965. (BOOL)CmnSigSetSignalBit(hcSignal,ulSignal);
  3966.  
  3967. Parameters 
  3968.  
  3969. hcSignal (HCSSIGNAL) - handle to the signal. 
  3970.  
  3971. ulSignal (ULONG) - specifies one or more bits to set. 
  3972.  
  3973. Returns 
  3974.  
  3975. This function returns TRUE if successful, or FALSE otherwise. 
  3976.  
  3977. Notes 
  3978.  
  3979. Use CmnSigSetSignalBit to set one or more bits in a signal. 
  3980.  
  3981. Related information 
  3982.  
  3983. o HCSSIGNAL data type 
  3984. o CmnSigClearSignalBit 
  3985.  
  3986.  
  3987. ΓòÉΓòÉΓòÉ 12.14. CmnSigWaitAllSignalBits ΓòÉΓòÉΓòÉ
  3988.  
  3989. CmnSigWaitAllSignalBits 
  3990.  
  3991. Purpose 
  3992.  
  3993. This function waits until all of the specified bits are set in all of the 
  3994. signal handles belonging to a signal list. 
  3995.  
  3996. Syntax 
  3997.  
  3998. (USHORT)CmnSigWaitAllSignalBits(hcsList,ulSignal,lTimeout);
  3999.  
  4000. Parameters 
  4001.  
  4002. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  4003.  
  4004. ulSignal (ULONG) - specifies the bits to wait for. 
  4005.  
  4006. lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
  4007. constant. 
  4008.  
  4009. Returns 
  4010.  
  4011. This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
  4012. bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
  4013. occurred. 
  4014.  
  4015. Notes 
  4016.  
  4017. Use CmnSigWaitAllSignalBits to wait for all of the specified bits in all of the 
  4018. signal handles in a signal list to be set.  This could be used as part of a 
  4019. handshaking mechanism, where one thread calls CmnSigSetAllSignalBits to 
  4020. indicate to the other threads that some function is to be performed and then 
  4021. follows with a call to this function to wait for each signal to indicate (via 
  4022. CmnSigSetSignalBit) that it has completed the request. 
  4023.  
  4024. Related information 
  4025.  
  4026. o SWS_TIMEOUT_ constants 
  4027. o HCSSIGNALLIST data type 
  4028. o CmnSigClearAllSignalBits 
  4029. o CmnSigSetAllSignalValues 
  4030. o CmnSigWaitAllSignalValues 
  4031.  
  4032.  
  4033. ΓòÉΓòÉΓòÉ 12.15. CmnSigWaitAllSignalValues ΓòÉΓòÉΓòÉ
  4034.  
  4035. CmnSigWaitAllSignalValues 
  4036.  
  4037. Purpose 
  4038.  
  4039. This function waits until all of the signal values in a signal list are equal 
  4040. to a specific value. 
  4041.  
  4042. Syntax 
  4043.  
  4044. (USHORT)CmnSigWaitAllSignalValues(hcsList,ulSignal,lTimeout);
  4045.  
  4046. Parameters 
  4047.  
  4048. hcsList (HCSSIGNALLIST) - handle to the signal list. 
  4049.  
  4050. ulSignal (ULONG) - specifies the value to wait for. 
  4051.  
  4052. lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
  4053. constant. 
  4054.  
  4055. Returns 
  4056.  
  4057. This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
  4058. bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
  4059. occurred. 
  4060.  
  4061. Notes 
  4062.  
  4063. Use CmnSigWaitAllSignalValues to wait for all signal values in a signal list to 
  4064. equal a specific value.  This could be used to wait for an acknowledgement from 
  4065. multiple threads after they have finished processing a task. 
  4066.  
  4067. Related information 
  4068.  
  4069. o SWS_TIMEOUT_ constants 
  4070. o HCSSIGNALLIST data type 
  4071. o CmnSigSetAllSignalValues 
  4072. o CmnSigWaitAllSignalBits 
  4073.  
  4074.  
  4075. ΓòÉΓòÉΓòÉ 12.16. CmnSigWaitSignalBit ΓòÉΓòÉΓòÉ
  4076.  
  4077. CmnSigWaitSignalBit 
  4078.  
  4079. Purpose 
  4080.  
  4081. This function waits for a specific set of bits to be set in a signal handle. 
  4082.  
  4083. Syntax 
  4084.  
  4085. (USHORT)CmnSigWaitSignalBit(hcSignal,ulSignal,lTimeout);
  4086.  
  4087. Parameters 
  4088.  
  4089. hcSignal (HCSSIGNAL) - handle to the signal. 
  4090.  
  4091. ulSignal (ULONG) - specifies one or more bits to wait for. 
  4092.  
  4093. lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
  4094. constant. 
  4095.  
  4096. Returns 
  4097.  
  4098. This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
  4099. bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
  4100. occurred. 
  4101.  
  4102. Notes 
  4103.  
  4104. Use CmnSigWaitSignalBit to wait for a specific set of bits in a signal handle 
  4105. to be set.  This could be used by a thread to wait until a bit is set before 
  4106. performing some action. 
  4107.  
  4108. Related information 
  4109.  
  4110. o SWS_TIMEOUT_ constants 
  4111. o HCSSIGNAL data type 
  4112. o CmnSigClearSignalBit 
  4113. o CmnSigSetSignalBit 
  4114.  
  4115.  
  4116. ΓòÉΓòÉΓòÉ 12.17. CmnSigWaitSignalValue ΓòÉΓòÉΓòÉ
  4117.  
  4118. CmnSigWaitSignalValue 
  4119.  
  4120. Purpose 
  4121.  
  4122. This function waits until the value of a signal handle equals a specific value. 
  4123.  
  4124. Syntax 
  4125.  
  4126. (USHORT)CmnSigWaitSignalValue(hcSignal,ulSignal,lTimeout);
  4127.  
  4128. Parameters 
  4129.  
  4130. hcSignal (HCSSIGNAL) - handle to the signal. 
  4131.  
  4132. ulSignal (ULONG) - specifies the value to wait for. 
  4133.  
  4134. lTimeout (LONG) - specifies the timeout in milliseconds, or an SWS_TIMEOUT_ 
  4135. constant. 
  4136.  
  4137. Returns 
  4138.  
  4139. This function returns SWS_RC_SIGNALSET if all of the signal handles had the 
  4140. bits set, SWS_RC_TIMEOUT if a timeout occurred, or SWS_RC_ERROR if an error 
  4141. occurred. 
  4142.  
  4143. Notes 
  4144.  
  4145. Use CmnSigWaitSignalValue to wait for the value of a signal handle equals a 
  4146. specific value.  This could be used in a handshaking protocol between multiple 
  4147. threads. 
  4148.  
  4149. Related information 
  4150.  
  4151. o SWS_TIMEOUT_ constants 
  4152. o HCSSIGNAL data type 
  4153. o CmnSigSetSignalValue 
  4154.  
  4155.  
  4156. ΓòÉΓòÉΓòÉ 13. Sprite routines ΓòÉΓòÉΓòÉ
  4157.  
  4158. The purpose of this group is to provide the capability to draw bitmaps with 
  4159. transparancy; the difference between a sprite resource and the system-defined 
  4160. pointer resource is that pointer are always the same size (determined by 
  4161. calling WinQuerySysValue with the SV_CXICON and SV_CYICON constants), while 
  4162. sprites can be any size, up to a maximum of MAX_SPRITE_CX by MAX_SPRITE_CY 
  4163. pels. 
  4164.  
  4165. Sprites are often used in animated sequences; however, while this group 
  4166. provides a basis for sprite manipulation, the animation is still up to the 
  4167. programmer to accomplish. 
  4168.  
  4169. Before a sprite can be drawn on the screen, it must belong to a playground.  A 
  4170. playground maintains a membership list and can have either a background bitmap 
  4171. or color associated with it.  Although the concept of a background seems 
  4172. superfluous, it is necessary for the transparency capabilities. 
  4173.  
  4174. Listed below are the functions which comprise this group: 
  4175.  
  4176. o CmnSprAddSprite 
  4177. o CmnSprCreatePlayground 
  4178. o CmnSprCreateSprite 
  4179. o CmnSprDestroyPlayground 
  4180. o CmnSprDestroySprite 
  4181. o CmnSprDrawPlayground 
  4182. o CmnSprDrawSprite 
  4183. o CmnSprQueryLayering 
  4184. o CmnSprQueryPlaygroundBack 
  4185. o CmnSprQueryPlaygroundColor 
  4186. o CmnSprQueryPlaygroundSize 
  4187. o CmnSprQuerySpritePosition 
  4188. o CmnSprQuerySpriteRect 
  4189. o CmnSprQuerySpriteSize 
  4190. o CmnSprQuerySpriteVisibility 
  4191. o CmnSprQueryUpdateFlag 
  4192. o CmnSprRemoveSprite 
  4193. o CmnSprSetLayering 
  4194. o CmnSprSetPlaygroundBack 
  4195. o CmnSprSetPlaygroundColor 
  4196. o CmnSprSetPlaygroundSize 
  4197. o CmnSprSetSpritePosition 
  4198. o CmnSprSetSpriteVisibility 
  4199. o CmnSprSetUpdateFlag 
  4200.  
  4201.  
  4202. ΓòÉΓòÉΓòÉ 13.1. CmnSprAddSprite ΓòÉΓòÉΓòÉ
  4203.  
  4204. CmnSprAddSprite 
  4205.  
  4206. Purpose 
  4207.  
  4208. This function adds a sprite to a playground so that it may be drawn, moved, 
  4209. etc. 
  4210.  
  4211. Syntax 
  4212.  
  4213. (SPRERROR)CmnSprAddSprite(hpgPlay,hsSprite);
  4214.  
  4215. Parameters 
  4216.  
  4217. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4218.  
  4219. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4220.  
  4221. Returns 
  4222.  
  4223. This function returns one of the following values: 
  4224.  
  4225. SPR_ERR_NOERROR 
  4226. SPR_ERR_BADHANDLE 
  4227. SPR_ERR_HASPLAYGROUND 
  4228. SPR_ERR_PLAYGROUNDFULL 
  4229.  
  4230. Notes 
  4231.  
  4232. Once a sprite is added to a playground, it may not be destroyed until it is 
  4233. removed from the playground.  A sprite may belong to one playground only at any 
  4234. given time, and a playground can hold up to MAX_SPRITES number of sprites at 
  4235. any given time. 
  4236.  
  4237. Related information 
  4238.  
  4239. o HCSPLAYGROUND data type 
  4240. o HCSSPRITE data type 
  4241. o CmnSprCreateSprite 
  4242. o CmnSprDestroySprite 
  4243. o CmnSprRemoveSprite 
  4244.  
  4245.  
  4246. ΓòÉΓòÉΓòÉ 13.2. CmnSprCreatePlayground ΓòÉΓòÉΓòÉ
  4247.  
  4248. CmnSprCreatePlayground 
  4249.  
  4250. Purpose 
  4251.  
  4252. This function creates a playground instance to which sprites may be added. 
  4253.  
  4254. Syntax 
  4255.  
  4256. (SPRERROR)CmnSprCreatePlayground(habAnchor,phpgPlay);
  4257.  
  4258. Parameters 
  4259.  
  4260. habAnchor (HAB) - handle of the anchor block of the calling thread. 
  4261.  
  4262. phpgPlay (PHCSPLAYGROUND) - points to the variable to receive the handle of the 
  4263. playground. 
  4264.  
  4265. Returns 
  4266.  
  4267. This function returns one of the following values: 
  4268.  
  4269. SPR_ERR_NOERROR 
  4270. SPR_ERR_NOMEMORY 
  4271. SPR_ERR_RESOURCE 
  4272.  
  4273. Notes 
  4274.  
  4275. Although specifying an anchor block might imply otherwise, playground handles 
  4276. are not specific to a thread, but instead belong to the entire process. 
  4277.  
  4278. A playground is created with the following defaults: 
  4279.  
  4280. Update flag         TRUE 
  4281. Background          Color, which is CLR_BLACK 
  4282. Size                Height and width of 0 
  4283.  
  4284. Related information 
  4285.  
  4286. o HCSPLAYGROUND data type 
  4287. o CmnSprDestroyPlayground 
  4288.  
  4289.  
  4290. ΓòÉΓòÉΓòÉ 13.3. CmnSprCreateSprite ΓòÉΓòÉΓòÉ
  4291.  
  4292. CmnSprCreateSprite 
  4293.  
  4294. Purpose 
  4295.  
  4296. This function creates a sprite instance which may be added to a playground. 
  4297.  
  4298. Syntax 
  4299.  
  4300. (SPRERROR)CmnSprCreateSprite(habAnchor,hbmBitmap,phsSprite);
  4301.  
  4302. Parameters 
  4303.  
  4304. habAnchor (HAB) - handle of the anchor block of the calling thread. 
  4305.  
  4306. hbmBitmap (HBITMAP) - handle of the bitmap from which to create the sprite. 
  4307.  
  4308. phsSprite (PHCSSPRITE) - points to the variable to receive the handle of the 
  4309. sprite. 
  4310.  
  4311. Returns 
  4312.  
  4313. This function returns one of the following values: 
  4314.  
  4315. SPR_ERR_NOERROR 
  4316. SPR_ERR_BADHANDLE 
  4317. SPR_ERR_NOMEMORY 
  4318. SPR_ERR_RESOURCE 
  4319.  
  4320. Notes 
  4321.  
  4322. All pels in the bitmap that, once mapped to the physical palette, are black 
  4323. specify the transparent portions of the sprite.  The bitmap that is passed in 
  4324. cannot have a wider greater than MAX_SPRITE_CX pels or a height greater than 
  4325. MAX_SPRITE_CY or the function will fail with error SPR_ERR_BADHANDLE.  Once 
  4326. this function returns SPR_ERR_NOERROR, the bitmap handle (hbmBitmap) is 
  4327. considered to be owned by the sprite subsystem and should not be deleted by the 
  4328. application, unless by calling CmnSprDestroySprite. 
  4329.  
  4330. Like the playground, a sprite belongs to the entire process that created it, 
  4331. instead of just the thread as the anchor block parameter would imply. 
  4332.  
  4333. A sprite is created with the following defaults: 
  4334.  
  4335. Visibility          Not visible 
  4336. Position            (0,0) 
  4337.  
  4338. Related information 
  4339.  
  4340. o HCSSPRITE data type 
  4341. o CmnSprDestroySprite 
  4342.  
  4343.  
  4344. ΓòÉΓòÉΓòÉ 13.4. CmnSprDestroyPlayground ΓòÉΓòÉΓòÉ
  4345.  
  4346. CmnSprDestroyPlayground 
  4347.  
  4348. Purpose 
  4349.  
  4350. This function destroys the playground instance, all sprites that still belong 
  4351. to it, and the background bitmap if one exists. 
  4352.  
  4353. Syntax 
  4354.  
  4355. (SPRERROR)CmnSprDestroyPlayground(hpgPlay);
  4356.  
  4357. Parameters 
  4358.  
  4359. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4360.  
  4361. Returns 
  4362.  
  4363. This function returns one of the following values: 
  4364.  
  4365. SPR_ERR_NOERROR 
  4366. SPR_ERR_BADHANDLE 
  4367.  
  4368. Related information 
  4369.  
  4370. o HCSPLAYGROUND data type 
  4371. o CmnSprCreatePlayground 
  4372.  
  4373.  
  4374. ΓòÉΓòÉΓòÉ 13.5. CmnSprDestroySprite ΓòÉΓòÉΓòÉ
  4375.  
  4376. CmnSprDestroySprite 
  4377.  
  4378. Purpose 
  4379.  
  4380. This function destroys the sprite instance, including any associated bitmaps. 
  4381.  
  4382. Syntax 
  4383.  
  4384. (SPRERROR)CmnSprDestroySprite(hsSprite);
  4385.  
  4386. Parameters 
  4387.  
  4388. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4389.  
  4390. Returns 
  4391.  
  4392. This function returns one of the following values: 
  4393.  
  4394. SPR_ERR_NOERROR 
  4395. SPR_ERR_BADHANDLE 
  4396. SPR_ERR_HASPLAYGROUND 
  4397.  
  4398. Notes 
  4399.  
  4400. If the sprite still belongs to a playground, this function fails with the error 
  4401. SPR_ERR_HASPLAYGROUND. 
  4402.  
  4403. Related information 
  4404.  
  4405. o HCSSPRITE data type 
  4406. o CmnSprCreateSprite 
  4407.  
  4408.  
  4409. ΓòÉΓòÉΓòÉ 13.6. CmnSprDrawPlayground ΓòÉΓòÉΓòÉ
  4410.  
  4411. CmnSprDrawPlayground 
  4412.  
  4413. Purpose 
  4414.  
  4415. This function redraws the entire playground, including any sprites belonging to 
  4416. it. 
  4417.  
  4418. Syntax 
  4419.  
  4420. (SPRERROR)CmnSprDrawPlayground(hpsDraw,hpgPlay);
  4421.  
  4422. Parameters 
  4423.  
  4424. hpsDraw (HPS) - handle of the presentation space to draw within. 
  4425.  
  4426. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4427.  
  4428. Returns 
  4429.  
  4430. This function returns one of the following values: 
  4431.  
  4432. SPR_ERR_NOERROR 
  4433. SPR_ERR_BADHANDLE 
  4434.  
  4435. Related information 
  4436.  
  4437. o HCSPLAYGROUND data type 
  4438. o CmnSprDrawSprite 
  4439.  
  4440.  
  4441. ΓòÉΓòÉΓòÉ 13.7. CmnSprDrawSprite ΓòÉΓòÉΓòÉ
  4442.  
  4443. CmnSprDrawSprite 
  4444.  
  4445. Purpose 
  4446.  
  4447. This function draws the sprite at its current position. 
  4448.  
  4449. Syntax 
  4450.  
  4451. (SPRERROR)CmnSprDrawSprite(hpsDraw,hsSprite);
  4452.  
  4453. Parameters 
  4454.  
  4455. hpsDraw (HPS) - handle of the presentation space to draw within. 
  4456.  
  4457. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4458.  
  4459. Returns 
  4460.  
  4461. This function returns one of the following values: 
  4462.  
  4463. SPR_ERR_NOERROR 
  4464. SPR_ERR_BADHANDLE 
  4465. SPR_ERR_HASNOPLAYGROUND 
  4466.  
  4467. Notes 
  4468.  
  4469. If the sprite's visibility flag is FALSE (see CmnSprSetSpriteVisibility), this 
  4470. function returns SPR_ERR_NOERROR, but no drawing takes place. 
  4471.  
  4472. Changing the position or visibility state of the sprite automatically redraws 
  4473. the sprite without forcing you to call this function. 
  4474.  
  4475. Related information 
  4476.  
  4477. o HCSSPRITE data type 
  4478. o CmnSprDrawPlayground 
  4479.  
  4480.  
  4481. ΓòÉΓòÉΓòÉ 13.8. CmnSprQueryLayering ΓòÉΓòÉΓòÉ
  4482.  
  4483. CmnSprQueryLayering 
  4484.  
  4485. Purpose 
  4486.  
  4487. This function returns the layer of the sprite within the z-order. 
  4488.  
  4489. Syntax 
  4490.  
  4491. (SPRERROR)CmnSprQueryLayering(hsSprite,plPos);
  4492.  
  4493. Parameters 
  4494.  
  4495. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4496.  
  4497. plPos (PLONG) - points to the variable to receive the index of the sprite. 
  4498.  
  4499. Returns 
  4500.  
  4501. This function returns one of the following values: 
  4502.  
  4503. SPR_ERR_NOERROR 
  4504. SPR_ERR_BADHANDLE 
  4505. SPR_ERR_HASNOPLAYGROUND 
  4506. SPR_ERR_NOTFOUND 
  4507.  
  4508. Related information 
  4509.  
  4510. o CmnSprSetLayering 
  4511.  
  4512.  
  4513. ΓòÉΓòÉΓòÉ 13.9. CmnSprQueryPlaygroundBack ΓòÉΓòÉΓòÉ
  4514.  
  4515. CmnSprQueryPlaygroundBack 
  4516.  
  4517. Purpose 
  4518.  
  4519. This function returns the handle of the playground background bitmap. 
  4520.  
  4521. Syntax 
  4522.  
  4523. (SPRERROR)CmnSprQueryPlaygroundBack(hpgPlay,phbmBack);
  4524.  
  4525. Parameters 
  4526.  
  4527. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4528.  
  4529. phbmBack (HBITMAP *) - points to the variable to receive the bitmap handle. 
  4530.  
  4531. Returns 
  4532.  
  4533. This function returns one of the following values: 
  4534.  
  4535. SPR_ERR_NOERROR 
  4536. SPR_ERR_BADHANDLE 
  4537.  
  4538. Notes 
  4539.  
  4540. The playground still owns the bitmap handle returned.  To specify that the 
  4541. playground should relinquish ownership, use the CmnSprSetPlaygroundBack 
  4542. function. 
  4543.  
  4544. Related information 
  4545.  
  4546. o HCSPLAYGROUND data type 
  4547. o CmnSprQueryPlaygroundColor 
  4548. o CmnSprQueryPlaygroundSize 
  4549. o CmnSprSetPlaygroundBack 
  4550. o CmnSprSetPlaygroundColor 
  4551. o CmnSprSetPlaygroundSize 
  4552.  
  4553.  
  4554. ΓòÉΓòÉΓòÉ 13.10. CmnSprQueryPlaygroundColor ΓòÉΓòÉΓòÉ
  4555.  
  4556. CmnSprQueryPlaygroundColor 
  4557.  
  4558. Purpose 
  4559.  
  4560. This function returns the current background color. 
  4561.  
  4562. Syntax 
  4563.  
  4564. (SPRERROR)CmnSprQueryPlaygroundColor(hpgPlay,plBackColor);
  4565.  
  4566. Parameters 
  4567.  
  4568. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4569.  
  4570. plBackColor (PLONG) - points to the variable to receive the current background 
  4571. color. 
  4572.  
  4573. Returns 
  4574.  
  4575. This function returns one of the following values: 
  4576.  
  4577. SPR_ERR_NOERROR 
  4578. SPR_ERR_BADHANDLE 
  4579. SPR_ERR_HASBACKGROUND 
  4580.  
  4581. Notes 
  4582.  
  4583. If the playground has a background bitmap, this function fails with the error 
  4584. SPR_ERR_HASBACKGROUND since the two are mutually exclusive properties. 
  4585.  
  4586. Related information 
  4587.  
  4588. o HCSPLAYGROUND data type 
  4589. o CmnSprQueryPlaygroundBack 
  4590. o CmnSprQueryPlaygroundSize 
  4591. o CmnSprSetPlaygroundBack 
  4592. o CmnSprSetPlaygroundColor 
  4593. o CmnSprSetPlaygroundSize 
  4594.  
  4595.  
  4596. ΓòÉΓòÉΓòÉ 13.11. CmnSprQueryPlaygroundSize ΓòÉΓòÉΓòÉ
  4597.  
  4598. CmnSprQueryPlaygroundSize 
  4599.  
  4600. Purpose 
  4601.  
  4602. This function returns the current background size. 
  4603.  
  4604. Syntax 
  4605.  
  4606. (SPRERROR)CmnSprQueryPlaygroundSize(hpgPlay,pszlSize);
  4607.  
  4608. Parameters 
  4609.  
  4610. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4611.  
  4612. pszlSize (PSIZEL) - points to the variable to receive the current background 
  4613. size. 
  4614.  
  4615. Returns 
  4616.  
  4617. This function returns one of the following values: 
  4618.  
  4619. SPR_ERR_NOERROR 
  4620. SPR_ERR_BADHANDLE 
  4621.  
  4622. Notes 
  4623.  
  4624. If the playground has a background bitmap, this function fails with the error 
  4625. SPR_ERR_HASBACKGROUND since the two are mutually exclusive properties. 
  4626.  
  4627. Related information 
  4628.  
  4629. o HCSPLAYGROUND data type 
  4630. o CmnSprQueryPlaygroundBack 
  4631. o CmnSprQueryPlaygroundColor 
  4632. o CmnSprSetPlaygroundBack 
  4633. o CmnSprSetPlaygroundColor 
  4634. o CmnSprSetPlaygroundSize 
  4635.  
  4636.  
  4637. ΓòÉΓòÉΓòÉ 13.12. CmnSprQuerySpritePosition ΓòÉΓòÉΓòÉ
  4638.  
  4639. CmnSprQuerySpritePosition 
  4640.  
  4641. Purpose 
  4642.  
  4643. This function returns the position of the sprite. 
  4644.  
  4645. Syntax 
  4646.  
  4647. (SPRERROR)CmnSprQuerySpritePosition(hsSprite,pptlPos);
  4648.  
  4649. Parameters 
  4650.  
  4651. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4652.  
  4653. pptlPos (PPOINTL) - points to the variable to receive the position of the 
  4654. sprite. 
  4655.  
  4656. Returns 
  4657.  
  4658. This function returns one of the following values: 
  4659.  
  4660. SPR_ERR_NOERROR 
  4661. SPR_ERR_BADHANDLE 
  4662. SPR_ERR_HASNOPLAYGROUND 
  4663.  
  4664. Notes 
  4665.  
  4666. The sprite must belong to a playground to have a position associated with it. 
  4667.  
  4668. Related information 
  4669.  
  4670. o HCSSPRITE data type 
  4671. o CmnSprAddSprite 
  4672. o CmnSprQuerySpriteRect 
  4673. o CmnSprQuerySpriteSize 
  4674. o CmnSprQuerySpriteVisibility 
  4675. o CmnSprRemoveSprite 
  4676. o CmnSprSetSpritePosition 
  4677. o CmnSprSetSpriteVisibility 
  4678.  
  4679.  
  4680. ΓòÉΓòÉΓòÉ 13.13. CmnSprQuerySpriteRect ΓòÉΓòÉΓòÉ
  4681.  
  4682. CmnSprQuerySpriteRect 
  4683.  
  4684. Purpose 
  4685.  
  4686. This function returns the bounding rectangle of the sprite. 
  4687.  
  4688. Syntax 
  4689.  
  4690. (SPRERROR)CmnSprQuerySpriteRect(hsSprite,prclRect);
  4691.  
  4692. Parameters 
  4693.  
  4694. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4695.  
  4696. prclRect (PRECTL) - points to the variable to receive the bounding rectangle of 
  4697. the sprite. 
  4698.  
  4699. Returns 
  4700.  
  4701. This function returns one of the following values: 
  4702.  
  4703. SPR_ERR_NOERROR 
  4704. SPR_ERR_BADHANDLE 
  4705. SPR_ERR_HASNOPLAYGROUND 
  4706.  
  4707. Notes 
  4708.  
  4709. The sprite must belong to a playground to have a position and size associated 
  4710. with it.  The bounding rectangle is calculated as follows: 
  4711.  
  4712. prclRect->xLeft=(current x position)
  4713. prclRect->yBottom=(current y position)
  4714. prclRect->xRight=prclRect->xLeft + (width of the original bitmap passed to
  4715.                                     CmnSprCreateSprite) - 1
  4716. prclRect->yTop=prclRect->yBottom + (height of the original bitmap passed to
  4717.                                     CmnSprCreateSprite) - 1
  4718.  
  4719. Related information 
  4720.  
  4721. o HCSSPRITE data type 
  4722. o CmnSprAddSprite 
  4723. o CmnSprQuerySpritePosition 
  4724. o CmnSprQuerySpriteSize 
  4725. o CmnSprQuerySpriteVisibility 
  4726. o CmnSprRemoveSprite 
  4727. o CmnSprSetSpritePosition 
  4728. o CmnSprSetSpriteVisibility 
  4729.  
  4730.  
  4731. ΓòÉΓòÉΓòÉ 13.14. CmnSprQuerySpriteSize ΓòÉΓòÉΓòÉ
  4732.  
  4733. CmnSprQuerySpriteSize 
  4734.  
  4735. Purpose 
  4736.  
  4737. This function returns the size of the sprite. 
  4738.  
  4739. Syntax 
  4740.  
  4741. (SPRERROR)CmnSprQuerySpriteSize(hsSprite,pszlSize);
  4742.  
  4743. Parameters 
  4744.  
  4745. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4746.  
  4747. pszlSize (PSIZEL) - points to the variable to receive the size of the sprite. 
  4748.  
  4749. Returns 
  4750.  
  4751. This function returns one of the following values: 
  4752.  
  4753. SPR_ERR_NOERROR 
  4754. SPR_ERR_BADHANDLE 
  4755.  
  4756. Notes 
  4757.  
  4758. Since the size of a sprite is static, this is the only function returning the 
  4759. value of a sprite characteristic which does not require the sprite to belong to 
  4760. a playground. 
  4761.  
  4762. Related information 
  4763.  
  4764. o HCSSPRITE data type 
  4765. o CmnSprAddSprite 
  4766. o CmnSprQuerySpritePosition 
  4767. o CmnSprQuerySpriteRect 
  4768. o CmnSprQuerySpriteVisibility 
  4769. o CmnSprRemoveSprite 
  4770. o CmnSprSetSpritePosition 
  4771. o CmnSprSetSpriteVisibility 
  4772.  
  4773.  
  4774. ΓòÉΓòÉΓòÉ 13.15. CmnSprQuerySpriteVisibility ΓòÉΓòÉΓòÉ
  4775.  
  4776. CmnSprQuerySpriteVisibility 
  4777.  
  4778. Purpose 
  4779.  
  4780. This function returns the visibility of the sprite. 
  4781.  
  4782. Syntax 
  4783.  
  4784. (SPRERROR)CmnSprQuerySpriteVisibility(hsSprite,pbVisible);
  4785.  
  4786. Parameters 
  4787.  
  4788. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4789.  
  4790. pbVisible (PBOOL) - points to the variable to receive the visibility state of 
  4791. the sprite. 
  4792.  
  4793. Returns 
  4794.  
  4795. This function returns one of the following values: 
  4796.  
  4797. SPR_ERR_NOERROR 
  4798. SPR_ERR_BADHANDLE 
  4799. SPR_ERR_HASNOPLAYGROUND 
  4800.  
  4801. Notes 
  4802.  
  4803. The sprite must belong to a playground to have a visibility state associated 
  4804. with it. 
  4805.  
  4806. Related information 
  4807.  
  4808. o HCSSPRITE data type 
  4809. o CmnSprAddSprite 
  4810. o CmnSprQuerySpritePosition 
  4811. o CmnSprQuerySpriteRect 
  4812. o CmnSprQuerySpriteSize 
  4813. o CmnSprRemoveSprite 
  4814. o CmnSprSetSpritePosition 
  4815. o CmnSprSetSpriteVisibility 
  4816.  
  4817.  
  4818. ΓòÉΓòÉΓòÉ 13.16. CmnSprQueryUpdateFlag ΓòÉΓòÉΓòÉ
  4819.  
  4820. CmnSprQueryUpdateFlag 
  4821.  
  4822. Purpose 
  4823.  
  4824. This function returns the value of the update flag of a playground. 
  4825.  
  4826. Syntax 
  4827.  
  4828. (SPRERROR)CmnSprQueryUpdateFlag(hpgPlay,pbUpdate);
  4829.  
  4830. Parameters 
  4831.  
  4832. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4833.  
  4834. pbUpdate (PBOOL) - points to the variable to receive the update flag of the 
  4835. playground. 
  4836.  
  4837. Returns 
  4838.  
  4839. This function returns one of the following values: 
  4840.  
  4841. SPR_ERR_NOERROR 
  4842. SPR_ERR_BADHANDLE 
  4843.  
  4844. Related information 
  4845.  
  4846. o HCSPLAYGROUND data type 
  4847. o CmnSprSetUpdateFlag 
  4848.  
  4849.  
  4850. ΓòÉΓòÉΓòÉ 13.17. CmnSprRemoveSprite ΓòÉΓòÉΓòÉ
  4851.  
  4852. CmnSprRemoveSprite 
  4853.  
  4854. Purpose 
  4855.  
  4856. This function removes a sprite from a playground. 
  4857.  
  4858. Syntax 
  4859.  
  4860. (SPRERROR)CmnSprRemoveSprite(hpgPlay,hsSprite);
  4861.  
  4862. Parameters 
  4863.  
  4864. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4865.  
  4866. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4867.  
  4868. Returns 
  4869.  
  4870. This function returns one of the following values: 
  4871.  
  4872. SPR_ERR_NOERROR 
  4873. SPR_ERR_BADHANDLE 
  4874. SPR_ERR_HASNOPLAYGROUND 
  4875.  
  4876. Notes 
  4877.  
  4878. This function must be called before the sprite can be destroyed. 
  4879.  
  4880. Related information 
  4881.  
  4882. o HCSPLAYGROUND data type 
  4883. o HCSSPRITE data type 
  4884. o CmnSprAddSprite 
  4885. o CmnSprCreateSprite 
  4886. o CmnSprDestroySprite 
  4887.  
  4888.  
  4889. ΓòÉΓòÉΓòÉ 13.18. CmnSprSetLayering ΓòÉΓòÉΓòÉ
  4890.  
  4891. CmnSprSetLayering 
  4892.  
  4893. Purpose 
  4894.  
  4895. This function sets the layer of the sprite in the z-order. 
  4896.  
  4897. Syntax 
  4898.  
  4899. (SPRERROR)CmnSprSetLayering(hpsDraw,hsSprite,lPos);
  4900.  
  4901. Parameters 
  4902.  
  4903. hpsDraw (HPS) - handle of the presentation space to draw within. 
  4904.  
  4905. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  4906.  
  4907. lPos (LONG) - specifies the new layer of the sprite. 
  4908.  
  4909. Returns 
  4910.  
  4911. This function returns one of the following values: 
  4912.  
  4913. SPR_ERR_NOERROR 
  4914. SPR_ERR_BADHANDLE 
  4915. SPR_ERR_HASNOPLAYGROUND 
  4916.  
  4917. Related information 
  4918.  
  4919. o CmnSprQueryLayering 
  4920.  
  4921.  
  4922. ΓòÉΓòÉΓòÉ 13.19. CmnSprSetPlaygroundBack ΓòÉΓòÉΓòÉ
  4923.  
  4924. CmnSprSetPlaygroundBack 
  4925.  
  4926. Purpose 
  4927.  
  4928. This function sets the bitmap to be used for the background. 
  4929.  
  4930. Syntax 
  4931.  
  4932. (SPRERROR)CmnSprSetPlaygroundBack(hpgPlay,hbmNew,phbmOld);
  4933.  
  4934. Parameters 
  4935.  
  4936. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4937.  
  4938. hbmNew (HBITMAP) - handle of the new background bitmap. 
  4939.  
  4940. phbmOld (HBITMAP *) - points to the variable to receive the handle of current 
  4941. background bitmap.  This may be NULL. 
  4942.  
  4943. Returns 
  4944.  
  4945. This function returns one of the following values: 
  4946.  
  4947. SPR_ERR_NOERROR 
  4948. SPR_ERR_BADHANDLE 
  4949.  
  4950. Notes 
  4951.  
  4952. The playground also relinquishes ownership of the current background bitmap, 
  4953. meaning it becomes the application's responsibility to insure it is deleted 
  4954. before the application exits. 
  4955.  
  4956. Related information 
  4957.  
  4958. o HCSPLAYGROUND data type 
  4959. o CmnSprQueryPlaygroundBack 
  4960. o CmnSprQueryPlaygroundColor 
  4961. o CmnSprQueryPlaygroundSize 
  4962. o CmnSprSetPlaygroundColor 
  4963. o CmnSprSetPlaygroundSize 
  4964.  
  4965.  
  4966. ΓòÉΓòÉΓòÉ 13.20. CmnSprSetPlaygroundColor ΓòÉΓòÉΓòÉ
  4967.  
  4968. CmnSprSetPlaygroundColor 
  4969.  
  4970. Purpose 
  4971.  
  4972. This function sets the current background color. 
  4973.  
  4974. Syntax 
  4975.  
  4976. (SPRERROR)CmnSprSetPlaygroundColor(hpgPlay,lBackColor);
  4977.  
  4978. Parameters 
  4979.  
  4980. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  4981.  
  4982. lBackColor (LONG) - specifies the new background color. 
  4983.  
  4984. Returns 
  4985.  
  4986. This function returns one of the following values: 
  4987.  
  4988. SPR_ERR_NOERROR 
  4989. SPR_ERR_BADHANDLE 
  4990. SPR_ERR_HASBACKGROUND 
  4991.  
  4992. Notes 
  4993.  
  4994. If the playground has a background bitmap, this function fails with error 
  4995. SPR_ERR_HASBACKGROUND since the two properties are mutual exclusive. 
  4996.  
  4997. Related information 
  4998.  
  4999. o HCSPLAYGROUND data type 
  5000. o CmnSprQueryPlaygroundBack 
  5001. o CmnSprQueryPlaygroundColor 
  5002. o CmnSprQueryPlaygroundSize 
  5003. o CmnSprSetPlaygroundBack 
  5004. o CmnSprSetPlaygroundSize 
  5005.  
  5006.  
  5007. ΓòÉΓòÉΓòÉ 13.21. CmnSprSetPlaygroundSize ΓòÉΓòÉΓòÉ
  5008.  
  5009. CmnSprSetPlaygroundSize 
  5010.  
  5011. Purpose 
  5012.  
  5013. This function sets the size of the playground. 
  5014.  
  5015. Syntax 
  5016.  
  5017. (SPRERROR)CmnSprSetPlaygroundSize(hpgPlay,pszlSize);
  5018.  
  5019. Parameters 
  5020.  
  5021. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  5022.  
  5023. pszlSize (PSIZEL) - points to the variable specifying the new size of the 
  5024. playground. 
  5025.  
  5026. Returns 
  5027.  
  5028. This function returns one of the following values: 
  5029.  
  5030. SPR_ERR_NOERROR 
  5031. SPR_ERR_BADHANDLE 
  5032. SPR_ERR_HASBACKGROUND 
  5033.  
  5034. Notes 
  5035.  
  5036. If the playground has a background bitmap, this function fails with error 
  5037. SPR_ERR_HASBACKGROUND since the two properties are mutual exclusive. 
  5038.  
  5039. Related information 
  5040.  
  5041. o HCSPLAYGROUND data type 
  5042. o CmnSprQueryPlaygroundBack 
  5043. o CmnSprQueryPlaygroundColor 
  5044. o CmnSprQueryPlaygroundSize 
  5045. o CmnSprSetPlaygroundColor 
  5046. o CmnSprSetPlaygroundSize 
  5047.  
  5048.  
  5049. ΓòÉΓòÉΓòÉ 13.22. CmnSprSetSpritePosition ΓòÉΓòÉΓòÉ
  5050.  
  5051. CmnSprSetSpritePosition 
  5052.  
  5053. Purpose 
  5054.  
  5055. This function sets the position of the sprite. 
  5056.  
  5057. Syntax 
  5058.  
  5059. (SPRERROR)CmnSprSetSpritePosition(hpsDraw,hsSprite,pptlNew);
  5060.  
  5061. Parameters 
  5062.  
  5063. hpsDraw (HPS) - handle of the presentation space to draw within. 
  5064.  
  5065. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  5066.  
  5067. pptlNew (PPOINTL) - points to the variable specifying the new position. 
  5068.  
  5069. Returns 
  5070.  
  5071. This function returns one of the following values: 
  5072.  
  5073. SPR_ERR_NOERROR 
  5074. SPR_ERR_BADHANDLE 
  5075. SPR_ERR_HASNOPLAYGROUND 
  5076.  
  5077. Notes 
  5078.  
  5079. The algorithm used by this function is optimized to remove flicker when the 
  5080. bounding rectangle of the sprite at the current position overlaps the bounding 
  5081. rectangle of the sprite at the new position.  If the sprite is not visible, 
  5082. this function returns SPR_ERR_NOERROR. 
  5083.  
  5084. Related information 
  5085.  
  5086. o HCSSPRITE data type 
  5087. o CmnSprQuerySpritePosition 
  5088. o CmnSprQuerySpriteRect 
  5089. o CmnSprQuerySpriteSize 
  5090. o CmnSprQuerySpriteVisibility 
  5091. o CmnSprSetSpriteVisibility 
  5092.  
  5093.  
  5094. ΓòÉΓòÉΓòÉ 13.23. CmnSprSetSpriteVisibility ΓòÉΓòÉΓòÉ
  5095.  
  5096. CmnSprSetSpriteVisibility 
  5097.  
  5098. Purpose 
  5099.  
  5100. This function sets the visibility state of a sprite. 
  5101.  
  5102. Syntax 
  5103.  
  5104. (SPRERROR)CmnSprSetSpriteVisibility(hpsDraw,hsSprite,bVisible);
  5105.  
  5106. Parameters 
  5107.  
  5108. hpsDraw (HPS) - handle of the presentation space to draw within. 
  5109.  
  5110. hsSprite (HCSSPRITE) - handle of the sprite instance. 
  5111.  
  5112. bVisible (BOOL) - specifies the new visibility state. 
  5113.  
  5114. Returns 
  5115.  
  5116. This function returns one of the following values: 
  5117.  
  5118. SPR_ERR_NOERROR 
  5119. SPR_ERR_BADHANDLE 
  5120. SPR_ERR_HASNOPLAYGROUND 
  5121.  
  5122. Related information 
  5123.  
  5124. o HCSSPRITE data type 
  5125. o CmnSprQuerySpritePosition 
  5126. o CmnSprQuerySpriteRect 
  5127. o CmnSprQuerySpriteSize 
  5128. o CmnSprQuerySpriteVisibility 
  5129. o CmnSprSetSpritePosition 
  5130.  
  5131.  
  5132. ΓòÉΓòÉΓòÉ 13.24. CmnSprSetUpdateFlag ΓòÉΓòÉΓòÉ
  5133.  
  5134. CmnSprSetUpdateFlag 
  5135.  
  5136. Purpose 
  5137.  
  5138. This function sets the update flag of the playground. 
  5139.  
  5140. Syntax 
  5141.  
  5142. (SPRERROR)CmnSprSetUpdateFlag(hpgPlay,bUpdate);
  5143.  
  5144. Parameters 
  5145.  
  5146. hpgPlay (HCSPLAYGROUND) - handle of the playground instance. 
  5147.  
  5148. bUpdate (BOOL) - specifies the new update flag value. 
  5149.  
  5150. Returns 
  5151.  
  5152. This function returns one of the following values: 
  5153.  
  5154. SPR_ERR_NOERROR 
  5155. SPR_ERR_BADHANDLE 
  5156.  
  5157. Notes 
  5158.  
  5159. The update flag determines if any drawing actually takes place when any of the 
  5160. functions requiring a presentation space handle are called. 
  5161.  
  5162. Related information 
  5163.  
  5164. o HCSPLAYGROUND data type 
  5165. o CmnSprQueryUpdateFlag 
  5166.  
  5167.  
  5168. ΓòÉΓòÉΓòÉ 14. String routines ΓòÉΓòÉΓòÉ
  5169.  
  5170. The purpose of this group is to provide functions that manipulate strings which 
  5171. and are not provided by the C run time library. 
  5172.  
  5173. Listed below are the functions which comprise this group: 
  5174.  
  5175. o CmnStrConvertToNumber 
  5176. o CmnStrPadString 
  5177. o CmnStrParseCommandLine 
  5178. o CmnStrParseLine 
  5179. o CmnStrQueryWord 
  5180. o CmnStrQueryWordCount 
  5181. o CmnStrQueryWordLength 
  5182. o CmnStrQueryWordPosition 
  5183. o CmnStrStripSpace 
  5184.  
  5185.  
  5186. ΓòÉΓòÉΓòÉ 14.1. CmnStrConvertToNumber ΓòÉΓòÉΓòÉ
  5187.  
  5188. CmnStrConvertToNumber 
  5189.  
  5190. Purpose 
  5191.  
  5192. This function converts a string into its numerical equivalent. 
  5193.  
  5194. Syntax 
  5195.  
  5196. (BOOL)CmnStrConvertToNumber(pchString,pvResult,usType);
  5197.  
  5198. Parameters 
  5199.  
  5200. pchString (PCHAR) - points to the string to convert. 
  5201.  
  5202. pvResult (PVOID) - points to the buffer to receive the result. The size of this 
  5203. buffer depends on the SCTN_TYPE_ constant specified. 
  5204.  
  5205. usType (USHORT) - specifies a combination of one SCTN_TYPE_ constant and one 
  5206. SCTN_ATTR_ constant. 
  5207.  
  5208. Returns 
  5209.  
  5210. This function returns TRUE if successful, or FALSE otherwise. 
  5211.  
  5212. Notes 
  5213.  
  5214. Use CmnStrConvertToNumber to convert a string to a number.  This is preferable 
  5215. to atoi (atol, etc.) because this function returns a definitive indicator of 
  5216. success, whereas the ANSI functions simply return 0 when an error occurs (and 
  5217. this could be a valid value as well). 
  5218.  
  5219. Related information 
  5220.  
  5221. o SCTN_ constants 
  5222.  
  5223.  
  5224. ΓòÉΓòÉΓòÉ 14.2. CmnStrPadString ΓòÉΓòÉΓòÉ
  5225.  
  5226. CmnStrPadString 
  5227.  
  5228. Purpose 
  5229.  
  5230. This function pads a string with a specified character. 
  5231.  
  5232. Syntax 
  5233.  
  5234. (BOOL)CmnStrPadString(pchString,usSide,usLength,chPad);
  5235.  
  5236. Parameters 
  5237.  
  5238. pchString (PCHAR) - points to the string to pad. 
  5239.  
  5240. usSide (USHORT) - specifies the side to pad on as an SPS_ constant. 
  5241.  
  5242. usLength (USHORT) - specifies the desired length of the string. 
  5243.  
  5244. chPad (CHAR) - specifies the character to pad with. 
  5245.  
  5246. Returns 
  5247.  
  5248. This function returns TRUE if successful, or FALSE otherwise. 
  5249.  
  5250. Notes 
  5251.  
  5252. Use CmnStrPadString to pad a string to a specified length. 
  5253.  
  5254. Related information 
  5255.  
  5256. o SPS_ constants 
  5257.  
  5258.  
  5259. ΓòÉΓòÉΓòÉ 14.3. CmnStrParseCommandLine ΓòÉΓòÉΓòÉ
  5260.  
  5261. CmnStrParseCommandLine 
  5262.  
  5263. Purpose 
  5264.  
  5265. This function parses the command line arguments. 
  5266.  
  5267. Syntax 
  5268.  
  5269. (BOOL)CmnStrParseCommandLine(ppchArgs,
  5270.                              usNumArgs,
  5271.                              pccdFormat,
  5272.                              usNumSwitches,
  5273.                              pfnError,
  5274.                              pvData);
  5275.  
  5276. Parameters 
  5277.  
  5278. ppchArgs (PCHAR *) - points to an array of pointers to the command line 
  5279. arguments. 
  5280.  
  5281. usNumArgs (USHORT) - specifies the number of arguments pointed to by ppchArgs. 
  5282.  
  5283. pccdFormat (PCSCMDDESC) - points to an array of CSCMDDESC structures describing 
  5284. the valid command line arguments. 
  5285.  
  5286. usNumSwitches (USHORT) - specifies the number of structures pointed to by 
  5287. pccdFormat. 
  5288.  
  5289. pfnError (PFNCMDERR) - points to a function which is called when an error 
  5290. occurs. 
  5291.  
  5292. pvData (PVOID) - points to application-specific data which is passed to the 
  5293. callback function as the fourth parameter. 
  5294.  
  5295. Returns 
  5296.  
  5297. This function returns TRUE if successful, or FALSE otherwise. 
  5298.  
  5299. Notes 
  5300.  
  5301. Use CmnStrParseCommandLine to parse the command line arguments passed to the 
  5302. application.  For each argument that is described in pccdFormat, the 
  5303. corresponding function is called with the arguments to the command line 
  5304. argument (if any). 
  5305.  
  5306. pfnError is called whenever an error occurs while processing the command line. 
  5307. While this could be a syntax error (returned by the argument processing 
  5308. function), it could also be another error type (out of memory, etc.). 
  5309.  
  5310. Related information 
  5311.  
  5312. o CSCMDDESC data type 
  5313. o PFNCMDERR function 
  5314.  
  5315.  
  5316. ΓòÉΓòÉΓòÉ 14.4. CmnStrParseLine ΓòÉΓòÉΓòÉ
  5317.  
  5318. CmnStrParseLine 
  5319.  
  5320. Purpose 
  5321.  
  5322. This function parses a line of data containing fixed position, fixed length 
  5323. fields. 
  5324.  
  5325. Syntax 
  5326.  
  5327. (SHORT)CmnStrParseLine(pchLine,acFormat,usNumRecs,pbBuf);
  5328.  
  5329. Parameters 
  5330.  
  5331. pchLine (PCHAR) - points to the line to parse. 
  5332.  
  5333. pcFormat (PCSLINEDESC) - points to an array of CSLINEDESC structures describing 
  5334. the fields in the line.  On return, the usType field indicates whether or not 
  5335. the field was empty. 
  5336.  
  5337. usNumRecs (USHORT) - specifies the number of structures pointed to by pcFormat. 
  5338.  
  5339. pbBuf (PBYTE) - points to the buffer to receive the results. On return, the 
  5340. buffer is initialized to the native equivalents of the fields (numeric, string, 
  5341. etc.). 
  5342.  
  5343. Returns 
  5344.  
  5345. This function returns the number of fields successfully parsed, or SPL_ERROR if 
  5346. an error occurred. 
  5347.  
  5348. Notes 
  5349.  
  5350. Use CmnStrParseLine to parse a line consisting of fixed position, fixed length 
  5351. fields similar to the sscanf function.  For example, supposing pchLine points 
  5352. to the following data: 
  5353.  
  5354. 12345This is a string678.90
  5355.  
  5356. Also, pcFormat points to four CSLINEDESC structures, containing the following 
  5357. values: 
  5358.  
  5359. {
  5360.    {
  5361.       0,
  5362.       5,
  5363.       SPL_TYPE_LONG
  5364.    },
  5365.    {
  5366.       21,
  5367.       6,
  5368.       SPL_TYPE_FLOAT
  5369.    },
  5370.    {
  5371.       5,
  5372.       16,
  5373.       SPL_TYPE_STRING
  5374.    },
  5375.    {
  5376.       28,
  5377.       4,
  5378.       SPL_TYPE_BYTE
  5379.    }
  5380. }
  5381. pbBuf points to a structure defined as follows: 
  5382.  
  5383. typedef struct {
  5384.    LONG lField1;
  5385.    float fField2;
  5386.    CHAR achField3[17];
  5387.    BYTE bField4;
  5388. } BUF, FAR *PBUF;
  5389.  
  5390. On exit, pbBuf points to the initialized structure containing 12345, 678.9, 
  5391. "This is a string", and (undefined), and the usType field of the CSLINEDESC 
  5392. structures will be SPL_FOUND, SPL_FOUND, SPL_FOUND, and SPL_NOT_FOUND (to 
  5393. indicate that there was not fourth field). 
  5394.  
  5395. It is imperative to note that if you are using this function, all structures 
  5396. initialized by this function must be "unaligned", i.e. no alignment of fields 
  5397. should be done by the compiler.  If you forget to specify this, unpredictable 
  5398. results will occur. 
  5399.  
  5400. Related information 
  5401.  
  5402. o SPL_ constants 
  5403. o CSLINEDESC data type 
  5404.  
  5405.  
  5406. ΓòÉΓòÉΓòÉ 14.5. CmnStrQueryWord ΓòÉΓòÉΓòÉ
  5407.  
  5408. CmnStrQueryWord 
  5409.  
  5410. Purpose 
  5411.  
  5412. This function returns the specified word in a string. 
  5413.  
  5414. Syntax 
  5415.  
  5416. (BOOL)CmnStrQueryWord(pchLine,sWord,pchWord,usSzWord);
  5417.  
  5418. Parameters 
  5419.  
  5420. pchLine (PCHAR) - points to the line to retrieve the word from. 
  5421.  
  5422. sWord (SHORT) - specifies the 0-based word number to retrieve. 
  5423.  
  5424. pchWord (PCHAR) - points to the buffer to receive the result. On return, the 
  5425. buffer contains the word retrieved. 
  5426.  
  5427. usSzWord (USHORT) - specifies the size of the buffer pointed to by pchWord. 
  5428.  
  5429. Returns 
  5430.  
  5431. This function returns TRUE if successful, or FALSE otherwise. 
  5432.  
  5433. Notes 
  5434.  
  5435. Use CmnStrQueryWord to retrieve a word from a line.  A word is defined as a 
  5436. sequence of letters, digits, and/or punctuation, delimited by whitespace. 
  5437.  
  5438. Related information 
  5439.  
  5440. o CmnStrQueryWordCount 
  5441. o CmnStrQueryWordLength 
  5442. o CmnStrQueryWordPosition 
  5443.  
  5444.  
  5445. ΓòÉΓòÉΓòÉ 14.6. CmnStrQueryWordCount ΓòÉΓòÉΓòÉ
  5446.  
  5447. CmnStrQueryWordCount 
  5448.  
  5449. Purpose 
  5450.  
  5451. This function queries the number of words in a line. 
  5452.  
  5453. Syntax 
  5454.  
  5455. (USHORT)CmnStrQueryWordCount(pchLine);
  5456.  
  5457. Parameters 
  5458.  
  5459. pchLine (PCHAR) - points to the line to query. 
  5460.  
  5461. Returns 
  5462.  
  5463. This function returns the number of words in the specified line. 
  5464.  
  5465. Notes 
  5466.  
  5467. Use CmnStrQueryWordCount to query the number of words in a line of ASCII data. 
  5468.  
  5469. Related information 
  5470.  
  5471. o CmnStrQueryWord 
  5472. o CmnStrQueryWordLength 
  5473. o CmnStrQueryWordPosition 
  5474.  
  5475.  
  5476. ΓòÉΓòÉΓòÉ 14.7. CmnStrQueryWordLength ΓòÉΓòÉΓòÉ
  5477.  
  5478. CmnStrQueryWordLength 
  5479.  
  5480. Purpose 
  5481.  
  5482. This function queries the length of a specified word in a line. 
  5483.  
  5484. Syntax 
  5485.  
  5486. (SHORT)CmnStrQueryWordLength(pchLine,sWord);
  5487.  
  5488. Parameters 
  5489.  
  5490. pchLine (PCHAR) - points to the line to query. 
  5491.  
  5492. sWord (SHORT) - specifies the number of the word to query. 
  5493.  
  5494. Returns 
  5495.  
  5496. This function returns the length of the specified word. 
  5497.  
  5498. Notes 
  5499.  
  5500. Use CmnStrQueryWordLength to query the length of a specified word in a line of 
  5501. ASCII data. 
  5502.  
  5503. Related information 
  5504.  
  5505. o CmnStrQueryWord 
  5506. o CmnStrQueryWordCount 
  5507. o CmnStrQueryWordPosition 
  5508.  
  5509.  
  5510. ΓòÉΓòÉΓòÉ 14.8. CmnStrQueryWordPosition ΓòÉΓòÉΓòÉ
  5511.  
  5512. CmnStrQueryWordPosition 
  5513.  
  5514. Purpose 
  5515.  
  5516. This function queries the position of a specified word in a line. 
  5517.  
  5518. Syntax 
  5519.  
  5520. (SHORT)CmnStrQueryWordPosition(pchLine,sWord);
  5521.  
  5522. Parameters 
  5523.  
  5524. pchLine (PCHAR) - points to the line to query. 
  5525.  
  5526. sWord (SHORT) - specifies the number of the word to query. 
  5527.  
  5528. Returns 
  5529.  
  5530. This function returns the 0-based index of the beginning of the specified word 
  5531. in the line. 
  5532.  
  5533. Notes 
  5534.  
  5535. Use CmnStrQueryWordPosition to query the position of a word in a line of ASCII 
  5536. data. 
  5537.  
  5538. Related information 
  5539.  
  5540. o CmnStrQueryWord 
  5541. o CmnStrQueryWordCount 
  5542. o CmnStrQueryWordLength 
  5543.  
  5544.  
  5545. ΓòÉΓòÉΓòÉ 14.9. CmnStrStripSpace ΓòÉΓòÉΓòÉ
  5546.  
  5547. CmnStrStripSpace 
  5548.  
  5549. Purpose 
  5550.  
  5551. This function strips the whitespace from the beginning and/or the end of a 
  5552. string. 
  5553.  
  5554. Syntax 
  5555.  
  5556. (BOOL)CmnStrStripSpace(pchString,usOptions);
  5557.  
  5558. Parameters 
  5559.  
  5560. pchString (PCHAR) - points to the string to strip. 
  5561.  
  5562. usOptions (USHORT) - specifies the side to strip from as an SPS_ constant. 
  5563.  
  5564. Returns 
  5565.  
  5566. This function returns TRUE if successful, or FALSE otherwise. 
  5567.  
  5568. Notes 
  5569.  
  5570. Use CmnStrStripSpace to strip the white space from a string. 
  5571.  
  5572. Related information 
  5573.  
  5574. o SPS_ constants 
  5575.  
  5576.  
  5577. ΓòÉΓòÉΓòÉ 15. Screen I/O routines ΓòÉΓòÉΓòÉ
  5578.  
  5579. The purpose of this group is to provide miscellaneous text-mode functions. 
  5580.  
  5581. Listed below are the functions which comprise this group: 
  5582.  
  5583. o CmnVioDisplayMessage 
  5584. o CmnVioGetString 
  5585. o CmnVioLoadMessage 
  5586.  
  5587.  
  5588. ΓòÉΓòÉΓòÉ 15.1. CmnVioDisplayMessage ΓòÉΓòÉΓòÉ
  5589.  
  5590. CmnVioDisplayMessage 
  5591.  
  5592. Purpose 
  5593.  
  5594. This function loads a message from a message file and writes it to stderr. 
  5595.  
  5596. Syntax 
  5597.  
  5598. (BOOL)CmnVioDisplayMessage(pchMsgFile,ulId,...);
  5599.  
  5600. Parameters 
  5601.  
  5602. pchMsgFile (PCHAR) - points to the name of the message file. Even if the 
  5603. message file is bound to the executable, this must be the name of the original 
  5604. message file. 
  5605.  
  5606. ulId (ULONG) - specifies the identifier of the message to load. 
  5607.  
  5608. ... (va_list) - specifies any additional arguments referred to by the message. 
  5609.  
  5610. Returns 
  5611.  
  5612. This function returns TRUE if successful, or FALSE otherwise. 
  5613.  
  5614. Notes 
  5615.  
  5616. Use CmnVioDisplayMessage to load and display a message from the specified 
  5617. message file.  Note that while fprintf will allow fields whose descriptors 
  5618. begin with a width specifier (e.g. "%05d%cdq.), this function does not since 
  5619. DosGetMessage attempts to substitute positional parameters when it encounters 
  5620. this. 
  5621.  
  5622.  
  5623. ΓòÉΓòÉΓòÉ 15.2. CmnVioGetString ΓòÉΓòÉΓòÉ
  5624.  
  5625. CmnVioLoadMessage 
  5626.  
  5627. Purpose 
  5628.  
  5629. This function gets a string from the user. 
  5630.  
  5631. Syntax 
  5632.  
  5633. (BOOL)CmnVioGetString(pchBuf,ulSzBuf,ulOptions);
  5634.  
  5635. Parameters 
  5636.  
  5637. pchBuf (PCHAR) - points to the buffer to hold the result.  On return, the 
  5638. buffer contains the string. 
  5639.  
  5640. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pchBuf. 
  5641.  
  5642. ulOptions (ULONG) - one or more VGS_* constants. 
  5643.  
  5644. Returns 
  5645.  
  5646. This function returns TRUE if successful, or FALSE otherwise. 
  5647.  
  5648. Notes 
  5649.  
  5650. Use CmnVioGetString to get a string from the user.  The advantage of using this 
  5651. function instead of a C library function is that this function provides the 
  5652. following: 
  5653.  
  5654. o Cursor movement via left, right, Ctrl-left (word-left), Ctrl-right 
  5655.   (word-right). 
  5656.  
  5657. o Erase contents via Escape key. 
  5658.  
  5659. o Options for unreadable entry and input required. 
  5660.  
  5661. Related information 
  5662.  
  5663. o VGS_ constants 
  5664.  
  5665.  
  5666. ΓòÉΓòÉΓòÉ 15.3. CmnVioLoadMessage ΓòÉΓòÉΓòÉ
  5667.  
  5668. CmnVioLoadMessage 
  5669.  
  5670. Purpose 
  5671.  
  5672. This function loads a message from a message file. 
  5673.  
  5674. Syntax 
  5675.  
  5676. (BOOL)CmnVioLoadMessage(pchMsgFile,ulId,pchBuf,ulSzBuf);
  5677.  
  5678. Parameters 
  5679.  
  5680. pchMsgFile (PCHAR) - points to the name of the message file. Even if the 
  5681. message file is bound to the executable, this must be the name of the original 
  5682. message file. 
  5683.  
  5684. ulId (ULONG) - specifies the identifier of the message to load. 
  5685.  
  5686. pchBuf (PCHAR) - points to the buffer to receive the result. On return, the 
  5687. buffer contains the loaded message. 
  5688.  
  5689. ulSzBuf (ULONG) - specifies the size of the buffer pointed to by pchBuf. 
  5690.  
  5691. Returns 
  5692.  
  5693. This function returns TRUE if successful, or FALSE otherwise. 
  5694.  
  5695. Notes 
  5696.  
  5697. Use CmnVioLoadMessage to load a message from the specified message file.  Note 
  5698. that it is impossible to have a message with simply a carriage-return at the 
  5699. end (versus a carriage-return, line-feed pair), since the toolkit utility 
  5700. MKMSGF indicates this to be a syntax error. 
  5701.  
  5702.  
  5703. ΓòÉΓòÉΓòÉ 16. Windowing routines ΓòÉΓòÉΓòÉ
  5704.  
  5705. The purpose of this group is to provide miscellaneous windowing functions. 
  5706.  
  5707. Listed below are the functions which comprise this group: 
  5708.  
  5709. o CmnWinCenterWindow 
  5710. o CmnWinDisplayMessage 
  5711. o CmnWinRestorePosition 
  5712. o CmnWinRestorePosFromBuffer 
  5713. o CmnWinSavePosition 
  5714. o CmnWinSavePosToBuffer 
  5715.  
  5716.  
  5717. ΓòÉΓòÉΓòÉ 16.1. CmnWinCenterWindow ΓòÉΓòÉΓòÉ
  5718.  
  5719. CmnWinCenterWindow 
  5720.  
  5721. Purpose 
  5722.  
  5723. This function centers a window within its parent. 
  5724.  
  5725. Syntax 
  5726.  
  5727. (VOID)CmnWinCenterWindow(hwndCenter);
  5728.  
  5729. Parameters 
  5730.  
  5731. hwndCenter (HWND) - specifies the handle of the window to center. 
  5732.  
  5733. Notes 
  5734.  
  5735. Use CmnWinCenterWindow to center a window within its parent. 
  5736.  
  5737.  
  5738. ΓòÉΓòÉΓòÉ 16.2. CmnWinDisplayMessage ΓòÉΓòÉΓòÉ
  5739.  
  5740. CmnWinDisplayMessage 
  5741.  
  5742. Purpose 
  5743.  
  5744. This function loads a message from the STRINGTABLE and displays it in a message 
  5745. box. 
  5746.  
  5747. Syntax 
  5748.  
  5749. (SHORT)CmnWinDisplayMessage(hwndParent,
  5750.                             hwndOwner,
  5751.                             ulStyle,
  5752.                             hmDll,
  5753.                             usId,
  5754.                             usHelpId,
  5755.                             ...);
  5756.  
  5757. Parameters 
  5758.  
  5759. hwndParent (HWND) - specifies the handle of the parent window. 
  5760.  
  5761. hwndOwner (HWND) - specifies the handle of the owner window. 
  5762.  
  5763. ulStyle (ULONG) - specifies the style of the message box.  If 0 is specified, 
  5764. MB_INFORMATION | MB_OK is used. 
  5765.  
  5766. hmDll (HMODULE) - specifies the handle to the module containing the STRINGTABLE 
  5767. to load from (or NULL if the .EXE file contains the STRINGTABLE). 
  5768.  
  5769. usId (USHORT) - specifies the identifier of the message to load. 
  5770.  
  5771. usHelpId (USHORT) - specifies the identifier that is used when calling the help 
  5772. hook.  If this is 0, no help button is shown in the message box. 
  5773.  
  5774. ... (va_list) - specifies any additional arguments referred to by the message. 
  5775.  
  5776. Returns 
  5777.  
  5778. This function returns the same result as WinMessageBox. 
  5779.  
  5780. Notes 
  5781.  
  5782. Use CmnWinDisplayMessage to load a message and display it on the screen. 
  5783.  
  5784.  
  5785. ΓòÉΓòÉΓòÉ 16.3. CmnWinRestorePosition ΓòÉΓòÉΓòÉ
  5786.  
  5787. CmnWinRestorePosition 
  5788.  
  5789. Purpose 
  5790.  
  5791. This function restores the position of a window previously saved with 
  5792. CmnWinSavePosition. 
  5793.  
  5794. Syntax 
  5795.  
  5796. (BOOL)CmnWinRestorePosition(hwndWindow,
  5797.                             hiniProfile,
  5798.                             pchAppl,
  5799.                             pchKey);
  5800.  
  5801. Parameters 
  5802.  
  5803. hwndWindow (HWND) - specifies the handle of the window to restore. 
  5804.  
  5805. hiniProfile (HINI) - specifies the .INI file handle containing the saved 
  5806. position information. 
  5807.  
  5808. pchAppl (PCHAR) - points to the application name that the positional 
  5809. information was saved under. 
  5810.  
  5811. pchKey (PCHAR) - points to the key name that the positional information was 
  5812. saved under. 
  5813.  
  5814. Returns 
  5815.  
  5816. This function returns TRUE if successful, or FALSE otherwise. 
  5817.  
  5818. Notes 
  5819.  
  5820. Use CmnWinRestorePosition to restore the position of a window previously saved 
  5821. with CmnWinSavePosition.  For MDI applications, you should use the 
  5822. CmnWinSavePosToBuffer and CmnWinRestorePosFromBuffer function. 
  5823.  
  5824. Related information 
  5825.  
  5826. o CmnWinSavePosition 
  5827.  
  5828.  
  5829. ΓòÉΓòÉΓòÉ 16.4. CmnWinRestorePosFromBuffer ΓòÉΓòÉΓòÉ
  5830.  
  5831. CmnWinRestorePosFromBuffer 
  5832.  
  5833. Purpose 
  5834.  
  5835. This function restores the position of a window previously saved with 
  5836. CmnWinSavePosToBuffer. 
  5837.  
  5838. Syntax 
  5839.  
  5840. BOOL CmnWinRestorePosFromBuffer(hwndWindow,pcpPosition);
  5841.  
  5842. Parameters 
  5843.  
  5844. hwndWindow (HWND) - the handle of the window to restore 
  5845.  
  5846. pcpPosition (PCWPOSITION) - points to the variable containing the information 
  5847. to be used when restoring 
  5848.  
  5849. Returns 
  5850.  
  5851. This function returns TRUE if successful, or FALSE otherwise. 
  5852.  
  5853. Notes 
  5854.  
  5855. Use CmnWinRestorePosFromBuffer to restore a window's size and position from the 
  5856. information saved by CmnWinSavePosToBuffer. 
  5857.  
  5858. Related information 
  5859.  
  5860. o CWPOSITION data type 
  5861. o CmnWinSavePosToBuffer 
  5862.  
  5863.  
  5864. ΓòÉΓòÉΓòÉ 16.5. CmnWinSavePosition ΓòÉΓòÉΓòÉ
  5865.  
  5866. CmnWinSavePosition 
  5867.  
  5868. Purpose 
  5869.  
  5870. This function saves the position of a window to be restored later with 
  5871. CmnWinRestorePosition. 
  5872.  
  5873. Syntax 
  5874.  
  5875. (BOOL)CmnWinSavePosition(hwndWindow,
  5876.                          hiniProfile,
  5877.                          pchAppl,
  5878.                          pchKey);
  5879.  
  5880. Parameters 
  5881.  
  5882. hwndWindow (HWND) - specifies the handle of the window to restore. 
  5883.  
  5884. hiniProfile (HINI) - specifies the .INI file handle to which the saved position 
  5885. information will be written. 
  5886.  
  5887. pchAppl (PCHAR) - points to the application name that the positional 
  5888. information will be saved under. 
  5889.  
  5890. pchKey (PCHAR) - points to the key name that the positional information will be 
  5891. saved under. 
  5892.  
  5893. Returns 
  5894.  
  5895. This function returns TRUE if successful, or FALSE otherwise. 
  5896.  
  5897. Notes 
  5898.  
  5899. Use CmnWinSavePosition to save the current size and position of the specified 
  5900. window for restoration at a later time. 
  5901.  
  5902. Related information 
  5903.  
  5904. o CmnWinRestorePosition 
  5905.  
  5906.  
  5907. ΓòÉΓòÉΓòÉ 16.6. CmnWinSavePosToBuffer ΓòÉΓòÉΓòÉ
  5908.  
  5909. CmnWinSavePosToBuffer 
  5910.  
  5911. Purpose 
  5912.  
  5913. This function saves the position of a window to a buffer for later use with 
  5914. CmnWinRestorePosFromBuffer. 
  5915.  
  5916. Syntax 
  5917.  
  5918. BOOL CmnWinSavePosToBuffer(hwndWindow,pcpPosition);
  5919.  
  5920. Parameters 
  5921.  
  5922. hwndWindow (HWND) - the handle of the window to restore 
  5923.  
  5924. pcpPosition (PCWPOSITION) - points to the variable to contain the information 
  5925. to be used when restoring 
  5926.  
  5927. Returns 
  5928.  
  5929. This function returns TRUE if successful, or FALSE otherwise. 
  5930.  
  5931. Notes 
  5932.  
  5933. Use CmnWinSavePosToBuffer to save a window's size and position so that it can 
  5934. be later restored using CmnWinRestorePosFromBuffer. 
  5935.  
  5936. Related information 
  5937.  
  5938. o CWPOSITION data type 
  5939. o CmnWinRestorePosFromBuffer 
  5940.  
  5941.  
  5942. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5943.  
  5944. Constant                      Meaning 
  5945. CCI_TYPE_CLIENT               Specifies that the connection type is (to be) 
  5946.                               client. 
  5947. CCI_TYPE_SERVER               Specifies that the connection type is (to be) 
  5948.                               server. 
  5949. CCI_TYPE_SERVERCONNECT        Specifies that the connection type is a server 
  5950.                               data connection to a client.  This can never be 
  5951.                               specified for CmnComOpenConnection. 
  5952. CCI_TYPE_CLIENTSERVER         Specifies that the connection type is (to be) 
  5953.                               client or server. 
  5954. CCI_ATTR_NOACKS               Specifies that no acknowledgements are to be 
  5955.                               requested by CmnComWriteData.  This is useful for 
  5956.                               eliminating overhead for transaction-based 
  5957.                               protocols where the applications must implement 
  5958.                               their own acknowledgements. 
  5959.  
  5960.  
  5961. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5962.  
  5963. Constant                      Meaning 
  5964. CSC_CLOSE                     specifies that the connection should be closed. 
  5965. CSC_RESET                     specifies that the connection should be reset. 
  5966.                               "Reset" is an abstract term that is defined by 
  5967.                               the application. 
  5968.  
  5969.  
  5970. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5971.  
  5972. A 32-bit handle used to specify a connection.  This handle is created by either 
  5973. CmnComOpenConnection or CmnComWaitConnection and is destroyed by 
  5974. CmnComCloseConnection. 
  5975.  
  5976. Related information 
  5977.  
  5978. o CmnComCloseConnection 
  5979. o CmnComOpenConnection 
  5980. o CmnComWaitConnection 
  5981.  
  5982.  
  5983. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  5984.  
  5985. typedef struct _CCOPENINFO {
  5986.    CHAR achMachine[MAX_CONNECTNAME+1];
  5987.    CHAR achConnect[MAX_CONNECTNAME+1];
  5988.    USHORT usAttr;
  5989.    LONG lTimeout;
  5990. } CCOPENINFO, FAR *PCCOPENINFO;
  5991.  
  5992. achMachine                    Specifies the name of the remote machine to 
  5993.                               connect to.  If this is an empty string, the 
  5994.                               connection is created locally. 
  5995. achConnect                    Specifies the name of the connection. 
  5996. usAttr                        Specifies a CCI_TYPE_* constant and zero or more 
  5997.                               CCI_ATTR_* constants. 
  5998. lTimeout                      Specifies the timeout, in seconds, for 
  5999.                               connections, data reading, and acknowledgement 
  6000.                               waiting. If this value is CCI_ATTR_NOTIMEOUT, no 
  6001.                               timeout will occur. 
  6002.  
  6003. Related information 
  6004.  
  6005. o CCI_ constants 
  6006.  
  6007.  
  6008. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6009.  
  6010. typedef struct _CCCONNECTINFO {
  6011.    CHAR achConnect[MAX_CONNECTNAME+1];
  6012.    USHORT usAttr;
  6013.    ULONG ulSzData;
  6014.    LONG lTimeout;
  6015. } CCCONNECTINFO, FAR *PCCCONNECTINFO;
  6016.  
  6017. achConnect                    Specifies the fully qualified name of the 
  6018.                               connection.  For clients, this will not be the 
  6019.                               name of the connection specified in the 
  6020.                               CCOPENINFO structure on the call to 
  6021.                               CmnComOpenConnection. 
  6022. usAttr                        Specifies the type of the connection and any 
  6023.                               associated attributes.  These are defined as CCI_ 
  6024.                               constants. 
  6025. ulSzData                      Specifies the size, in bytes, of any data waiting 
  6026.                               to be read.  This is the same value that is 
  6027.                               returned by CmnComQueryData. 
  6028. lTimeout                      Specifies the timeout value, in seconds. 
  6029.  
  6030. For calls to CmnSetHandleInfo, lTimeout is the only field that is used.  All 
  6031. others are ignored. 
  6032.  
  6033. Related information 
  6034.  
  6035. o CCI_ constants 
  6036. o CmnSetHandleInfo 
  6037. o CmnComOpenConnection 
  6038. o CmnComQueryData 
  6039.  
  6040.  
  6041. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6042.  
  6043. Constant                      Meaning 
  6044. DWT_TYPE_NAME                 specifies that the file argument points to the 
  6045.                               file name 
  6046. DWT_TYPE_FILE                 specifies that the file argument points to a FILE 
  6047.                               structure 
  6048.  
  6049.  
  6050. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6051.  
  6052. Constant                      Meaning 
  6053. FCS_ATTR_NORMAL               specifies normal files 
  6054. FCS_ATTR_READONLY             specifies read-only files 
  6055. FCS_ATTR_HIDDEN               specifies hidden files 
  6056. FCS_ATTR_SYSTEM               specifies system files 
  6057. FCS_ATTR_DIRECTORY            specifies directories 
  6058. FCS_ATTR_ARCHIVED             specifies archived files 
  6059.  
  6060.  
  6061. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6062.  
  6063. Constant                      Meaning 
  6064. FEA_TYPE                      specifes the "Type" extended attribute 
  6065. FEA_KEYPHRASES                specifes the "Key phrases" extended attribute 
  6066. FEA_SUBJECT                   specifes the "Subject" extended attribute 
  6067. FEA_COMMENTS                  specifes the "Comments" extended attribute 
  6068. FEA_HISTORY                   specifes the "History" extended attribute 
  6069. FEA_VERSION                   specifes the "Version" extended attribute 
  6070. FEA_ICON                      specifes the "Icon" extended attribute 
  6071. FEA_ASSOCTABLE                specifes the "Assoctable" extended attribute 
  6072. FEA_HPFSNAME                  specifes the "HPFS name" extended attribute 
  6073.  
  6074.  
  6075. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6076.  
  6077. Constant                      Meaning 
  6078. FCD_OPT_WANTFORMATTED         specifies that the function should fail if the 
  6079.                               destination diskette is not already formatted. 
  6080.                               If this option is not specified, and the 
  6081.                               destination diskette is not formatted, 
  6082.                               CmnFilFormatDiskette is called to format the 
  6083.                               diskette. 
  6084.  
  6085. Related information 
  6086.  
  6087. o CmnFilFormatDiskette 
  6088.  
  6089.  
  6090. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6091.  
  6092. Constant                      Meaning 
  6093. FCD_TYPE_ERROR                specifies that the value of the second parameter 
  6094.                               of pfnCallback is an FCD_ERR_* constant. 
  6095. FCD_TYPE_MESSAGE              specifies that the value of the second parameter 
  6096.                               of pfnCallback is an FCD_MSG_* constant.  The 
  6097.                               return value of pfnCallback is determined by this 
  6098.                               FCD_MSG_* constant. 
  6099. FCD_TYPE_PROGRESS             specifies that the value of the second parameter 
  6100.                               of pfnCallback is a number in the range 0-100 
  6101.                               which specifies the percentage complete of the 
  6102.                               current operation (read, write, etc.). 
  6103.  
  6104.  
  6105. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6106.  
  6107. Constant                      Meaning 
  6108. FCD_MSG_BEGINFORMAT           specifies that the format operation is beginning. 
  6109. FCD_MSG_BEGINREAD             specifies that the read of the source diskette is 
  6110.                               beginning. 
  6111. FCD_MSG_BEGINVERIFY           specifies that the verify of the destination 
  6112.                               diskette is beginning. 
  6113. FCD_MSG_BEGINWRITE            specifies that the write of the destination 
  6114.                               diskette is beginning. 
  6115. FCD_MSG_ENDFORMAT             specifies that the format operation has completed 
  6116.                               successfully. 
  6117. FCD_MSG_ENDREAD               specifies that the source diskette was 
  6118.                               successfully read. 
  6119. FCD_MSG_ENDVERIFY             specifies that the destination diskette was 
  6120.                               successfully verified. 
  6121. FCD_MSG_ENDWRITE              specifies that the destination diskette was 
  6122.                               successfully written. 
  6123. FCD_MSG_SIZEMISMATCH          specifies that the source and destination 
  6124.                               diskette sizes do not match. pfnCallback should 
  6125.                               return TRUE if a new diskette has been inserted 
  6126.                               and the operation should be retried or FALSE if 
  6127.                               the copy operation should be halted. 
  6128. FCD_MSG_VALIDATESRCDISK       specifies that pfnCallback should verify that the 
  6129.                               source diskette is the desired one to be copied. 
  6130.                               This is usually done by calling CmnFilQueryLabel 
  6131.                               to check the diskette label. pfnCallback should 
  6132.                               return TRUE if the correct diskette is in the 
  6133.                               drive or FALSE otherwise.  Returning FALSE causes 
  6134.                               CmnFilCopyDiskette to resend the 
  6135.                               FCD_MSG_WANTSRCDISK message. 
  6136. FCD_MSG_WANTDESTDISK          specifies that the destination diskette should be 
  6137.                               inserted in the drive. This is sent if the source 
  6138.                               and destination drives are the same and the 
  6139.                               source diskette was successfully read or if there 
  6140.                               is no diskette in the destination drive. 
  6141.                               pfnCallback should return TRUE if the diskette 
  6142.                               has been inserted and the operation should be 
  6143.                               retried or FALSE if the copy operation should be 
  6144.                               halted. 
  6145. FCD_MSG_WANTFORMATDISK        specifies that the diskette to be formatted 
  6146.                               should be inserted in the drive.  pfnCallback 
  6147.                               should return TRUE if the diskette has been 
  6148.                               inserted and the operation should be retried or 
  6149.                               FALSE if the format operation should be halted. 
  6150. FCD_MSG_WANTSRCDISK           specifies that the source diskette should be 
  6151.                               inserted in the drive.  This is sent if there is 
  6152.                               no diskette in the destination drive. pfnCallback 
  6153.                               should return TRUE if the diskette has been 
  6154.                               inserted and the operation should be retried or 
  6155.                               FALSE if the copy operation should be halted. 
  6156. FCD_MSG_WRITEPROTECTED        specifies that the destination diskette is 
  6157.                               write-protected. pfnCallback should return TRUE 
  6158.                               if this condition has been corrected and the 
  6159.                               operation should be retried or FALSE if the copy 
  6160.                               operation should be halted. 
  6161.  
  6162.  
  6163. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6164.  
  6165. Constant                      Meaning 
  6166. FCD_ERR_ABORTED               specifies that the operation was halted because 
  6167.                               pfnCallback returned FALSE for an FCD_MSG_* 
  6168.                               constant whose return value is significant. 
  6169. FCD_ERR_CLOSEFAILED           specifies that an attempt to close the diskette 
  6170.                               failed. 
  6171. FCD_ERR_DESTDRVINVALID        specifies that the destination drive specified 
  6172.                               does not support removable media. 
  6173. FCD_ERR_FORMATFAILED          specifies that the format operation failed. 
  6174. FCD_ERR_LOCKFAILED            specifies that either the source or destination 
  6175.                               drive could not be "locked". 
  6176. FCD_ERR_NOMEMORY              specifies that there is not enough memory to hold 
  6177.                               the contents of the source diskette. 
  6178. FCD_ERR_OPENFAILED            specifies that an attempt to open the diskette 
  6179.                               failed. 
  6180. FCD_ERR_READFAILED            specifies that a read operation failed. 
  6181. FCD_ERR_SRCDRVINVALID         specifies that the source drive specified does 
  6182.                               not support removable media. 
  6183. FCD_ERR_UNLOCKFAILED          specifies that either the source or destination 
  6184.                               drive could not be "unlocked". 
  6185. FCD_ERR_VERIFYFAILED          specifies that the verify operation failed. 
  6186. FCD_ERR_WRITEFAILED           specifies that a write operation failed. 
  6187.  
  6188.  
  6189. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6190.  
  6191. A 32-bit handle used for file searches.  It is created using the function 
  6192. CmnFilCreateSearch and is destroyed using the function CmnFilDestroySearch. 
  6193.  
  6194. Related information 
  6195.  
  6196. o CmnFilCreateSearch 
  6197. o CmnFilDestroySearch 
  6198.  
  6199.  
  6200. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6201.  
  6202. Constant                      Meaning 
  6203. CFFI_SECTOR_128B              specifies 128 bytes per sector 
  6204. CFFI_SECTOR_256B              specifies 256 bytes per sector 
  6205. CFFI_SECTOR_512B              specifies 512 bytes per sector 
  6206. CFFI_SECTOR_1024B             specifies 1024 bytes per sector 
  6207.  
  6208.  
  6209. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6210.  
  6211. Format parameters 
  6212.  
  6213. typedef struct _CFFORMATINFO {
  6214.    ULONG ulSzStruct;
  6215.    ULONG ulNumTracks;
  6216.    ULONG ulNumSectors;
  6217.    ULONG ulSzSector;
  6218. } CFFORMATINFO, *PCFFORMATINFO;
  6219.  
  6220. ulSzStruct                    specifies the size of the structure in bytes. 
  6221. ulNumTracks                   specifies the desired number of tracks. 
  6222. ulNumSectors                  specifies the number of sectors per track. 
  6223. ulSzSector                    specifies a CFFI_SECTOR_* constant describing the 
  6224.                               size of each sector. 
  6225.  
  6226. Standard formats are listed below: 
  6227.  
  6228. 360 KB (5.25 inch)            ulNumTracks=40, ulNumSectors=9, 
  6229.                               ulSzSector=CFFI_SECTOR_512B 
  6230. 720 KB (3.5 inch)             ulNumTracks=80, ulNumSectors=9, 
  6231.                               ulSzSector=CFFI_SECTOR_512B 
  6232. 1.2 MB (5.25 inch)            ulNumTracks=80, ulNumSectors=15, 
  6233.                               ulSzSector=CFFI_SECTOR_512B 
  6234. 1.44 MB (3.5 inch)            ulNumTracks=80, ulNumSectors=18, 
  6235.                               ulSzSector=CFFI_SECTOR_512B 
  6236. 2.88 MB (3.5 inch)            ulNumTracks=80, ulNumSectors=36, 
  6237.                               ulSzSector=CFFI_SECTOR_512B 
  6238.  
  6239. It is recommended that your application use a standard format since unexpected 
  6240. results may occur otherwise (due to limitations in the file system drivers 
  6241. and/or hardware). 
  6242.  
  6243. Related information 
  6244.  
  6245. o CFFI_SECTOR_ constants 
  6246.  
  6247.  
  6248. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6249.  
  6250. typedef BOOL (* EXPENTRY PFNDISKIO)(ULONG,ULONG,PVOID);
  6251.  
  6252. Input 
  6253.  
  6254. ULONG               specifies an FCD_TYPE_* constant which describes how the 
  6255.                     next parameter is to be interpreted. 
  6256. ULONG               depending on the value of the last parameter: 
  6257.  
  6258.    FCD_TYPE_PROGRESS   specifies a value in the range 0-100 which specifies the 
  6259.                        progress of the copy operation. 
  6260.    FCD_TYPE_MESSAGE    specifies an FCD_MSG_* constant. 
  6261.    FCD_TYPE_ERROR      specifies an FCD_ERR_* constant. 
  6262. PVOID               specifies the user data passed to the CmnFilCopyDiskette 
  6263.                     function. 
  6264.  
  6265. For FCF_TYPE_PROGRESS, this function returns TRUE if the operation is to 
  6266. continue, or FALSE if the operation is to be halted.  For FCD_TYPE_MESSAGE, the 
  6267. return value may or may not be significant, depending on the specific FCD_MSG_* 
  6268. constant passed. 
  6269.  
  6270. Related information 
  6271.  
  6272. o FCD_TYPE_ constants 
  6273. o FCD_MSG_ constants 
  6274. o FCD_ERR_ constants 
  6275.  
  6276.  
  6277. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6278.  
  6279. Constant                      Meaning 
  6280. LAR_TAIL                      specifies that the record should be inserted at 
  6281.                               the end of the list. 
  6282. LAR_HEAD                      specifies that the record should be inserted at 
  6283.                               the beginning of the list. 
  6284.  
  6285.  
  6286. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6287.  
  6288. Constant                      Meaning 
  6289. LQR_END                       specifies that the last record should be returned 
  6290. LQR_PREVIOUS                  specifies that the previous record should be 
  6291.                               returned 
  6292. LQR_NEXT                      specifies that the next record should be returned 
  6293.  
  6294.  
  6295. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6296.  
  6297. A 32-bit handle used to specify a linked list.  It is created using the 
  6298. function CmnLstCreateList and is destroyed using the function 
  6299. CmnLstDestroyList. 
  6300.  
  6301. Related information 
  6302.  
  6303. o CmnLstCreateList 
  6304. o CmnLstDestroyList 
  6305.  
  6306.  
  6307. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6308.  
  6309. typedef struct _CLLISTINFO {
  6310.    USHORT usSzRecord;
  6311.    USHORT usNumRecords;
  6312.    PVOID pvHead;
  6313.    PVOID pvTail;
  6314. } CLLISTINFO, FAR *PCLLISTINFO;
  6315.  
  6316. usSzRecord                    Contains the size of each record in the list. 
  6317. usNumRecords                  Contains the number of records currently in the 
  6318.                               list. 
  6319. pvHead                        Points to the head of the list. 
  6320. pvTail                        Points to the tail of the list. 
  6321.  
  6322.  
  6323. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6324.  
  6325. typedef SHORT (* EXPENTRY PFNRECCOMP)(PVOID,PVOID,PVOID);
  6326. //-------------------------------------------------------------------------
  6327. // SHORT EXPENTRY pfnRecComp(PVOID pvFirst,PVOID pvSecond,PVOID pvData);
  6328. //-------------------------------------------------------------------------
  6329.  
  6330. Input 
  6331.  
  6332. pvFirst (PVOID)     Points to the first record to be compared 
  6333. pvSecond (PVOID)    Points to the second record to be compared 
  6334. pvData (PVOID)      Points to application-defined data 
  6335.  
  6336. Returns 
  6337.  
  6338. -1                  If the first parameter is "less than" the second parameter 
  6339. 0                   If the first parameter is "equal to" the second parameter 
  6340. 1                   If the first parameter is "greater than" the second 
  6341.                     parameter 
  6342.  
  6343.  
  6344. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6345.  
  6346. typedef VOID (* EXPENTRY PFNRECFUNC)(PVOID,PVOID);
  6347. //-------------------------------------------------------------------------
  6348. // SHORT EXPENTRY pfnRecFunc(PVOID pvRecord,PVOID pvData);
  6349. //-------------------------------------------------------------------------
  6350.  
  6351. Input 
  6352.  
  6353. pvRecord (PVOID)    Points to a record in the list 
  6354. pvData (PVOID)      Points to application-defined data 
  6355.  
  6356.  
  6357. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6358.  
  6359. typedef BOOL (* EXPENTRY PFNRECMED)(HCLLIST,PVOID,PVOID);
  6360. //-------------------------------------------------------------------------
  6361. // SHORT EXPENTRY pfnRecMed(HCLLIST hclSubList,PVOID pvBuffer,PVOID pvData);
  6362. //-------------------------------------------------------------------------
  6363.  
  6364. Input 
  6365.  
  6366. hclSubList (HCLLIST) Handle to the list to find the median of 
  6367. pvBuffer (PVOID)    Points to a buffer large enough to hold a single record 
  6368. pvData (PVOID)      Points to application-defined data 
  6369.  
  6370. Output 
  6371.  
  6372. pvBuffer (PVOID)    Points to a buffer containing the median of the specified 
  6373.                     list 
  6374.  
  6375. Returns 
  6376.  
  6377. TRUE if successful, FALSE otherwise 
  6378.  
  6379.  
  6380. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6381.  
  6382. A 32-bit handle used to specify a memory manager instance.  it is created using 
  6383. the function CmnMemInitialize and is destroyed using the function 
  6384. CmnMemTerminate. 
  6385.  
  6386. Related information 
  6387.  
  6388. o CmnMemInitialize 
  6389. o CmnMemTerminate 
  6390.  
  6391.  
  6392. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6393.  
  6394. typedef struct _CMMEMINFO {
  6395.    USHORT usNumHeaps;
  6396.    ULONG ulSzHeap;
  6397.    ULONG ulMemUsed;
  6398. } CMMEMINFO, FAR *PCMMEMINFO;
  6399.  
  6400. usNumHeaps                    Contains the number of internal heaps to be used 
  6401.                               by the memory management routines.  The default 
  6402.                               is 256. 
  6403. ulSzHeaps                     Contains the size of each heap.  The default is 
  6404.                               61440. 
  6405. ulMemUsed                     Contains the amount of memory currently allocated 
  6406.                               by this memory handle. This field is ignored by 
  6407.                               CmnMemInitialize(). 
  6408.  
  6409.  
  6410. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6411.  
  6412. A 32-bit handle used to specify an object manager instance.  it is created 
  6413. using the function CmnObjInitialize and is destroyed using the function 
  6414. CmnObjTerminate. 
  6415.  
  6416. Related information 
  6417.  
  6418. o CmnObjInitialize 
  6419. o CmnObjTerminate 
  6420.  
  6421.  
  6422. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6423.  
  6424. typedef struct _COOBJECTINFO {
  6425.    HCOOBJECT hcoParent;
  6426.    CHAR achName[MAX_OBJECTNAME+1];
  6427.    ULONG ulSzData;
  6428.    PVOID pvData;
  6429.    USHORT usNumChildren;
  6430.    ULONG ulReserved;
  6431. } COOBJECTINFO, FAR *PCOOBJECTINFO;
  6432.  
  6433. hcoParent                     Specifies the handle of the parent object.  If 
  6434.                               NULL then this is the root object. 
  6435. achName                       Specifies the fully qualified name of the object. 
  6436. ulSzData                      Specifies the size of the object-data. 
  6437. pvData                        Points to the object-data.  Using this field is 
  6438.                               discouraged, since this points to the 
  6439.                               object-manager's copy of the data.  Instead, use 
  6440.                               the CmnObjQueryObjectData function. 
  6441. usNumChildren                 Specifies the number of immediate children. 
  6442. ulReserved                    Reserved, though it might not be zero. 
  6443.  
  6444. Related information 
  6445.  
  6446. o CmnObjQueryObjectData 
  6447.  
  6448.  
  6449. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6450.  
  6451. A 32-bit handle used to specify a set.  It is created using the function 
  6452. CmnSetCreateSet and is destroyed using the function CmnSetDestroySet. 
  6453.  
  6454. Related information 
  6455.  
  6456. o CmnSetCreateSet 
  6457. o CmnSetDestroySet 
  6458.  
  6459.  
  6460. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6461.  
  6462. typedef struct _CSSETINFO {
  6463.    ULONG ulMaxElements;
  6464.    ULONG ulElementsSet;
  6465. } CSSETINFO, FAR *PCSSETINFO;
  6466.  
  6467. ulMaxElements                 specifies the size of the set 
  6468. ulElementsSet                 specifies the number of elements currently set in 
  6469.                               the set 
  6470.  
  6471.  
  6472. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6473.  
  6474. Constant                      Meaning 
  6475. SWS_TIMEOUT_IMMEDIATE         specifies that the function should return 
  6476.                               immediately if the condition fails 
  6477. SWS_TIMEOUT_NEVER             specifies that the function should never return 
  6478.                               until the condition is met 
  6479.  
  6480.  
  6481. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6482.  
  6483. A 32-bit handle used to specify a signal.  It is created using the function 
  6484. CmnSigCreateSignal and is destroyed using the function CmnSigDestroySignal. 
  6485.  
  6486. Related information 
  6487.  
  6488. o CmnSigCreateSignal 
  6489. o CmnSigDestroySignal 
  6490.  
  6491.  
  6492. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6493.  
  6494. A 32-bit handle used to specify a signal list.  It is created using the 
  6495. function CmnSigCreateSignalList and is destroyed using the function 
  6496. CmnSigDestroySignalList. 
  6497.  
  6498. Related information 
  6499.  
  6500. o CmnSigCreateSignalList 
  6501. o CmnSigDestroySignalList 
  6502.  
  6503.  
  6504. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6505.  
  6506. A 32-bit handle used to specify a playground instance.  This is created by the 
  6507. CmnSprCreatePlayground function and is destroyed by the CmnSprDestroyPlayground 
  6508. function.  Sprites must be added to a playground before they can be manipulated 
  6509. in any way. 
  6510.  
  6511. Related information 
  6512.  
  6513. o CmnSprAddSprite 
  6514. o CmnSprCreatePlayground 
  6515. o CmnSprDestroyPlayground 
  6516. o CmnSprRemoveSprite 
  6517.  
  6518.  
  6519. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6520.  
  6521. A 32-bit handle used to specify a sprite instance.  This is created by the 
  6522. CmnSprCreateSprite function and is destroyed by the CmnSprDestroySprite 
  6523. function.  Sprites must be added to a playground before they can be manipulated 
  6524. in any way. 
  6525.  
  6526. Related information 
  6527.  
  6528. o CmnSprAddSprite 
  6529. o CmnSprCreateSprite 
  6530. o CmnSprDestroySprite 
  6531. o CmnSprRemoveSprite 
  6532.  
  6533.  
  6534. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6535.  
  6536. Constant                      Meaning 
  6537. SCTN_TYPE_BYTE                specifies that the ASCII data represents a byte 
  6538.                               of data 
  6539. SCTN_TYPE_SHORT               specifies that the ASCII data represents a short 
  6540.                               integer (2 bytes) 
  6541. SCTN_TYPE_LONG                specifies that the ASCII data represents a long 
  6542.                               integer (4 bytes) 
  6543. SCTN_TYPE_FLOAT               specifies that the ASCII data represents a 
  6544.                               single-precision floating point number 
  6545. SCTN_TYPE_DOUBLE              specifies that the ASCII data represents a 
  6546.                               double-precision floating point number 
  6547.  
  6548. The following are attribute constants which can be or'd with the above type 
  6549. constants. 
  6550.  
  6551. Constant                      Meaning 
  6552. SCTN_ATTR_DECIMAL             specifies that the number represented in ASCII is 
  6553.                               in decimal 
  6554. SCTN_ATTR_HEX                 specifies that the number represented in ASCII is 
  6555.                               in hexadecimal 
  6556.  
  6557.  
  6558. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6559.  
  6560. Constant                      Meaning 
  6561. SPL_TYPE_BYTE                 specifies that the field represents a byte of 
  6562.                               data 
  6563. SPL_TYPE_CHAR                 specifies that the field represents a character 
  6564.                               of data 
  6565. SPL_TYPE_STRING               specifies that the field represents a string of 
  6566.                               characters.  Note that the length of the field 
  6567.                               does not include the terminating `\0'. 
  6568. SPL_TYPE_SHORT                specifies that the field represents a short 
  6569.                               integer (2 bytes) 
  6570. SPL_TYPE_LONG                 specifies that the field represents a long 
  6571.                               integer (4 bytes) 
  6572. SPL_TYPE_FLOAT                specifies that the field represents a 
  6573.                               single-precision floating point number 
  6574. SPL_TYPE_DOUBLE               specifies that the field represents a 
  6575.                               double-precision floating point number 
  6576. SPL_TYPE_RESERVED             specifies that the bytes in the destination 
  6577.                               buffer are to be skipped 
  6578.  
  6579. The following are attribute constants which can be or'd with the numeric type 
  6580. constants listed above. 
  6581.  
  6582. Constant                      Meaning 
  6583. SPL_ATTR_DECIMAL              specifies that the number represented in ASCII is 
  6584.                               in decimal 
  6585. SPL_ATTR_HEX                  specifies that the number represented in ASCII is 
  6586.                               in hexadecimal 
  6587.  
  6588. Return code values are the following: 
  6589.  
  6590. Constant                      Meaning 
  6591. SPL_NOTFOUND                  specifies that the field was empty 
  6592. SPL_FOUND                     specifies that the field was not empty 
  6593.  
  6594.  
  6595. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6596.  
  6597. Constant                      Meaning 
  6598. SPS_LEFT                      Specifies that the string is to be padded on the 
  6599.                               left side. 
  6600. SPS_RIGHT                     Specifies that the string is to be padded on the 
  6601.                               right side. 
  6602.  
  6603.  
  6604. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6605.  
  6606. Command line argument descriptor 
  6607.  
  6608. typedef struct _CSCMDDESC {
  6609.    USHORT usId;
  6610.    CHAR achSwitch[SPCL_MAX_SWITCH+1];
  6611.    USHORT usNumArgs;
  6612.    USHORT usFlags;
  6613.    PFNCMDARG pfnCallback;
  6614. } CSCMDDESC, FAR *PCSCMDDESC;
  6615.  
  6616. usId                          specifies the identifier for the command line 
  6617.                               argument 
  6618. achSwitch                     specifies the string representing the command 
  6619.                               line argument 
  6620. usNumArgs                     specifies the number of arguments the command 
  6621.                               line argument requires 
  6622. usFlags                       specifies a combination of SPCL_FLG_ constants 
  6623. pfnCallback                   points to a callback function (see below) 
  6624.  
  6625. SPCL_FLG_ constants 
  6626.  
  6627. SPCL_FLG_CASESENSITIVE        specifies that achSwitch is case-sensitive 
  6628. SPCL_FLG_SUBSTRING            specifies that achSwitch is a substring of the 
  6629.                               entire command line argument.  If you specify 
  6630.                               this, you must also specify SPCL_FLG_ARGCONCAT. 
  6631. SPCL_FLG_ARGCONCAT            specifies that the first argument is concatenated 
  6632.                               to the command line argument (e.g. "-FPa", where 
  6633.                               "a" is the first argument). 
  6634.  
  6635. PFNCMDARG function 
  6636.  
  6637. typedef BOOL (* EXPENTRY PFNCMDARG)(USHORT,PCHAR *,USHORT,PVOID);
  6638. //-------------------------------------------------------------------------
  6639. // VOID EXPENTRY pfnCmdArg(USHORT usId,
  6640. //                         PCHAR *apchArgs,
  6641. //                         USHORT usNumArgs,
  6642. //                         PVOID pvData);
  6643. //-------------------------------------------------------------------------
  6644.  
  6645. Input 
  6646.  
  6647. usId (USHORT)       specifies the identifier of the switch 
  6648. apchArgs (PCHAR *)  points to an array of arguments to the command line 
  6649.                     argument 
  6650. usNumArgs (USHORT)  specifies the number of arguments 
  6651. pvData (PVOID)      Pointer to application-defined data 
  6652.  
  6653. Returns 
  6654.  
  6655. TRUE if the processing was successful, or FALSE otherwise 
  6656.  
  6657.  
  6658. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6659.  
  6660. typedef struct _CSLINEDESC {
  6661.    USHORT usOffset;
  6662.    USHORT usLength;
  6663.    USHORT usType;
  6664. } CSLINEDESC, FAR *PCSLINEDESC;
  6665.  
  6666. usOffset                      specifies the 0-based offset of the field 
  6667. usLength                      specifies the length in bytes of the field 
  6668. usType                        specifies a combination of SPL_ constants 
  6669.  
  6670. Related information 
  6671.  
  6672. o SPL_ constants 
  6673.  
  6674.  
  6675. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6676.  
  6677. typedef VOID (* EXPENTRY PFNCMDERR)(USHORT,PVOID);
  6678. //-------------------------------------------------------------------------
  6679. // VOID EXPENTRY pfnCmdErr(USHORT usId,PVOID pvData);
  6680. //-------------------------------------------------------------------------
  6681.  
  6682. Input 
  6683.  
  6684. usId (USHORT)       Specifies the error code 
  6685.  
  6686.    SPCL_ERR_NOMEMORY   The function could not allocate a required amount of 
  6687.                        memory 
  6688.    SPCL_ERR_NOTENOUGHARGS A command-line switch did not contain enough 
  6689.                        arguments 
  6690.    SPCL_ERR_BADSWITCH  An invalid switch was specified 
  6691.    SPCL_ERR_SWITCHERROR The switch function indicated that an error occurred 
  6692. pvData (PVOID)      Pointer to application-defined data 
  6693.  
  6694.  
  6695. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6696.  
  6697. Constant                      Meaning 
  6698. VGS_UNREADABLE                specifies that the input should not be readable. 
  6699.                               Each character is displayed as an asterisk ('*'). 
  6700. VGS_REQUIRED                  specifies that an empty string may not be 
  6701.                               returned. 
  6702.  
  6703.  
  6704. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  6705.  
  6706. typedef struct _CWPOSITION {
  6707.    ULONG ulSzStruct;
  6708.    SWP swpPosition;
  6709.    USHORT ausExtra[6];
  6710. } CWPOSITION, FAR *PCWPOSITION;
  6711.  
  6712. ulSzStruct                    specifies the size of the structure in bytes 
  6713. swpPosition                   specifies the current size and position 
  6714. ausExtra                      specifies the minimized position and the restored 
  6715.                               size and position 
  6716.