home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / common.zip / COMMON.H < prev    next >
C/C++ Source or Header  |  1995-02-08  |  107KB  |  2,047 lines
  1. //-------------------------------------------------------------------------
  2. // Copyright (c) 1993 by Lawrence W. Salomon, Jr.  All rights reserved.
  3. //
  4. // This file may not be modified in any form without the expressed,
  5. // written consent of the author.  See also the licensing agreement
  6. // included with this package for more information.
  7. //-------------------------------------------------------------------------
  8. #ifndef COMMONLIB_INCLUDED
  9. #define COMMONLIB_INCLUDED
  10.  
  11. #ifndef OS2_INCLUDED
  12. #error You must include <os2.h> prior to including <common.h>
  13. #endif
  14.  
  15. //-------------------------------------------------------------------------
  16. // By defining the following symbols, the corresponding functions are
  17. // defined:
  18. //
  19. // INCL_CMNBUF  -       Buffer routines
  20. // INCL_CMNCOM  -       Communication routines
  21. // INCL_CMNDBG  -       Debugging routines
  22. // INCL_CMNFIL  -       File routines
  23. // INCL_CMNLST  -       Linked list routines
  24. // INCL_CMNMEM  -       Memory routines
  25. // INCL_CMNOBJ  -       Object routines
  26. // INCL_CMNSET  -       Set routines
  27. // INCL_CMNSIG  -       Signal routines
  28. // INCL_CMNSPR  -       Sprite routines
  29. // INCL_CMNSTR  -       String routines
  30. // INCL_CMNVIO  -       VIO routines
  31. // INCL_CMNWIN  -       PM routines
  32. //-------------------------------------------------------------------------
  33. #ifdef INCL_COMMONALL
  34. #define INCL_CMNBUF
  35. #define INCL_CMNCOM
  36. #define INCL_CMNDBG
  37. #define INCL_CMNFIL
  38. #define INCL_CMNLST
  39. #define INCL_CMNMEM
  40. #define INCL_CMNOBJ
  41. #define INCL_CMNSET
  42. #define INCL_CMNSIG
  43. #define INCL_CMNSPR
  44. #define INCL_CMNSTR
  45. #define INCL_CMNVIO
  46. #define INCL_CMNWIN
  47. #endif                           // #ifdef INCL_COMMONALL
  48.  
  49. #include <cmndefs.h>
  50.  
  51. #pragma pack(1)
  52.  
  53. #ifdef __cplusplus
  54. extern "C" {
  55. #endif                           // #ifdef __cplusplus
  56.  
  57. #define CmnQueryHandle                 CMNQUERYHANDLE
  58. #define CmnQueryHandleInfo             CMNQUERYHANDLEINFO
  59. #define CmnSetHandleInfo               CMNSETHANDLEINFO
  60.  
  61. USHORT EXPENTRY CmnQueryHandle(LHANDLE lhHandle);
  62. //-------------------------------------------------------------------------
  63. // This function returns the type of the specified handle
  64. //
  65. // Input:  lhHandle - specifies the handle to query
  66. // Returns:  QH_* constant
  67. //-------------------------------------------------------------------------
  68.  
  69. BOOL EXPENTRY CmnQueryHandleInfo(LHANDLE lhHandle,PVOID pvInfo);
  70. //-------------------------------------------------------------------------
  71. // This function returns information about the handle specified.
  72. //
  73. // Input:  lhHandle - specifies the handle to query
  74. // Output:  pvInfo - points to the buffer which received the result.  The
  75. //                   size of this buffer depends on the handle type.
  76. // Returns:  TRUE if successful, FALSE otherwise
  77. //-------------------------------------------------------------------------
  78.  
  79. BOOL EXPENTRY CmnSetHandleInfo(LHANDLE lhHandle,PVOID pvInfo);
  80. //-------------------------------------------------------------------------
  81. // This function sets certain attributes about the handle specified.
  82. //
  83. // Input:  lhHandle - specifies the handle to query
  84. //         pvInfo - points to the buffer which received the result.  The
  85. //                  size and type of this buffer depends on the handle type.
  86. // Returns:  TRUE if successful, FALSE otherwise
  87. //-------------------------------------------------------------------------
  88.  
  89. #define CmnQueryVersion                CMNQUERYVERSION
  90.  
  91. VOID EXPENTRY CmnQueryVersion(PUSHORT pusMajor,
  92.                               PUSHORT pusMinor,
  93.                               PUSHORT pusRev);
  94. //-------------------------------------------------------------------------
  95. // This function returns the major, minor, and revision numbers.
  96. //
  97. // Output:  pusMajor - points to the variable that received the major
  98. //                     version number
  99. //          pusMinor - points to the variable that received the minor
  100. //                     version number
  101. //          pusRev - points to the variable that received the revision
  102. //                   version number
  103. //-------------------------------------------------------------------------
  104.  
  105. #ifdef INCL_CMNBUF
  106. //-------------------------------------------------------------------------
  107. // Buffer routines
  108. //-------------------------------------------------------------------------
  109. #define CmnBufCompressBytes            CMNBUFCOMPRESSBYTES
  110. #define CmnBufDecompressBytes          CMNBUFDECOMPRESSBYTES
  111. #define CmnBufEncryptBytes             CMNBUFENCRYPTBYTES
  112. #define CmnBufDecryptBytes             CMNBUFDECRYPTBYTES
  113.  
  114. BOOL EXPENTRY CmnBufCompressBytes(PBYTE pbInBuf,
  115.                                   ULONG ulSzInBuf,
  116.                                   PBYTE pbOutBuf,
  117.                                   PULONG pulSzOutBuf);
  118. //-------------------------------------------------------------------------
  119. // This function uses a run-length encoding algorithm to attempt to
  120. // compress the contents of a specified buffer.
  121. //
  122. // Input:   pbInBuf - points to the buffer to compress
  123. //          ulSzInBuf - specifies the size of the buffer pointed to by
  124. //                      pbInBuf
  125. //          pbOutBuf - points to the buffer to hold the result.  If NULL,
  126. //                     no results are written.
  127. // Output:  pulSzOutBuf - points to the variable containing the size of
  128. //                        the compressed buffer.
  129. // Returns:  TRUE if successful, FALSE otherwise.
  130. //-------------------------------------------------------------------------
  131.  
  132. BOOL EXPENTRY CmnBufDecompressBytes(PBYTE pbInBuf,
  133.                                     ULONG ulSzInBuf,
  134.                                     PBYTE pbOutBuf,
  135.                                     PULONG pulSzOutBuf);
  136. //-------------------------------------------------------------------------
  137. // This function uses a run-length encoding algorithm to decompress
  138. // the contents of a specified buffer that was compressed using
  139. // CmnBufCompressBytes().
  140. //
  141. // Input:   pbInBuf - points to the buffer to decompress
  142. //          ulSzInBuf - specifies the size of the buffer pointed to by
  143. //                      pbInBuf
  144. //          pbOutBuf - points to the buffer to hold the result.  If NULL,
  145. //                     no results are written.
  146. // Output:  pulSzOutBuf - points to the variable containing the size of
  147. //                        the decompressed buffer.
  148. // Returns:  TRUE if successful, FALSE otherwise.
  149. //-------------------------------------------------------------------------
  150.  
  151. BOOL EXPENTRY CmnBufEncryptBytes(PBYTE pbInBuf,ULONG ulSzBuf,PBYTE pbOutBuf);
  152. //-------------------------------------------------------------------------
  153. // This function encrypts the contents of a buffer using a not-too-secure
  154. // algorithm based on the XOR operation.  The resulting buffer is always
  155. // of the same size as the input.
  156. //
  157. // Input:  pbInBuf - points to the buffer to be encrypted
  158. //         ulSzBuf - specifies the size of the buffer pointed to by pbInBuf
  159. //         pbOutBuf - points to the buffer to hold the encrypted result
  160. // Returns:  TRUE if successful, FALSE otherwise.
  161. //-------------------------------------------------------------------------
  162.  
  163. BOOL EXPENTRY CmnBufDecryptBytes(PBYTE pbInBuf,ULONG ulSzBuf,PBYTE pbOutBuf);
  164. //-------------------------------------------------------------------------
  165. // This function decrypts the contents of a buffer encrypted using
  166. // CmnBufEncryptBytes().  The resulting buffer is always of the same size
  167. // as the input.
  168. //
  169. // Input:  pbInBuf - points to the buffer to be decrypted
  170. //         ulSzBuf - specifies the size of the buffer pointed to by pbInBuf
  171. //         pbOutBuf - points to the buffer to hold the decrypted result
  172. // Returns:  TRUE if successful, FALSE otherwise.
  173. //-------------------------------------------------------------------------
  174. #endif                           // #ifdef INCL_CMNBUF
  175.  
  176. #ifdef INCL_CMNCOM
  177. //-------------------------------------------------------------------------
  178. // Communication routines
  179. //-------------------------------------------------------------------------
  180. #define CmnComOpenConnection           CMNCOMOPENCONNECTION
  181. #define CmnComCloseConnection          CMNCOMCLOSECONNECTION
  182. #define CmnComWaitConnection           CMNCOMWAITCONNECTION
  183. #define CmnComSendControl              CMNCOMSENDCONTROL
  184. #define CmnComReadData                 CMNCOMREADDATA
  185. #define CmnComWriteData                CMNCOMWRITEDATA
  186. #define CmnComQueryData                CMNCOMQUERYDATA
  187.  
  188. COMERROR EXPENTRY CmnComOpenConnection(PCCOPENINFO pcoiInfo,
  189.                                        PHCCCONNECT phccConnect);
  190. //-------------------------------------------------------------------------
  191. // This function opens a connection with the desired attributes and
  192. // returns the connection handle.
  193. //
  194. // Input:  pcoiInfo - points to the CCOPENINFO structure describing the
  195. //                    type of connection desired
  196. // Output:  phccConnect - points to the variable which receives the result
  197. // Returns:  COM_ERR_* constant
  198. //-------------------------------------------------------------------------
  199.  
  200. COMERROR EXPENTRY CmnComCloseConnection(PHCCCONNECT phccConnect);
  201. //-------------------------------------------------------------------------
  202. // This function closes the specified connection and destroys the connection
  203. // handle.
  204. //
  205. // Input:  phccConnect - points to the variable containing the handle to
  206. //                       destroy.  On exit, this variable contains NULL.
  207. // Returns:  COM_ERR_* constant
  208. //-------------------------------------------------------------------------
  209.  
  210. COMERROR EXPENTRY CmnComWaitConnection(HCCCONNECT hccServer,
  211.                                        PHCCCONNECT phccConnect);
  212. //-------------------------------------------------------------------------
  213. // For server connections, this function waits until a client connects to
  214. // the server connection, then creates a new connection for private
  215. // communication to the client.  This leaves the server connection free
  216. // to service other requests.  If a client connection is specified, this
  217. // function returns COM_ERR_NOTSERVER.
  218. //
  219. // Input:  hccServer - handle to the server connection
  220. // Output:  phccConnect - points to the variable which receives the new
  221. //                        connection once a client connects to the
  222. //                        connection specified by hccServer
  223. // Returns:  COM_ERR_* constant
  224. //-------------------------------------------------------------------------
  225.  
  226. COMERROR EXPENTRY CmnComSendControl(HCCCONNECT hccConnect,ULONG ulCtrlCode);
  227. //-------------------------------------------------------------------------
  228. // This function sends a control packet to the other end of the connection.
  229. // The semantics of the various control codes are as follows:
  230. //
  231. //    CSC_CTRL_CLOSE - indicates that the connection should be closed.
  232. //    CSC_CTRL_RESET - indicates that the connection should be reset.
  233. //                     "Reset" is an abstract term that should be defined
  234. //                     by the application.
  235. //
  236. // Specifying any other value for ulCtrlCode returns COM_ERR_BADCONTROL.
  237. //
  238. // Input:  hccConnect - handle to the connection
  239. //         ulCtrlCode - specifies a CSC_CTRL_* constant
  240. // Returns:  COM_ERR_* constant
  241. //-------------------------------------------------------------------------
  242.  
  243. COMERROR EXPENTRY CmnComReadData(HCCCONNECT hccConnect,
  244.                                  PVOID pvBuf,
  245.                                  PULONG pulSzBuf);
  246. //-------------------------------------------------------------------------
  247. // This function reads data from the connection.
  248. //
  249. // Input:  hccConnect - handle to the connection
  250. //         pulSzBuf - points to the variable containing the size of the
  251. //                    buffer pointed to by pvBuf.  On exit, this variable
  252. //                    contains the number of bytes read.
  253. // Output:  pvBuf - points to the buffer to receive the data
  254. // Returns:  COM_ERR_* constant
  255. //-------------------------------------------------------------------------
  256.  
  257. COMERROR EXPENTRY CmnComWriteData(HCCCONNECT hccConnect,
  258.                                   PVOID pvBuf,
  259.                                   ULONG ulSzBuf);
  260. //-------------------------------------------------------------------------
  261. // This function writes data to a connection.
  262. //
  263. // Input:  hccConnect - handle to the connection
  264. //         pvBuf - points to the buffer containing the data
  265. //         ulSzBuf - specifies the size of the buffer pointed to by pvBuf
  266. // Returns:  COM_ERR_* constant
  267. //-------------------------------------------------------------------------
  268.  
  269. COMERROR EXPENTRY CmnComQueryData(HCCCONNECT hccConnect,PULONG pulData);
  270. //-------------------------------------------------------------------------
  271. // This function returns the size of the data waiting to be read by
  272. // the specified connection.  Since this does not return any data that
  273. // was written by the connection, the number returned does *not* necessarily
  274. // equal the number of bytes in the connection.
  275. //
  276. // Input:  hccConnect - handle to the connection
  277. // Output:  pulData - points to the variable that receives the result
  278. // Returns:  COM_ERR_* constant
  279. //-------------------------------------------------------------------------
  280. #endif                           // #ifdef INCL_CMNCOM
  281.  
  282. #ifdef INCL_CMNDBG
  283. //-------------------------------------------------------------------------
  284. // Debugging routines
  285. //-------------------------------------------------------------------------
  286. #define CmnDbgWriteRecord              CMNDBGWRITERECORD
  287. #define CmnDbgWriteText                CMNDBGWRITETEXT
  288. #define CmnDbgWriteBinary              CMNDBGWRITEBINARY
  289.  
  290. SHORT EXPENTRY CmnDbgWriteRecord(PVOID pvFile,
  291.                                  USHORT usFileType,
  292.                                  struct _CSLINEDESC *pcFormat,
  293.                                  USHORT usNumRecs,
  294.                                  PBYTE pbBuf);
  295. //-------------------------------------------------------------------------
  296. // This function writes the contents of the specified buffer to the specified
  297. // file.  The format of the buffer is specified in acFormat.
  298. //
  299. // Input:  pvFile - point to the file name or FILE structure
  300. //         usFileType - DWT_TYPE_* constant describing the contents of pvFile
  301. //         pcFormat - points to an array of CSLINEDESC describing the line
  302. //         usNumRecs - specifies the number of CSLINEDESC records are
  303. //                     pointed to by acFormat
  304. //         pbBuf - points to the buffer to print
  305. // Returns:  the number of fields printed is successful, DWT_ERROR otherwise
  306. //-------------------------------------------------------------------------
  307.  
  308. SHORT EXPENTRY CmnDbgWriteText(PVOID pvFile,USHORT usFileType,PCHAR pchFmt,...);
  309. //-------------------------------------------------------------------------
  310. // This function writes debug info to the file described by pvFile.  pvFile
  311. // can be a pointer to a file name or a (FILE *).  In the former case, the
  312. // file is opened upon entry and closed upon exit.
  313. //
  314. // Input:  pvFile - points to the file name or FILE structure
  315. //         usFileType - DWT_TYPE_* constant describing the contents of pvFile
  316. //         pchFmt - point to the format string (as in printf)
  317. // Returns:  number of characters written if successful, DWT_ERROR otherwise
  318. //-------------------------------------------------------------------------
  319.  
  320. SHORT EXPENTRY CmnDbgWriteBinary(PVOID pvFile,
  321.                                  USHORT usFileType,
  322.                                  PVOID pvBuf,
  323.                                  USHORT usSzBuf);
  324. //-------------------------------------------------------------------------
  325. // This function writes the binary data in hexadecimal/ASCII format (a la
  326. // Norton's disk editor) to the specified file.
  327. //
  328. // Input:  pvFile - points to the file name or FILE structure
  329. //         usFileType - DWT_TYPE_* constant describing the contents of pvFile
  330. //         pvBuf - points to the data to be written
  331. //         usSzBuf - specifies the size of the buffer pointed to by pvBuf
  332. // Returns:  number of characters written if successful, DWT_ERROR otherwise
  333. //-------------------------------------------------------------------------
  334. #endif                           // #ifdef INCL_CMNDBG
  335.  
  336. #ifdef INCL_CMNFIL
  337. //-------------------------------------------------------------------------
  338. // File routines
  339. //-------------------------------------------------------------------------
  340. #define CmnFilCreateSearch             CMNFILCREATESEARCH
  341. #define CmnFilSearchFiles              CMNFILSEARCHFILES
  342. #define CmnFilDestroySearch            CMNFILDESTROYSEARCH
  343. #define CmnFilQueryExtAttribute        CMNFILQUERYEXTATTRIBUTE
  344. #define CmnFilSetExtAttribute          CMNFILSETEXTATTRIBUTE
  345. #define CmnFilSplitFilename            CMNFILSPLITFILENAME
  346. #define CmnFilFormatDiskette           CMNFILFORMATDISKETTE
  347. #define CmnFilCopyDiskette             CMNFILCOPYDISKETTE
  348. #define CmnFilQueryLabel               CMNFILQUERYLABEL
  349. #define CmnFilInstallDiskette          CMNFILINSTALLDISKETTE
  350.  
  351. BOOL EXPENTRY CmnFilCreateSearch(PCHAR pchMask,
  352.                                  ULONG ulAttr,
  353.                                  PHCFSEARCH phcSearch);
  354. //-------------------------------------------------------------------------
  355. // This function creates a search handle
  356. //
  357. // Input:  pchMask - points to the file mask to search with
  358. //         ulAttr - points to the file attributes to retrieve
  359. // Output:  phcSearch - points to the search handle
  360. // Returns:  TRUE if successful, FALSE otherwise
  361. //-------------------------------------------------------------------------
  362.  
  363. LONG EXPENTRY CmnFilSearchFiles(HCFSEARCH hcSearch,
  364.                                 PCHAR pchBuf,
  365.                                 ULONG ulSzBuf);
  366. //-------------------------------------------------------------------------
  367. // This function searches for the files matching the mask specified in the
  368. // CmnFilCreateSearch call.
  369. //
  370. // Input:  hcSearch - search handle
  371. //         ulSzBuf - contains the size of the buffer pointed to by pchBuf
  372. // Output:  pchBuf - points to the next file that matches the mask
  373. // Returns:  attribute of the file found, FSF_NOFILES if none found, or
  374. //           FSF_ERROR if an error occurred.
  375. //-------------------------------------------------------------------------
  376.  
  377. BOOL EXPENTRY CmnFilDestroySearch(PHCFSEARCH phcSearch);
  378. //-------------------------------------------------------------------------
  379. // This function destroys the specified search handle
  380. //
  381. // Input:  phcSearch - points to the search handle to destroy.
  382. // Output:  phcSearch - points to the value NULL.
  383. // Returns:  TRUE if successful, FALSE otherwise.
  384. //-------------------------------------------------------------------------
  385.  
  386. BOOL EXPENTRY CmnFilQueryExtAttribute(PCHAR pchFile,
  387.                                       PCHAR pchVendor,
  388.                                       PCHAR pchAppl,
  389.                                       PCHAR pchName,
  390.                                       PUSHORT pusAttr,
  391.                                       PBYTE pbValue,
  392.                                       PUSHORT pusSzValue);
  393. //-------------------------------------------------------------------------
  394. // This function queries the value of the specified extended attribute
  395. // from the specified file.  This function cannot be used to query
  396. // EAs of type EAT_MVMT, EAT_MVST, or EAT_ASN1.
  397. //
  398. // Input:  pchFile - points to the name of the file to query
  399. //         pchVendor - points to the name of the company, or is one of
  400. //                     the FEA_* constants.  If an FEA_* constant is
  401. //                     specified, pchAppl and pchName are ignored.
  402. //         pchAppl - points to the name of the application
  403. //         pchName - points to the name of the extended attribute
  404. //         pusAttr - points to the variable which receives the EAT_*
  405. //                   constant for the data
  406. //         pbValue - points to the buffer which receives the data
  407. //         pusSzValue - points to the variable containing the size of the
  408. //                      buffer pointed to by pbValue
  409. // Output:  pusAttr - points to the variable containing the EAT_* type
  410. //          pbValue - points to the extended attribute data
  411. //          pusSzValue - points to the variable containing the size of the
  412. //                       data returned
  413. // Returns:  TRUE if successful, FALSE otherwise
  414. //-------------------------------------------------------------------------
  415.  
  416. BOOL EXPENTRY CmnFilSetExtAttribute(PCHAR pchFile,
  417.                                     USHORT usAttr,
  418.                                     PCHAR pchVendor,
  419.                                     PCHAR pchAppl,
  420.                                     PCHAR pchName,
  421.                                     PBYTE pbValue,
  422.                                     USHORT usSzValue);
  423. //-------------------------------------------------------------------------
  424. // This function adds or changes the specified extended attribute for the
  425. // specified file.  This function cannot be used to set EAs of type
  426. // EAT_MVMT, EAT_MVST, or EAT_ASN1.
  427. //
  428. // Input:  pchFile - points to the name of the file to query
  429. //         usAttr - specifies the EAT_* constant for the data
  430. //         pchVendor - points to the name of the company, or is one of
  431. //                     the FEA_* constants.  If an FEA_* constant is
  432. //                     specified, pchAppl and pchName are ignored.
  433. //         pchAppl - points to the name of the application
  434. //         pchName - points to the name of the extended attribute
  435. //         pbValue - points to the buffer which contains the data
  436. //         usSzValue - specifies the size of the buffer pointed to by
  437. //                     pbValue
  438. // Returns:  TRUE if successful, FALSE otherwise
  439. //-------------------------------------------------------------------------
  440.  
  441. BOOL EXPENTRY CmnFilSplitFilename(PCHAR pchFile,
  442.                                   PCHAR pchDrive,
  443.                                   PCHAR pchPath,
  444.                                   PCHAR pchName);
  445. //-------------------------------------------------------------------------
  446. // This function splits a filename into the drive, path, and name components.
  447. //
  448. // Input:  pchFile - points to the filename to split
  449. // Output:  pchDrive - if not NULL, points to the buffer which receives
  450. //                     the drive portion of the filename
  451. //          pchPath - if not NULL, points to the buffer which receives
  452. //                    the path portion of the filename
  453. //          pchName - if not NULL, points to the buffer which receives
  454. //                    the name portion of the filename
  455. // Returns:  TRUE if successful, FALSE otherwise
  456. //-------------------------------------------------------------------------
  457.  
  458. BOOL EXPENTRY CmnFilFormatDiskette(CHAR chDrive,
  459.                                    PCFFORMATINFO pfiInfo,
  460.                                    PFNDISKIO pfnCallback,
  461.                                    PVOID pvUser);
  462. //-------------------------------------------------------------------------
  463. // This function formats a diskette according to the specified parameters.
  464. //
  465. // For the notification FCD_MSG_WANTFORMATDISK and the type
  466. // FCD_TYPE_PROGESS, pfnCallback should return TRUE for the operation to
  467. // continue or FALSE to halt the operation.
  468. //
  469. // Input:  chDrive - specifies the drive to be formatted.
  470. //         pfiInfo - points to the format parameters.  If NULL, the
  471. //                   drive defaults are used.
  472. //         pfnCallback - pointer to a callback function
  473. //         pvUser - user-data passed to pfnCallback
  474. // Returns:  TRUE if successful, FALSE otherwise.
  475. //-------------------------------------------------------------------------
  476.  
  477. BOOL EXPENTRY CmnFilCopyDiskette(CHAR chSrc,
  478.                                  CHAR chDest,
  479.                                  ULONG ulOptions,
  480.                                  PFNDISKIO pfnCallback,
  481.                                  PVOID pvUser);
  482. //-------------------------------------------------------------------------
  483. // This function copies the contents of one diskette to another.  If the
  484. // destination diskette is already formatted, its capacity must match that
  485. // of the source diskette or this function will fail.
  486. //
  487. // For the notification type FCD_TYPE_PROGRESS and for the following
  488. // FCD_MSG_* notifications, pfnCallback should return TRUE for the operation
  489. // to continue/retry or FALSE to halt/abort the operation.
  490. //
  491. // Input:  chSrc - specifies the source drive
  492. //         chDest - specifies the destination drive
  493. //         ulOptions - specifies one or mor FCD_OPT_* constants
  494. //         pfnCallback - pointer to a callback function
  495. //         pvUser - user-data passed to pfnCallback
  496. // Returns:  TRUE if successful, FALSE otherwise.
  497. //-------------------------------------------------------------------------
  498.  
  499. BOOL EXPENTRY CmnFilQueryLabel(CHAR chDrive,PCHAR pchLabel);
  500. //-------------------------------------------------------------------------
  501. // This function returns the label of the diskette in the drive specified.
  502. //
  503. // Input:  chDrive - specifies the drive to check
  504. //         pchLabel - points to the buffer to copy the label into
  505. // Output:  pchLabel - points to the diskette label
  506. // Returns:  TRUE if successful, FALSE otherwise
  507. //-------------------------------------------------------------------------
  508.  
  509. ULONG EXPENTRY CmnFilInstallDiskette(PCHAR pchFile,
  510.                                      PCHAR pchVendor,
  511.                                      PCHAR pchApp,
  512.                                      PCHAR pchName,
  513.                                      PULONG pulNumLicenses,
  514.                                      ULONG ulRequest);
  515. //-------------------------------------------------------------------------
  516. // This function performs one of the available actions on a diskette
  517. // which is intended to be an install diskette for an application.  The
  518. // action to be performed is specified in ulRequest:
  519. //
  520. //    CFID_REQ_CREATE - initialize the install diskette with a specified
  521. //                      number of licenses
  522. //    CFID_REQ_DECREMENT - decrement the number of licenses
  523. //    CFID_REQ_INCREMENT - increment the number of licenses
  524. //    CFID_REQ_QUERY - query the number of licenses
  525. //
  526. // On all actions but create, the diskette is checked to insure that
  527. // it is the original diskette initialized with the create action and
  528. // an error code is returned if not.
  529. //
  530. // Input:  pchFile - points to the name of a file to contain the
  531. //                   installation information.
  532. //         pchVendor - points to the name of the company producing the
  533. //                     product.
  534. //         pchApp - points to the name of the application.
  535. //         pchName - points to an arbitrary name.
  536. //         pulNumLicenses - if ulRequest=CFID_REQ_CREATE, this points
  537. //                          to a variable specifying the initial number
  538. //                          of licenses for this installation diskette.
  539. //                          Otherwise, it points to a variable to receive
  540. //                          the updated number of available licenses or
  541. //                          is NULL meaning that the information isn't
  542. //                          needed.
  543. //         ulRequest - one of the CFID_REQ_* constants
  544. // Output:  pulNumLicenses - if non NULL, this contains the updated number
  545. //                           of licenses after the request was performed.
  546. // Returns:  CFID_ERR_NOERROR if successful, a CFID_ERR_* constant otherwise.
  547. //-------------------------------------------------------------------------
  548. #endif                           // #ifdef INCL_CMNFIL
  549.  
  550. #ifdef INCL_CMNLST
  551. //-------------------------------------------------------------------------
  552. // Link-list routines
  553. //-------------------------------------------------------------------------
  554. #define CmnLstAddRecord                CMNLSTADDRECORD
  555. #define CmnLstAddUniqueRecord          CMNLSTADDUNIQUERECORD
  556. #define CmnLstMoveRecord               CMNLSTMOVERECORD
  557. #define CmnLstCopyList                 CMNLSTCOPYLIST
  558. #define CmnLstCreateList               CMNLSTCREATELIST
  559. #define CmnLstDeleteList               CMNLSTDELETELIST
  560. #define CmnLstDeleteRecord             CMNLSTDELETERECORD
  561. #define CmnLstDestroyList              CMNLSTDESTROYLIST
  562. #define CmnLstPruneList                CMNLSTPRUNELIST
  563. #define CmnLstQueryRecord              CMNLSTQUERYRECORD
  564. #define CmnLstQueryRecordCount         CMNLSTQUERYRECORDCOUNT
  565. #define CmnLstQueryRelative            CMNLSTQUERYRELATIVE
  566. #define CmnLstQuickSortList            CMNLSTQUICKSORTLIST
  567. #define CmnLstSearchRecord             CMNLSTSEARCHRECORD
  568. #define CmnLstSortList                 CMNLSTSORTLIST
  569. #define CmnLstTraverseList             CMNLSTTRAVERSELIST
  570.  
  571. BOOL EXPENTRY CmnLstAddRecord(HCLLIST hclList,
  572.                               PVOID pvRecord,
  573.                               PFNRECCOMP pfnSort,
  574.                               PVOID *ppvResult,
  575.                               PVOID pvData);
  576. //-------------------------------------------------------------------------
  577. // This function adds a "record" into the linked list in sorted order as
  578. // defined by the user-defined pfnSort function.
  579. //
  580. // Input:  hclList - handle to the list to add the record to
  581. //         pvRecord - points to the record to add
  582. //         pfnSort - points to the comparison function.  If NULL, the function
  583. //                   inserts at the end of the list.  See above for a
  584. //                   description of its parameters.
  585. //         pvData - passed to pfnSort as the third parameter.
  586. // Output:  ppvResult - if not NULL on entry, points to the variable pointing
  587. //                      to the new entry
  588. // Returns:  TRUE if successful, FALSE otherwise
  589. //-------------------------------------------------------------------------
  590.  
  591. USHORT EXPENTRY CmnLstAddUniqueRecord(HCLLIST hclList,
  592.                                       PVOID pvRecord,
  593.                                       PFNRECCOMP pfnSearch,
  594.                                       PFNRECCOMP pfnSort,
  595.                                       PVOID *ppvResult,
  596.                                       PVOID pvData);
  597. //-------------------------------------------------------------------------
  598. // This function adds a "record" into the linked list only if the record
  599. // does not already exist.  The record is added in sorted order using the
  600. // pfnSort function.
  601. //
  602. // Input:  hclList - handle to the list to add the record to
  603. //         pvRecord - points to the record to add
  604. //         pfnSearch - points to the search function.  See above for a
  605. //                     description of its parameters.
  606. //         pfnSort - points to the comparison function.  If NULL, the function
  607. //                   inserts at the end of the list.  See above for a
  608. //                   description of its parameters.
  609. //         pvData - passed to pfnSearch and pfnSort as the third parameter.
  610. // Output:  ppvResult - if not NULL on entry, points to the variable pointing
  611. //                      to the old entry if one already existed or the newly
  612. //                      created entry.
  613. // Returns:  LAUR_NOERROR if successful, LAUR_EXISTS if the record already
  614. //           exists, or LAUR_ERROR otherwise
  615. //-------------------------------------------------------------------------
  616.  
  617. BOOL EXPENTRY CmnLstMoveRecord(HCLLIST hclList,
  618.                                PVOID pvMove,
  619.                                PVOID pvWhere,
  620.                                SHORT sRelative);
  621. //-------------------------------------------------------------------------
  622. // This function moves a record to a position relative to another record in
  623. // the specified list.
  624. //
  625. // Input:  hclList - handle to the list
  626. //         pvMove - pointer to the record to move
  627. //         pvWhere - pointer to the record specifying the new location
  628. //         sRelative - either LQR_PREVIOUS or LQR_NEXT specifying
  629. //                     immediately before or after pvWhere, respectively.
  630. // Returns:  TRUE if successful, FALSE otherwise
  631. //-------------------------------------------------------------------------
  632.  
  633. BOOL EXPENTRY CmnLstCopyList(HCLLIST hclList,
  634.                              HCLLIST hclCopy,
  635.                              PFNRECCOMP pfnSort,
  636.                              PVOID pvData);
  637. //-------------------------------------------------------------------------
  638. // This function copies one list into another list in sorted order.  Note
  639. // that if a call to CmnLstAddRecord fails, the state of the list being
  640. // modified is undefined.
  641. //
  642. // Input:  hclList - handle to the list to copy into
  643. //         hclCopy - handle to the list to copy from
  644. //         pfnSort - points to the comparison function.  If NULL, the function
  645. //                   will append hclCopy to hclList.  See above for a
  646. //                   description of its parameters.
  647. //         pvData - passed to pfnSort as the third parameter.
  648. // Returns:  TRUE if successful, FALSE otherwise
  649. //-------------------------------------------------------------------------
  650.  
  651. BOOL EXPENTRY CmnLstCreateList(USHORT usSzRecord,PHCLLIST phclList);
  652. //-------------------------------------------------------------------------
  653. // This function creates a linked list of records, and initializes it to
  654. // "empty".
  655. //
  656. // Input:  usSzRecord - the size of each record of the linked list
  657. // Output:  phclList - points to the handle to the new list
  658. // Returns:  TRUE if successful, FALSE otherwise
  659. //-------------------------------------------------------------------------
  660.  
  661. BOOL EXPENTRY CmnLstDeleteList(HCLLIST hclList);
  662. //-------------------------------------------------------------------------
  663. // This function deletes the entire list but does not destroy it
  664. //
  665. // Input:  hclList - handle to the list to delete
  666. // Output:  ppvHead - points to the head of the list==NULL
  667. // Returns:  TRUE if successful, FALSE otherwise
  668. //-------------------------------------------------------------------------
  669.  
  670. BOOL EXPENTRY CmnLstDeleteRecord(HCLLIST hclList,PVOID pvRecord);
  671. //-------------------------------------------------------------------------
  672. // This function deletes a record from the linked list.
  673. //
  674. // Input:  hclList - handle to the list to delete the record from
  675. //         pvRecord - points to the record to delete
  676. // Returns:  TRUE if successful, FALSE otherwise
  677. //-------------------------------------------------------------------------
  678.  
  679. BOOL EXPENTRY CmnLstDestroyList(PHCLLIST phclList);
  680. //-------------------------------------------------------------------------
  681. // This function deletes and then destroys the specified list.
  682. //
  683. // Input:  phclList - points to the handle to the list
  684. // Output:  pchList - points to a variable containing NULL
  685. // Returns:  TRUE if successful, FALSE otherwise
  686. //-------------------------------------------------------------------------
  687.  
  688. BOOL EXPENTRY CmnLstPruneList(HCLLIST hclList,
  689.                               PVOID pvRecord,
  690.                               PFNRECCOMP pfnSearch,
  691.                               PVOID pvData);
  692. //-------------------------------------------------------------------------
  693. // This function deletes records that match the search criteria from the
  694. // specified list.
  695. //
  696. // Input:  hclList - handle to the list to prune
  697. //         pvSearch - points to the application defined search data.  It is
  698. //                    passed to pfnSearch as the second parameter.
  699. //         pfnSearch - points to the comparison function.  See above for a
  700. //                     description of its parameters.
  701. //         pvData - passed to pfnSearch as the third parameter.
  702. // Returns:  TRUE if successful, FALSE otherwise
  703. //-------------------------------------------------------------------------
  704.  
  705. #define LQR_END                  -1
  706.  
  707. PVOID EXPENTRY CmnLstQueryRecord(HCLLIST hclList,SHORT sNumRecord);
  708. //-------------------------------------------------------------------------
  709. // This function returns the nth record in the specified linked list.
  710. //
  711. // Input:  hclList - handle to the list to query
  712. //         sNumRecord - specifies the 0-based number of the record to
  713. //                      retrieve or a LQR_* constant
  714. // Returns:  pointer to the record if successful, NULL otherwise
  715. //-------------------------------------------------------------------------
  716.  
  717. SHORT EXPENTRY CmnLstQueryRecordCount(HCLLIST hclList);
  718. //-------------------------------------------------------------------------
  719. // This function returns the number of records in the linked list.
  720. //
  721. // Input:  hclList - handle to the list to query
  722. // Returns:  the number of records if successful, LQRC_ERROR otherwise
  723. //-------------------------------------------------------------------------
  724.  
  725. PVOID EXPENTRY CmnLstQueryRelative(PVOID pvRecord,SHORT sWhich);
  726. //-------------------------------------------------------------------------
  727. // This function returns either the previous or next record relative to the
  728. // specified record.
  729. //
  730. // Input:  pvRecord - points to the record to query
  731. //         sNumRecord - specifies either LQR_PREVIOUS or LQR_NEXT
  732. // Returns:  pointer to the record if successfull, or NULL if pvRecord is the
  733. //           head of the list and LQR_PREVIOUS was specified, pvRecord is the
  734. //           tail of the list and LQR_NEXT was specified or an error occurred.
  735. //-------------------------------------------------------------------------
  736.  
  737. BOOL EXPENTRY CmnLstQuickSortList(HCLLIST hclList,
  738.                                   PFNRECMED pfnMedian,
  739.                                   PFNRECCOMP pfnCompare,
  740.                                   PVOID pvData);
  741. //-------------------------------------------------------------------------
  742. // This function sorts the specified list using a version of the quick sort
  743. // algorithm that has been slightly modified to conserve memory.
  744. //
  745. // Input:  hclList - handle to the list to sort
  746. //         pfnMedian - points to a median function.  See above for a
  747. //                     description of its parameters.
  748. //         pfnCompare - points to a comparison function.  See above for a
  749. //                      description of its parameters.
  750. //         pvData - passed to pfnMedian and pfnCompare as the third parameter.
  751. // Output:  hclList - handle to the sorted list
  752. // Returns:  TRUE if successful, FALSE otherwise.
  753. //-------------------------------------------------------------------------
  754.  
  755. PVOID EXPENTRY CmnLstSearchRecord(PVOID pvRecord,
  756.                                   PVOID pvSearch,
  757.                                   PFNRECCOMP pfnSearch,
  758.                                   PVOID pvData);
  759. //-------------------------------------------------------------------------
  760. // This function searches the linked list for a record using the pfnSearch
  761. // function.
  762. //
  763. // Input:  pvRecord - points to the first record of the linked list where
  764. //                    searching is to begin
  765. //         pvSearch - points to the application defined search data.  It is
  766. //                    passed to pfnSearch as the second parameter.
  767. //         pfnSearch - points to the comparison function.  See above for a
  768. //                     description of its parameters.
  769. //         pvData - passed to pfnSearch as the third parameter.
  770. // Returns:  pointer to record if found, NULL otherwise
  771. //-------------------------------------------------------------------------
  772.  
  773. BOOL EXPENTRY CmnLstSortList(HCLLIST hclList,PFNRECCOMP pfnSort,PVOID pvData);
  774. //-------------------------------------------------------------------------
  775. // This function performs a bubble sort on the specified list.
  776. //
  777. // Input:  hclList - handle to the list to sort
  778. //         pfnSort - points to the comparison function.  See above for a
  779. //                   description of its parameters.
  780. //         pvData - passed to pfnSort as the third parameter.
  781. // Returns:  TRUE if successful, FALSE otherwise.
  782. //-------------------------------------------------------------------------
  783.  
  784. BOOL EXPENTRY CmnLstTraverseList(HCLLIST hclList,
  785.                                  PFNRECFUNC pfnFunc,
  786.                                  PVOID pvData);
  787. //-------------------------------------------------------------------------
  788. // This function traverses the specified list, calling the specified function
  789. // for each record in the list.  This can be used, for example, to print
  790. // out each record in the list for debugging purposes.
  791. //
  792. // Input:  hclList - handle to the list to traverse
  793. //         pfnFunc - callback function.  See above for a description of its
  794. //                   parameters.
  795. //         pvData - passed to pfnFunc as the second parameter
  796. // Returns:  TRUE if successful, FALSE otherwise
  797. //-------------------------------------------------------------------------
  798. #endif                           // #ifdef INCL_CMNLST
  799.  
  800. #ifdef INCL_CMNMEM
  801. //-------------------------------------------------------------------------
  802. // Memory allocation routines
  803. //-------------------------------------------------------------------------
  804. #define CmnMemAllocate                 CMNMEMALLOCATE
  805. #define CmnMemFree                     CMNMEMFREE
  806. #define CmnMemInitialize               CMNMEMINITIALIZE
  807. #define CmnMemQueryMemSize             CMNMEMQUERYMEMSIZE
  808. #define CmnMemReset                    CMNMEMRESET
  809. #define CmnMemTerminate                CMNMEMTERMINATE
  810.  
  811. MEMERROR EXPENTRY CmnMemAllocate(HCMMEM hcmMem,ULONG ulSzBuf,PVOID *ppvBuf);
  812. //-------------------------------------------------------------------------
  813. // This function allocates a block of memory from a memory manager instance.
  814. //
  815. // Input:  hcmMem - handle to the memory manager instance.
  816. //         ulSzBuf - specifies the requested size of the memory block.
  817. // Output:  ppvBuf - points to the variable which receives the pointer
  818. //                   to the allocated memory.
  819. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise.
  820. //-------------------------------------------------------------------------
  821.  
  822. MEMERROR EXPENTRY CmnMemFree(HCMMEM hcmMem,PVOID pvBuf);
  823. //-------------------------------------------------------------------------
  824. // This function returns a block of memory to the memory manager.
  825. //
  826. // Input:  hcmMem - handle to the memory manager instance.
  827. //         pvBuf - points to the block of memory to free.
  828. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise
  829. //-------------------------------------------------------------------------
  830.  
  831. MEMERROR EXPENTRY CmnMemInitialize(PCMMEMINFO pcmiInfo,PHCMMEM phcmMem);
  832. //-------------------------------------------------------------------------
  833. // This function creates an instance of the memory manager.
  834. //
  835. // Input:  pcmiInfo - points to a CMMEMINFO structure which specifies the
  836. //                    desired attributes of the instance.  If NULL, the
  837. //                    defaults are used.
  838. // Output:  phcmMem - points to the variable containing the memory handle.
  839. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise.
  840. //-------------------------------------------------------------------------
  841.  
  842. ULONG EXPENTRY CmnMemQueryMemSize(PVOID pvBuf);
  843. //-------------------------------------------------------------------------
  844. // This function returns the size of a block of memory.  No validation is
  845. // done to determine whether or not the memory was allocated with
  846. // CmnMemAllocate.
  847. //
  848. // Input:  pvBuf - points to the block of memory to query.
  849. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise
  850. //-------------------------------------------------------------------------
  851.  
  852. MEMERROR EXPENTRY CmnMemReset(HCMMEM hcmMem);
  853. //-------------------------------------------------------------------------
  854. // This function deallocates *all* memory associated with a memory manager
  855. // instance and resets the heaps to "empty."
  856. //
  857. // Input:  hcmMem - handle to the memory manager instance.
  858. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise
  859. //-------------------------------------------------------------------------
  860.  
  861. MEMERROR EXPENTRY CmnMemTerminate(PHCMMEM phcmMem);
  862. //-------------------------------------------------------------------------
  863. // This function destroys an instance of the memory manager.
  864. //
  865. // Input:  phcmMem - points to the variable containing the memory handle
  866. //                   to destroy.
  867. // Output:  phcmMem - points to the value NULL.
  868. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise.
  869. //-------------------------------------------------------------------------
  870. #endif                           // #ifdef INCL_CMNMEM
  871.  
  872. #ifdef INCL_CMNOBJ
  873. //-------------------------------------------------------------------------
  874. // Object routines
  875. //-------------------------------------------------------------------------
  876. #define CmnObjInitialize               CMNOBJINITIALIZE
  877. #define CmnObjTerminate                CMNOBJTERMINATE
  878. #define CmnObjReset                    CMNOBJRESET
  879. #define CmnObjQueryObject              CMNOBJQUERYOBJECT
  880. #define CmnObjCreateObject             CMNOBJCREATEOBJECT
  881. #define CmnObjDestroyObject            CMNOBJDESTROYOBJECT
  882. #define CmnObjSetObjectData            CMNOBJSETOBJECTDATA
  883. #define CmnObjQueryObjectData          CMNOBJQUERYOBJECTDATA
  884. #define CmnObjObjectFromName           CMNOBJOBJECTFROMNAME
  885.  
  886. OBJERROR EXPENTRY CmnObjInitialize(PCOROOTINFO pcoriInfo,PHCOOBJECT phcoRoot);
  887. //-------------------------------------------------------------------------
  888. // This function initializes the object manager and returns the handle
  889. // to the root object.
  890. //
  891. // Input:  pcoriInfo - points to the COROOTINFO structure containing
  892. //                     the desired characteristics of the instance
  893. // Output:  phcoRoot - points to the variable that received the created
  894. //                     root object handle
  895. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  896. //-------------------------------------------------------------------------
  897.  
  898. OBJERROR EXPENTRY CmnObjTerminate(PHCOOBJECT phcoRoot);
  899. //-------------------------------------------------------------------------
  900. // This function destroys all children of the specified root object
  901. // (via a call to CmnObjReset()) and terminates the object manager
  902. // instance.
  903. //
  904. // Input:  phcoRoot - points to the variable specified the root object
  905. //                    handle.  On return, this variable contains NULL.
  906. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  907. //-------------------------------------------------------------------------
  908.  
  909. OBJERROR EXPENTRY CmnObjReset(HCOOBJECT hcoRoot);
  910. //-------------------------------------------------------------------------
  911. // This function deletes all child objects from the specified root object.
  912. //
  913. // Input:  hcoRoot - handle of the root object
  914. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  915. //-------------------------------------------------------------------------
  916.  
  917. OBJERROR EXPENTRY CmnObjQueryObject(HCOOBJECT hcoObject,
  918.                                     SHORT sQuery,
  919.                                     PHCOOBJECT phcoResult);
  920. //-------------------------------------------------------------------------
  921. // This function returns the handle of the object related to the specified
  922. // object in the specified way.
  923. //
  924. // Input:  hcoObject - handle to the object to query the relationship of
  925. //         sQuery - an OQO_* constant specifying the relationship
  926. // Output:  phcoResult - points to the variable which receives the result
  927. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  928. //-------------------------------------------------------------------------
  929.  
  930. OBJERROR EXPENTRY CmnObjCreateObject(HCOOBJECT hcoParent,
  931.                                      PCHAR pchName,
  932.                                      PHCOOBJECT phcoResult);
  933. //-------------------------------------------------------------------------
  934. // This function creates a new object whose parent is specified in
  935. // hcoParent.
  936. //
  937. // Input:  hcoParent - handle to the parent object
  938. //         pchName - points to the variable specifying the subname.  This
  939. //                   cannot contain a backslash
  940. // Output:  phcoResult - points to the variable which receives the handle
  941. //                       to the newly created object
  942. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  943. //-------------------------------------------------------------------------
  944.  
  945. OBJERROR EXPENTRY CmnObjDestroyObject(PHCOOBJECT phcoObject);
  946. //-------------------------------------------------------------------------
  947. // This function destroys the specified object.  It is an error to call
  948. // this function with the root object handle.
  949. //
  950. // Input:  phcoObject - points to the variable specifying the handle of
  951. //                      the object to destroy.  On return, this variable
  952. //                      contains NULL.
  953. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  954. //-------------------------------------------------------------------------
  955.  
  956. OBJERROR EXPENTRY CmnObjSetObjectData(HCOOBJECT hcoObject,
  957.                                       PVOID pvBuffer,
  958.                                       ULONG ulSzBuf);
  959. //-------------------------------------------------------------------------
  960. // This function sets the object-specific data.  Any data that was
  961. // previously set into the object is disposed of an the memory is returned
  962. // to the system.
  963. //
  964. // Intput:  hcoObject - handle to the object
  965. //          pvBuffer - points to the new object data
  966. //          ulSzBuf - specifies the size of the buffer pointed to by
  967. //                    pvBuffer
  968. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  969. //-------------------------------------------------------------------------
  970.  
  971. OBJERROR EXPENTRY CmnObjQueryObjectData(HCOOBJECT hcoObject,
  972.                                         PVOID pvBuffer,
  973.                                         PULONG pulSzBuf);
  974. //-------------------------------------------------------------------------
  975. // This function returns the object-specific data set by CmnObjSetData().
  976. //
  977. // Intput:  hcoObject - handle to the object
  978. // Output:  pvBuffer - points to the receiving buffer.  If NULL, pulSzBuf
  979. //                     contains the size required to completely hold the
  980. //                     data
  981. //          pulSzBuf - points to the variable that receives the number of
  982. //                     of bytes copied if pvBuffer!=NULL.  If pvBuffer==NULL,
  983. //                     the variable instead contains the size in bytes of
  984. //                     the data
  985. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  986. //-------------------------------------------------------------------------
  987.  
  988. OBJERROR EXPENTRY CmnObjObjectFromName(HCOOBJECT hcoObject,
  989.                                        PCHAR pchName,
  990.                                        PHCOOBJECT phcoResult);
  991. //-------------------------------------------------------------------------
  992. // This function returns the object with the given relative or absolute
  993. // name.  The name to search for consists of one or more subnames separated
  994. // by backslashes.  If the name begins with a backslash, searching begins
  995. // at the root object.  As with filenames, the subnames "." and ".." have
  996. // special meanings analagous to the file system interpretations.
  997. //
  998. // Input:  hcoObject - handle to the object
  999. //         pchName - points to the name
  1000. // Output:  phcoResult - points to the variable which receives the result
  1001. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  1002. //-------------------------------------------------------------------------
  1003. #endif                           // #ifdef INCL_CMNOBJ
  1004.  
  1005. #ifdef INCL_CMNSET
  1006. //-------------------------------------------------------------------------
  1007. // Set routines
  1008. //-------------------------------------------------------------------------
  1009. #define CmnSetCreateSet                CMNSETCREATESET
  1010. #define CmnSetDestroySet               CMNSETDESTROYSET
  1011. #define CmnSetSetElement               CMNSETSETELEMENT
  1012. #define CmnSetClearElement             CMNSETCLEARELEMENT
  1013. #define CmnSetInvertElement            CMNSETINVERTELEMENT
  1014. #define CmnSetFindElement              CMNSETFINDELEMENT
  1015. #define CmnSetSetSet                   CMNSETSETSET
  1016. #define CmnSetClearSet                 CMNSETCLEARSET
  1017. #define CmnSetInvertSet                CMNSETINVERTSET
  1018. #define CmnSetQueryElement             CMNSETQUERYELEMENT
  1019. #define CmnSetQueryEqualSets           CMNSETQUERYEQUALSETS
  1020. #define CmnSetCombineSets              CMNSETCOMBINESETS
  1021. #define CmnSetIntersectSets            CMNSETINTERSECTSETS
  1022.  
  1023. BOOL EXPENTRY CmnSetCreateSet(ULONG ulMaxElems,PHCSSET phcsSet);
  1024. //-------------------------------------------------------------------------
  1025. // This function creates a set with the specified number of elements.
  1026. //
  1027. // Input:  ulMaxElems - specifies the maximum number of elements.
  1028. // Output:  phcsSet - points to the variable containing the set handle
  1029. // Returns:  TRUE if successful, FALSE otherwise
  1030. //-------------------------------------------------------------------------
  1031.  
  1032. BOOL EXPENTRY CmnSetDestroySet(PHCSSET phcsSet);
  1033. //-------------------------------------------------------------------------
  1034. // This function destroys the set handle pointed to by phcsSet.
  1035. //
  1036. // Input:  phcsSet - points to the variable specifying the set handle to
  1037. //                  destroy
  1038. // Returns:  TRUE if successful, FALSE otherwise
  1039. //-------------------------------------------------------------------------
  1040.  
  1041. BOOL EXPENTRY CmnSetSetElement(HCSSET hcsSet,ULONG ulElement);
  1042. //-------------------------------------------------------------------------
  1043. // This function sets the specified element in the specified set.
  1044. //
  1045. // Input:  hcsSet - specifies the set handle
  1046. //         ulElement - specifies the element to set
  1047. // Returns:  TRUE if successful, FALSE otherwise
  1048. //-------------------------------------------------------------------------
  1049.  
  1050. BOOL EXPENTRY CmnSetClearElement(HCSSET hcsSet,ULONG ulElement);
  1051. //-------------------------------------------------------------------------
  1052. // This function clears the specified element in the specified set.
  1053. //
  1054. // Input:  hcsSet - specifies the set handle
  1055. //         ulElement - specifies the element to clear
  1056. // Returns:  TRUE if successful, FALSE otherwise
  1057. //-------------------------------------------------------------------------
  1058.  
  1059. BOOL EXPENTRY CmnSetInvertElement(HCSSET hcsSet,ULONG ulElement);
  1060. //-------------------------------------------------------------------------
  1061. // This function inverts the state of the specified element.
  1062. //
  1063. // Input:  hcsSet - specifies the set handle
  1064. //         ulElement - specifies the element to invert
  1065. // Returns:  TRUE if successful, FALSE otherwise
  1066. //-------------------------------------------------------------------------
  1067.  
  1068. LONG EXPENTRY CmnSetFindElement(HCSSET hcsSet,ULONG ulNumber,USHORT usType);
  1069. //-------------------------------------------------------------------------
  1070. // This function finds the nth element that is either set or clear.
  1071. //
  1072. // Input:  hcsSet - specifies the set handle
  1073. //         ulNumber - specifies the number of the element desired
  1074. //         usType - specifies either SFE_SET if the nth element set is
  1075. //                  desired or SFE_CLEAR if the nth element clear is
  1076. //                  desired
  1077. // Returns:  Element number if found, SFE_NOTFOUND if not found, or
  1078. //           SFE_ERROR if an error occurred
  1079. //-------------------------------------------------------------------------
  1080.  
  1081. BOOL EXPENTRY CmnSetSetSet(HCSSET hcsSet);
  1082. //-------------------------------------------------------------------------
  1083. // This function sets all of the elements of the specified set.
  1084. //
  1085. // Input:  hcsSet - specifies the set handle
  1086. // Returns:  TRUE if successful, FALSE otherwise
  1087. //-------------------------------------------------------------------------
  1088.  
  1089. BOOL EXPENTRY CmnSetClearSet(HCSSET hcsSet);
  1090. //-------------------------------------------------------------------------
  1091. // This function clears all of the elements of the specified set.
  1092. //
  1093. // Input:  hcsSet - specifies the set handle
  1094. // Returns:  TRUE if successful, FALSE otherwise
  1095. //-------------------------------------------------------------------------
  1096.  
  1097. BOOL EXPENTRY CmnSetInvertSet(HCSSET hcsSet);
  1098. //-------------------------------------------------------------------------
  1099. // This function inverts all of the elements of the specified set.
  1100. //
  1101. // Input:  hcsSet - specifies the set handle
  1102. // Returns:  TRUE if successful, FALSE otherwise
  1103. //-------------------------------------------------------------------------
  1104.  
  1105. SHORT EXPENTRY CmnSetQueryElement(HCSSET hcsSet,ULONG ulElement);
  1106. //-------------------------------------------------------------------------
  1107. // This function returns the state of the specified element.
  1108. //
  1109. // Input:  hcsSet - specifies the set handle
  1110. //         ulElement - specifies the element to query
  1111. // Returns:  SQE_SET if the element is set, SQE_CLEAR if the element is not
  1112. //           set, or SQE_ERROR if an error occurs
  1113. //-------------------------------------------------------------------------
  1114.  
  1115. SHORT EXPENTRY CmnSetQueryEqualSets(HCSSET hcsSet1,HCSSET hcsSet2);
  1116. //-------------------------------------------------------------------------
  1117. // This function compares two sets for equality.
  1118. //
  1119. // Input:  hcsSet1 - specifies the first set handle
  1120. //         hcsSet2 - specifies the second set handle
  1121. // Returns:  SQES_EQUAL if the sets are equal, SQES_NOTEQUAL if the sets
  1122. //           are not equal, or SQES_ERROR if an error occurs
  1123. //-------------------------------------------------------------------------
  1124.  
  1125. HCSSET EXPENTRY CmnSetCombineSets(HCSSET hcsSet1,HCSSET hcsSet2);
  1126. //-------------------------------------------------------------------------
  1127. // This function calculates the union of the specified sets and returns
  1128. // the result.
  1129. //
  1130. // Input:  hcsSet1 - specifies the first set handle
  1131. //         hcsSet2 - specifies the second set handle
  1132. // Returns:  a new set handle containing the union if successful, NULL
  1133. //           otherwise
  1134. //-------------------------------------------------------------------------
  1135.  
  1136. HCSSET EXPENTRY CmnSetIntersectSets(HCSSET hcsSet1,HCSSET hcsSet2);
  1137. //-------------------------------------------------------------------------
  1138. // This function calculates the intersection of the specified sets and returns
  1139. // the result.  If the sets are not equal in size, the function pads the
  1140. // smaller set with "set" elements.
  1141. //
  1142. // Input:  hcsSet1 - specifies the first set handle
  1143. //         hcsSet2 - specifies the second set handle
  1144. // Returns:  a new set handle containing the intersection if successful,
  1145. //           NULL otherwise
  1146. //-------------------------------------------------------------------------
  1147. #endif                           // #ifdef INCL_CMNSET
  1148.  
  1149. #ifdef INCL_CMNSIG
  1150. //-------------------------------------------------------------------------
  1151. // Signal routines
  1152. //-------------------------------------------------------------------------
  1153. #define CmnSigCreateSignalList         CMNSIGCREATESIGNALLIST
  1154. #define CmnSigDestroySignalList        CMNSIGDESTROYSIGNALLIST
  1155. #define CmnSigCreateSignal             CMNSIGCREATESIGNAL
  1156. #define CmnSigDestroySignal            CMNSIGDESTROYSIGNAL
  1157. #define CmnSigQuerySignal              CMNSIGQUERYSIGNAL
  1158. #define CmnSigSetSignalValue           CMNSIGSETSIGNALVALUE
  1159. #define CmnSigSetSignalBit             CMNSIGSETSIGNALBIT
  1160. #define CmnSigClearSignalBit           CMNSIGCLEARSIGNALBIT
  1161. #define CmnSigSetAllSignalValues       CMNSIGSETALLSIGNALVALUES
  1162. #define CmnSigSetAllSignalBits         CMNSIGSETALLSIGNALBITS
  1163. #define CmnSigClearAllSignalBits       CMNSIGCLEARALLSIGNALBITS
  1164. #define CmnSigQuerySignalId            CMNSIGQUERYSIGNALID
  1165. #define CmnSigQuerySignalValue         CMNSIGQUERYSIGNALVALUE
  1166. #define CmnSigWaitSignalValue          CMNSIGWAITSIGNALVALUE
  1167. #define CmnSigWaitSignalBit            CMNSIGWAITSIGNALBIT
  1168. #define CmnSigWaitAllSignalValues      CMNSIGWAITALLSIGNALVALUES
  1169. #define CmnSigWaitAllSignalBits        CMNSIGWAITALLSIGNALBITS
  1170.  
  1171. BOOL EXPENTRY CmnSigCreateSignalList(PHCSSIGNALLIST phcsList);
  1172. //-------------------------------------------------------------------------
  1173. // This function creates a signal list which is used in subsequent calls to
  1174. // the CmnSig functions.  Typically, only one per application is needed,
  1175. // although this might not always be true.
  1176. //
  1177. // Output:  phcsList - points to the variable specifying the list handle
  1178. // Returns:  TRUE if successful, FALSE otherwise
  1179. //-------------------------------------------------------------------------
  1180.  
  1181. BOOL EXPENTRY CmnSigDestroySignalList(PHCSSIGNALLIST phcsList);
  1182. //-------------------------------------------------------------------------
  1183. // This function destroys the specified signal list.
  1184. //
  1185. // Input:  phcsList - points to the variable specifying the list handle
  1186. // Output:  phcsList - points to the variable specifying NULL
  1187. // Returns:  TRUE if successful, FALSE otherwise
  1188. //-------------------------------------------------------------------------
  1189.  
  1190. BOOL EXPENTRY CmnSigCreateSignal(HCSSIGNALLIST hcsList,
  1191.                                  ULONG ulId,
  1192.                                  PHCSSIGNAL phcSignal);
  1193. //-------------------------------------------------------------------------
  1194. // This function creates a signal handle in the specified signal list.
  1195. // The returned signal handle is used in subsequent calls to the signal
  1196. // functions.  Note that ulId can be any id unique to the list.
  1197. //
  1198. // Input:  hcsList - specifies the list handle to add the signal to
  1199. //         ulId - specifies the id of the handle to be created
  1200. // Output:  phcSignal - points to the variable containing the created
  1201. //                      signal handle
  1202. // Returns:  TRUE if successful, FALSE otherwise
  1203. //-------------------------------------------------------------------------
  1204.  
  1205. BOOL EXPENTRY CmnSigDestroySignal(PHCSSIGNAL phcSignal);
  1206. //-------------------------------------------------------------------------
  1207. // This function destroys the specified signal from the owner list.
  1208. //
  1209. // Input:  phcSignal - points to the variable specifying the signal handle
  1210. //                     to delete
  1211. // Output:  phcSignal - points to the variable specifying NULL
  1212. // Returns:  TRUE if successful, FALSE otherwise
  1213. //-------------------------------------------------------------------------
  1214.  
  1215. BOOL EXPENTRY CmnSigQuerySignal(HCSSIGNALLIST hcsList,
  1216.                                 ULONG ulId,
  1217.                                 PHCSSIGNAL phcSignal);
  1218. //-------------------------------------------------------------------------
  1219. // This function searches the specified list for the signal handle with the
  1220. // specified id.
  1221. //
  1222. // Input:  hcsList - specifies the list to search
  1223. //         ulId - specifies the signal id to search for
  1224. // Output:  phcSignal - points to the variable specifying the signal handle
  1225. //                      if found, NULL otherwise
  1226. // Returns:  TRUE if successful, FALSE otherwise
  1227. //-------------------------------------------------------------------------
  1228.  
  1229. BOOL EXPENTRY CmnSigSetSignalValue(HCSSIGNAL hcSignal,ULONG ulSignal);
  1230. //-------------------------------------------------------------------------
  1231. // This function sets the signal value for the specified signal handle to
  1232. // the specified value.  This is useful for unique signal values.  Note
  1233. // that since 0 could possibly be a valid signal value, you must call
  1234. // CmnSigSetSignalValue() with the "empty" value (this is application-specific)
  1235. // to clear this value.
  1236. //
  1237. // For signal values whose individual bits have specific interpretations,
  1238. // use CmnSigSetSignalBit().
  1239. //
  1240. // Input:  hcSignal - specifies the signal handle to set
  1241. //         ulSignal - specifies the new signal value
  1242. // Returns:  TRUE if successful, FALSE otherwise
  1243. //-------------------------------------------------------------------------
  1244.  
  1245. BOOL EXPENTRY CmnSigSetSignalBit(HCSSIGNAL hcSignal,ULONG ulSignal);
  1246. //-------------------------------------------------------------------------
  1247. // This function sets the specified signal value bits for the specified
  1248. // signal handle.
  1249. //
  1250. // Input:  hcSignal - specifies the signal handle to set
  1251. //         ulSignal - specifies the signal bits to set
  1252. // Returns:  TRUE if successful, FALSE otherwise
  1253. //-------------------------------------------------------------------------
  1254.  
  1255. BOOL EXPENTRY CmnSigClearSignalBit(HCSSIGNAL hcSignal,ULONG ulSignal);
  1256. //-------------------------------------------------------------------------
  1257. // This function clears the specified signal value bits for the specified
  1258. // signal handle.
  1259. //
  1260. // Input:  hcSignal - specifies the signal handle to clear
  1261. //         ulSignal - specifies the signal bits to clear
  1262. // Returns:  TRUE if successful, FALSE otherwise
  1263. //-------------------------------------------------------------------------
  1264.  
  1265. BOOL EXPENTRY CmnSigSetAllSignalValues(HCSSIGNALLIST hcsList,ULONG ulSignal);
  1266. //-------------------------------------------------------------------------
  1267. // This function sets all of the signals in the specified list to a specific
  1268. // value.
  1269. //
  1270. // Input:  hcsList - specifies the list to set
  1271. //         ulSignal - specifies the new value of the list
  1272. // Returns:  TRUE if successful, FALSE otherwise
  1273. //-------------------------------------------------------------------------
  1274.  
  1275. BOOL EXPENTRY CmnSigSetAllSignalBits(HCSSIGNALLIST hcsList,ULONG ulSignal);
  1276. //-------------------------------------------------------------------------
  1277. // This function sets the specified bits of all of the signals in the
  1278. // specified list.
  1279. //
  1280. // Input:  hcsList - specifies the list to set
  1281. //         ulSignal - specifies the new value of the list
  1282. // Returns:  TRUE if successful, FALSE otherwise
  1283. //-------------------------------------------------------------------------
  1284.  
  1285. BOOL EXPENTRY CmnSigClearAllSignalBits(HCSSIGNALLIST hcsList,ULONG ulSignal);
  1286. //-------------------------------------------------------------------------
  1287. // This function clears the specified bits of all of the signals in the
  1288. // specified list.
  1289. //
  1290. // Input:  hcsList - specifies the list to set
  1291. //         ulSignal - specifies the new value of the list
  1292. // Returns:  TRUE if successful, FALSE otherwise
  1293. //-------------------------------------------------------------------------
  1294.  
  1295. BOOL EXPENTRY CmnSigQuerySignalId(HCSSIGNAL hcSignal,PULONG pulId);
  1296. //-------------------------------------------------------------------------
  1297. // This function returns the id of the specified signal handle.
  1298. //
  1299. // Input:  hcSignal - specifies the signal handle to query
  1300. // Output:  pulId - points the variable specifying the signal id
  1301. // Returns:  TRUE if successful, FALSE otherwise
  1302. //-------------------------------------------------------------------------
  1303.  
  1304. BOOL EXPENTRY CmnSigQuerySignalValue(HCSSIGNAL hcSignal,PULONG pulSignal);
  1305. //-------------------------------------------------------------------------
  1306. // This function returns the current signal value for the specified signal.
  1307. //
  1308. // Input:  hcSignal - specifies the signal handle to query
  1309. // Output:  pulSignal - points the variable specifying the signal value
  1310. // Returns:  TRUE if successful, FALSE otherwise
  1311. //-------------------------------------------------------------------------
  1312.  
  1313. USHORT EXPENTRY CmnSigWaitSignalValue(HCSSIGNAL hcSignal,
  1314.                                       ULONG ulSignal,
  1315.                                       LONG lTimeout);
  1316. //-------------------------------------------------------------------------
  1317. // This function waits for a signal handle's signal value to equal a
  1318. // specified value, subject to a timeout.
  1319. //
  1320. // Input:  hcSignal - specifies the signal handle to wait for
  1321. //         ulSignal - specifies the signal value to wait for
  1322. //         lTimeout - specifies the timeout in milliseconds, or an
  1323. //                    SWS_TIMEOUT_* value
  1324. // Returns:  SWS_RC_SIGNALSET if the signal was set, SWS_RC_TIMEOUT if
  1325. //           a timeout occurred, or SWS_RC_ERROR if an error occurred
  1326. //-------------------------------------------------------------------------
  1327.  
  1328. USHORT EXPENTRY CmnSigWaitSignalBit(HCSSIGNAL hcSignal,
  1329.                                     ULONG ulSignal,
  1330.                                     LONG lTimeout);
  1331. //-------------------------------------------------------------------------
  1332. // This function waits for a signal handle's signal value to have a
  1333. // specific set of bits set, subject to a timeout.
  1334. //
  1335. // Note that this is different than CmnSigWaitSignal() in that the other
  1336. // bits can be any value, whereas the said function checks for equality
  1337. // for *all* bits.
  1338. //
  1339. // Input:  hcSignal - specifies the signal handle to wait for
  1340. //         ulSignal - specifies the signal value bits to wait for
  1341. //         lTimeout - specifies the timeout in milliseconds, or an
  1342. //                    SWS_TIMEOUT_* value
  1343. // Returns:  SWS_RC_SIGNALSET if the signal was set, SWS_RC_TIMEOUT if
  1344. //           a timeout occurred, or SWS_RC_ERROR if an error occurred
  1345. //-------------------------------------------------------------------------
  1346.  
  1347. USHORT EXPENTRY CmnSigWaitAllSignalValues(HCSSIGNALLIST hcsList,
  1348.                                           ULONG ulSignal,
  1349.                                           LONG lTimeout);
  1350. //-------------------------------------------------------------------------
  1351. // This function waits for *all* signal handles in the specified list to have
  1352. // the signal value specified, subject to a timeout.
  1353. //
  1354. // Input:  hcsList - specifies the signal list to wait for
  1355. //         ulSignal - specifies the signal value to wait for
  1356. //         lTimeout - specifies the timeout in milliseconds, or an
  1357. //                    SWS_TIMEOUT_* value
  1358. // Returns:  SWS_RC_SIGNALSET if the signal was set, SWS_RC_TIMEOUT if
  1359. //           a timeout occurred, or SWS_RC_ERROR if an error occurred
  1360. //-------------------------------------------------------------------------
  1361.  
  1362. USHORT EXPENTRY CmnSigWaitAllSignalBits(HCSSIGNALLIST hcsList,
  1363.                                         ULONG ulSignal,
  1364.                                         LONG lTimeout);
  1365. //-------------------------------------------------------------------------
  1366. // This function waits for *all* signal handles in the specified list to have
  1367. // the set of signal value bits set, subject to a timeout.
  1368. //
  1369. // Note that this is different than CmnSigWaitSignal() in that the other
  1370. // bits can be any value, whereas the said function checks for equality
  1371. // for *all* bits.
  1372. //
  1373. // Input:  hcsList - specifies the signal list to wait for
  1374. //         ulSignal - specifies the signal value to wait for
  1375. //         lTimeout - specifies the timeout in milliseconds, or an
  1376. //                    SWS_TIMEOUT_* value
  1377. // Returns:  SWS_RC_SIGNALSET if the signal was set, SWS_RC_TIMEOUT if
  1378. //           a timeout occurred, or SWS_RC_ERROR if an error occurred
  1379. //-------------------------------------------------------------------------
  1380. #endif                           // #ifdef INCL_CMNSIG
  1381.  
  1382. #ifdef INCL_CMNSPR
  1383. //-------------------------------------------------------------------------
  1384. // Sprite routines
  1385. //-------------------------------------------------------------------------
  1386. #define CmnSprCreatePlayground         CMNSPRCREATEPLAYGROUND
  1387. #define CmnSprDestroyPlayground        CMNSPRDESTROYPLAYGROUND
  1388. #define CmnSprAddSprite                CMNSPRADDSPRITE
  1389. #define CmnSprRemoveSprite             CMNSPRREMOVESPRITE
  1390. #define CmnSprSetPlaygroundBack        CMNSPRSETPLAYGROUNDBACK
  1391. #define CmnSprQueryPlaygroundBack      CMNSPRQUERYPLAYGROUNDBACK
  1392. #define CmnSprSetPlaygroundSize        CMNSPRSETPLAYGROUNDSIZE
  1393. #define CmnSprQueryPlaygroundSize      CMNSPRQUERYPLAYGROUNDSIZE
  1394. #define CmnSprSetPlaygroundColor       CMNSPRSETPLAYGROUNDCOLOR
  1395. #define CmnSprQueryPlaygroundColor     CMNSPRQUERYPLAYGROUNDCOLOR
  1396. #define CmnSprSetUpdateFlag            CMNSPRSETUPDATEFLAG
  1397. #define CmnSprQueryUpdateFlag          CMNSPRQUERYUPDATEFLAG
  1398. #define CmnSprDrawPlayground           CMNSPRDRAWPLAYGROUND
  1399. #define CmnSprCreateSprite             CMNSPRCREATESPRITE
  1400. #define CmnSprDestroySprite            CMNSPRDESTROYSPRITE
  1401. #define CmnSprSetSpritePosition        CMNSPRSETSPRITEPOSITION
  1402. #define CmnSprQuerySpritePosition      CMNSPRQUERYSPRITEPOSITION
  1403. #define CmnSprQuerySpriteSize          CMNSPRQUERYSPRITESIZE
  1404. #define CmnSprQuerySpriteRect          CMNSPRQUERYSPRITERECT
  1405. #define CmnSprSetSpriteVisibility      CMNSPRSETSPRITEVISIBILITY
  1406. #define CmnSprQuerySpriteVisibility    CMNSPRQUERYSPRITEVISIBILITY
  1407. #define CmnSprDrawSprite               CMNSPRDRAWSPRITE
  1408. #define CmnSprSetLayering              CMNSPRSETLAYERING
  1409. #define CmnSprQueryLayering            CMNSPRQUERYLAYERING
  1410.  
  1411. SPRERROR EXPENTRY CmnSprCreatePlayground(HAB habAnchor,
  1412.                                          PHCSPLAYGROUND phpgPlay);
  1413. //-------------------------------------------------------------------------
  1414. // This function creates a playground to which sprites can be added.
  1415. //
  1416. // Input:  habAnchor - anchor block of the calling thread.
  1417. // Output:  phpgPlay - points to the variable with the HCSPLAYGROUND handle
  1418. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1419. //-------------------------------------------------------------------------
  1420.  
  1421. SPRERROR EXPENTRY CmnSprDestroyPlayground(HCSPLAYGROUND hpgPlay);
  1422. //-------------------------------------------------------------------------
  1423. // This function destroys the playground including any sprites that are
  1424. // still members of it.  All resources consumed by the playground,
  1425. // including the back bitmap, are returned to the system.
  1426. //
  1427. // Input:  hpgPlay - handle to the playground
  1428. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1429. //-------------------------------------------------------------------------
  1430.  
  1431. SPRERROR EXPENTRY CmnSprAddSprite(HCSPLAYGROUND hpgPlay,HCSSPRITE hsSprite);
  1432. //-------------------------------------------------------------------------
  1433. // This function labels a sprite as a "member" of the specified playground.
  1434. // Doing so allows the application to control the sprite's position,
  1435. // visibility, etc. on a drawing surface.
  1436. //
  1437. // Input:  hpgPlay - handle to the playground
  1438. //         hsSprite - handle to the sprite to add
  1439. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1440. //-------------------------------------------------------------------------
  1441.  
  1442. SPRERROR EXPENTRY CmnSprRemoveSprite(HCSPLAYGROUND hpgPlay,HCSSPRITE hsSprite);
  1443. //-------------------------------------------------------------------------
  1444. // This function removes the sprite from the membership list of the
  1445. // specified playground.  The sprite can then be added to another
  1446. // playground, or this one at a later time.
  1447. //
  1448. // Since there is a limited number of sprites that can be members of
  1449. // a playground, this function can be used to temporarily remove unused
  1450. // sprites from a playground so that others can be used.
  1451. //
  1452. // Input:  hpgPlay - handle to the playground
  1453. //         hsSprite - handle to the sprite to remove
  1454. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1455. //-------------------------------------------------------------------------
  1456.  
  1457. SPRERROR EXPENTRY CmnSprSetPlaygroundBack(HCSPLAYGROUND hpgPlay,
  1458.                                           HBITMAP hbmNew,
  1459.                                           HBITMAP *phbmOld);
  1460. //-------------------------------------------------------------------------
  1461. // This function sets the background bitmap of the playground.
  1462. //
  1463. // Note that, once this function is called, the bitmap is managed by
  1464. // the sprite subsystem.  The bitmap should *NOT* be deleted by the
  1465. // application unless the bitmap is "unset" from the playground (by
  1466. // calling this function again with a different handle).
  1467. //
  1468. // Input:  hpgPlay - handle to the playground
  1469. //         hbmNew - handle to the new bitmap to used as the background
  1470. // Output:  phbmOld - points to the handle to the old background bitmap.
  1471. //          This can be NULL, meaning that the application isn't interested
  1472. //          in receiving this value.
  1473. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1474. //-------------------------------------------------------------------------
  1475.  
  1476. SPRERROR EXPENTRY CmnSprQueryPlaygroundBack(HCSPLAYGROUND hpgPlay,
  1477.                                             HBITMAP *phbmBack);
  1478. //-------------------------------------------------------------------------
  1479. // This function returns the handle of the background bitmap currently in
  1480. // use.
  1481. //
  1482. // Input:  hpgPlay - handle to the playground
  1483. // Output:  phbmBack - points to the handle to the background bitmap.
  1484. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1485. //-------------------------------------------------------------------------
  1486.  
  1487. SPRERROR EXPENTRY CmnSprSetPlaygroundSize(HCSPLAYGROUND hpgPlay,
  1488.                                           PSIZEL pszlSize);
  1489. //-------------------------------------------------------------------------
  1490. // This function sets the playground size for playgrounds that do not have
  1491. // a bitmap set as the background.
  1492. //
  1493. // Input:  hpgPlay - handle to the playground
  1494. //         pszlSize - points to the size of the playground
  1495. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1496. //-------------------------------------------------------------------------
  1497.  
  1498. SPRERROR EXPENTRY CmnSprQueryPlaygroundSize(HCSPLAYGROUND hpgPlay,
  1499.                                             PSIZEL pszlSize);
  1500. //-------------------------------------------------------------------------
  1501. // This function returns the size of the playground.  For playgrounds with
  1502. // bitmaps set as the background, the returned value is the size of the
  1503. // bitmap.  Otherwise, the returned value is that which was specified on
  1504. // the last call to CmnSprSetPlaygroundSize().
  1505. //
  1506. // Input:  hpgPlay - handle to the playground
  1507. //         pszlSize - points to the variable to receive the size of the
  1508. //                    playground
  1509. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1510. //-------------------------------------------------------------------------
  1511.  
  1512. SPRERROR EXPENTRY CmnSprSetPlaygroundColor(HCSPLAYGROUND hpgPlay,
  1513.                                            LONG lBackColor);
  1514. //-------------------------------------------------------------------------
  1515. // This function sets the new background color of the playground and is
  1516. // only valid if the playground doesn't have a bitmap.
  1517. //
  1518. // Input:  hpgPlay - handle to the playground
  1519. //         lBackColor - specifies the new background color
  1520. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1521. //-------------------------------------------------------------------------
  1522.  
  1523. SPRERROR EXPENTRY CmnSprQueryPlaygroundColor(HCSPLAYGROUND hpgPlay,
  1524.                                              PLONG plBackColor);
  1525. //-------------------------------------------------------------------------
  1526. // This function returns the background color of the playground and is
  1527. // only valid if the playground doesn't have a bitmap.
  1528. //
  1529. // Input:  hpgPlay - handle to the playground
  1530. //         plBackColor - points to the variable to receive the background
  1531. //                       color
  1532. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1533. //-------------------------------------------------------------------------
  1534.  
  1535. SPRERROR EXPENTRY CmnSprSetUpdateFlag(HCSPLAYGROUND hpgPlay,BOOL bUpdate);
  1536. //-------------------------------------------------------------------------
  1537. // This function sets the update flag for the playground.  If FALSE, no
  1538. // drawing actually takes place in any of the functions requiring an HPS,
  1539. // and the value of the HPS handle may be NULLHANDLE.  If TRUE, updating
  1540. // is reenabled, but you should still call CmnSprDrawPlayground() to refresh
  1541. // the screen with the current contents.
  1542. //
  1543. // Input:  hpgPlay - handle to the playground
  1544. //         bUpdate - specifies the new update flag
  1545. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1546. //-------------------------------------------------------------------------
  1547.  
  1548. SPRERROR EXPENTRY CmnSprQueryUpdateFlag(HCSPLAYGROUND hpgPlay,PBOOL pbUpdate);
  1549. //-------------------------------------------------------------------------
  1550. // This function returns the setting of the update flag.  See the notes
  1551. // for CmnSprSetUpdateFlag() for more information about this setting.
  1552. //
  1553. // Input:  hpgPlay - handle to the playground
  1554. //         pbUpdate - points to the variable to receive the update flag
  1555. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1556. //-------------------------------------------------------------------------
  1557.  
  1558. SPRERROR EXPENTRY CmnSprDrawPlayground(HPS hpsDraw,HCSPLAYGROUND hpgPlay);
  1559. //-------------------------------------------------------------------------
  1560. // This function redraws the playground and all sprites belonging to the
  1561. // playground.
  1562. //
  1563. // Input:  hpsDraw - handle to the HPS to draw the playground in
  1564. //         hpgPlay - handle to the playground
  1565. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1566. //-------------------------------------------------------------------------
  1567.  
  1568. SPRERROR EXPENTRY CmnSprCreateSprite(HAB habAnchor,
  1569.                                      HBITMAP hbmBitmap,
  1570.                                      PHCSSPRITE phsSprite);
  1571. //-------------------------------------------------------------------------
  1572. // This function creates a sprite from the specified bitmap.  The sprite
  1573. // cannot be moved, shown, etc., however, until it is associated with a
  1574. // playground.
  1575. //
  1576. // The color black is used as the transparency color.  If you need to use
  1577. // black in the bitmap without it becoming transparent, use the next
  1578. // closest color.  <grin>
  1579. //
  1580. // New sprites are initialized as being at position (0,0) and hidden.
  1581. //
  1582. // Note that, once this function is called, the bitmap is managed by
  1583. // the sprite subsystem.  The bitmap should *NOT* be deleted by the
  1584. // application or else unpredictable results will occur.
  1585. //
  1586. // Input:  habAnchor - anchor block of the calling thread.
  1587. //         hbmBitmap - handle to the bitmap
  1588. // Output:  phsSprite - points to the sprite handle
  1589. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1590. //-------------------------------------------------------------------------
  1591.  
  1592. SPRERROR EXPENTRY CmnSprDestroySprite(HCSSPRITE hsSprite);
  1593. //-------------------------------------------------------------------------
  1594. // This function destroys the sprite and returns all resources to the
  1595. // system.
  1596. //
  1597. // Input:  hsSprite - handle to the sprite
  1598. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1599. //-------------------------------------------------------------------------
  1600.  
  1601. SPRERROR EXPENTRY CmnSprSetSpritePosition(HPS hpsDraw,
  1602.                                           HCSSPRITE hsSprite,
  1603.                                           PPOINTL pptlNew);
  1604. //-------------------------------------------------------------------------
  1605. // This function changes the position of the sprite.  This function is
  1606. // optimized so that, if the rectangle bounding the sprite at the new
  1607. // position overlaps the old, only one "bit blit" to the specified HPS
  1608. // is done, eliminating flicker.
  1609. //
  1610. // Input:  hpsDraw - handle to the HPS to draw the sprite in once it is
  1611. //                   moved
  1612. //         hsSprite - handle to the sprite
  1613. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1614. //-------------------------------------------------------------------------
  1615.  
  1616. SPRERROR EXPENTRY CmnSprQuerySpritePosition(HCSSPRITE hsSprite,
  1617.                                             PPOINTL pptlPos);
  1618. //-------------------------------------------------------------------------
  1619. // This function returns the current position of the sprite.  Note that
  1620. // a sprite has a current position even if it is hidden.
  1621. //
  1622. // Input:  hsSprite - handle to the sprite
  1623. // Output:  pptlPos - points to the current position
  1624. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1625. //-------------------------------------------------------------------------
  1626.  
  1627. SPRERROR EXPENTRY CmnSprQuerySpriteSize(HCSSPRITE hsSprite,PSIZEL pszlSize);
  1628. //-------------------------------------------------------------------------
  1629. // This function returns the current size of the sprite.
  1630. //
  1631. // Input:  hsSprite - handle to the sprite
  1632. // Output:  pszlSize - points to the current size
  1633. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1634. //-------------------------------------------------------------------------
  1635.  
  1636. SPRERROR EXPENTRY CmnSprQuerySpriteRect(HCSSPRITE hsSprite,PRECTL prclRect);
  1637. //-------------------------------------------------------------------------
  1638. // This function returns the bounding rectangle of the sprite at its
  1639. // current position.
  1640. //
  1641. // Input:  hsSprite - handle to the sprite
  1642. // Output:  prclRect - points to the current bounding rectangle
  1643. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1644. //-------------------------------------------------------------------------
  1645.  
  1646. SPRERROR EXPENTRY CmnSprSetSpriteVisibility(HPS hpsDraw,
  1647.                                             HCSSPRITE hsSprite,
  1648.                                             BOOL bVisible);
  1649. //-------------------------------------------------------------------------
  1650. // This function shows or hides a sprite.
  1651. //
  1652. // Input:  hpsDraw - handle to the HPS to draw in once the sprite is
  1653. //                   shown or hidden
  1654. //         hsSprite - handle to the sprite
  1655. //         bVisible - new visibility state
  1656. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1657. //-------------------------------------------------------------------------
  1658.  
  1659. SPRERROR EXPENTRY CmnSprQuerySpriteVisibility(HCSSPRITE hsSprite,
  1660.                                               PBOOL pbVisible);
  1661. //-------------------------------------------------------------------------
  1662. // This function returns the visibility state of the sprite
  1663. //
  1664. // Input:  hsSprite - handle to the sprite
  1665. // Output:  pbVisible - points to the visibility state
  1666. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1667. //-------------------------------------------------------------------------
  1668.  
  1669. SPRERROR EXPENTRY CmnSprDrawSprite(HPS hpsDraw,HCSSPRITE hsSprite);
  1670. //-------------------------------------------------------------------------
  1671. // This function draws a sprite
  1672. //
  1673. // Input:  hpsDraw - handle to the HPS to draw the sprite in
  1674. //         hsSprite - handle to the sprite
  1675. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1676. //-------------------------------------------------------------------------
  1677.  
  1678. SPRERROR EXPENTRY CmnSprSetLayering(HPS hpsDraw,HCSSPRITE hsSprite,LONG lPos);
  1679. //-------------------------------------------------------------------------
  1680. // This function sets the z-order of a sprite.
  1681. //
  1682. // Input:  hpsDraw - handle to the HPS to make the updates in.
  1683. //         hsSprite - handle to the sprite whose z-order is to be changed
  1684. //         lPos - an absolute layer number (0 to MAX_SPRITES-1) or an
  1685. //                SSL_* constant.
  1686. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1687. //-------------------------------------------------------------------------
  1688.  
  1689. SPRERROR EXPENTRY CmnSprQueryLayering(HCSSPRITE hsSprite,PLONG plPos);
  1690. //-------------------------------------------------------------------------
  1691. // This function sets the z-order of a sprite.
  1692. //
  1693. // Input:  hsSprite - handle to the sprite whose z-order is to be queried
  1694. //         plPos - points to the variable to receive the layer number.
  1695. // Output:  plPos - points to the layer number (0 to MAX_SPRITES-1).
  1696. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1697. //-------------------------------------------------------------------------
  1698. #endif                           // #ifdef INCL_CMNSPR
  1699.  
  1700. #ifdef INCL_CMNSTR
  1701. //-------------------------------------------------------------------------
  1702. // String routines
  1703. //-------------------------------------------------------------------------
  1704. #define CmnStrQueryWordCount           CMNSTRQUERYWORDCOUNT
  1705. #define CmnStrQueryWordPosition        CMNSTRQUERYWORDPOSITION
  1706. #define CmnStrQueryWordLength          CMNSTRQUERYWORDLENGTH
  1707. #define CmnStrQueryWord                CMNSTRQUERYWORD
  1708. #define CmnStrConvertToNumber          CMNSTRCONVERTTONUMBER
  1709. #define CmnStrParseLine                CMNSTRPARSELINE
  1710. #define CmnStrParseCommandLine         CMNSTRPARSECOMMANDLINE
  1711. #define CmnStrPadString                CMNSTRPADSTRING
  1712. #define CmnStrStripSpace               CMNSTRSTRIPSPACE
  1713.  
  1714. USHORT EXPENTRY CmnStrQueryWordCount(PCHAR pchLine);
  1715. //-------------------------------------------------------------------------
  1716. // This function returns the number of words in the specified string
  1717. //
  1718. // Input:  pchLine - points to the string to query
  1719. // Returns:  number of words in the string
  1720. //-------------------------------------------------------------------------
  1721.  
  1722. SHORT EXPENTRY CmnStrQueryWordPosition(PCHAR pchLine,SHORT sWord);
  1723. //-------------------------------------------------------------------------
  1724. // This function finds the 0-based position of the specified word in the
  1725. // specified string.
  1726. //
  1727. // Input:  pchLine - points to the string to search
  1728. //         sWord - specifies the word number
  1729. // Returns:  position of the word if successful, SQWP_ERROR otherwise
  1730. //-------------------------------------------------------------------------
  1731.  
  1732. SHORT EXPENTRY CmnStrQueryWordLength(PCHAR pchLine,SHORT sWord);
  1733. //-------------------------------------------------------------------------
  1734. // This function returns the length of the word specified.
  1735. //
  1736. // Input:  pchLine - points to the string to search
  1737. //         sWord - specifies the word number
  1738. // Returns:  length of the word if successful, SQWP_ERROR otherwise
  1739. //-------------------------------------------------------------------------
  1740.  
  1741. BOOL EXPENTRY CmnStrQueryWord(PCHAR pchLine,
  1742.                               SHORT sWord,
  1743.                               PCHAR pchWord,
  1744.                               USHORT usSzWord);
  1745. //-------------------------------------------------------------------------
  1746. // This function extracts a word non-destructively from the specified line
  1747. // and copies it to the specified buffer.
  1748. //
  1749. // Input:  pchLine - points to the line to parse
  1750. //         sWord - contains the 0-based word number to extract
  1751. //         usSzWord - contains the size of the buffer pointed to by pchWord
  1752. // Output:  pchWord - points to the extracted word
  1753. // Returns:  TRUE if successful, FALSE otherwise
  1754. //-------------------------------------------------------------------------
  1755.  
  1756. BOOL EXPENTRY CmnStrConvertToNumber(PCHAR pchString,
  1757.                                     PVOID pvResult,
  1758.                                     USHORT usType);
  1759. //-------------------------------------------------------------------------
  1760. // This function converts a string to a number.  This is more robust than the
  1761. // ato*() family since this positively indicates whether or not an error
  1762. // occurred.
  1763. //
  1764. // Input:  pchString - points to the string to convert
  1765. //         usType - a combination of one SCTN_TYPE_* and one SCTN_ATTR_*
  1766. //                  constants.
  1767. // Output:  pvResult - points to the resulting number
  1768. // Returns:  TRUE if successful, FALSE otherwise
  1769. //-------------------------------------------------------------------------
  1770.  
  1771. SHORT EXPENTRY CmnStrParseLine(PCHAR pchLine,
  1772.                                PCSLINEDESC pcFormat,
  1773.                                USHORT usNumRecs,
  1774.                                PBYTE pbBuf);
  1775. //-------------------------------------------------------------------------
  1776. // This function parses the specified line, whose format is described by an
  1777. // array of CSLINEDESC structures (acFormat).  If the usType field of a
  1778. // CSLINEDESC record is blank, then usLength bytes are skipped in the
  1779. // result buffer, allowing the caller to have other fields that are not to
  1780. // be filled in by this function.
  1781. //
  1782. // Upon exit, the usType field is either SPL_FOUND or SPL_NOTFOUND, indicating
  1783. // whether or not a non-whitespace character was found in the usOffset<->
  1784. // usOffset+usLength-1 positions of the line.
  1785. //
  1786. // For each field descriptor, the corresponding field is extracted, and
  1787. // CmnStrConvertToNumber is called if the destination type is numeric.
  1788. //
  1789. // Notes:
  1790. // For numeric types, an SPL_ATTR_* constant may be or'd to specify
  1791. //    whether or not the number is in decimal or hexidecimal
  1792. // For SPL_TYPE_STRING fields, usLength also specifies the width of the
  1793. //    placeholder in pbBuf and does not include the trailing '\0'.
  1794. // For SPL_TYPE_RESERVED fields, usType always equals SPL_FOUND on return.
  1795. //
  1796. // Input:  pchLine - points to the line to parse
  1797. //         pcFormat - points to an array of CSLINEDESC describing the line
  1798. //         usNumRecs - specifies the number of CSLINEDESC records are
  1799. //                     pointed to by acFormat
  1800. // Output:  pcFormat - usType field indicates found/not found status of the
  1801. //                     field
  1802. //          pbBuf - points to the parsed line
  1803. // Returns:  the number of fields found is successful, SPL_ERROR otherwise
  1804. //-------------------------------------------------------------------------
  1805.  
  1806. BOOL EXPENTRY CmnStrParseCommandLine(PCHAR *ppchArgs,
  1807.                                      USHORT usNumArgs,
  1808.                                      PCSCMDDESC pccdFormat,
  1809.                                      USHORT usNumSwitches,
  1810.                                      PFNCMDERR pfnError,
  1811.                                      PVOID pvData);
  1812. //-------------------------------------------------------------------------
  1813. // This function parses the command line as described by the pccdFormat
  1814. // switch description array.
  1815. //
  1816. // Input:  ppchArgs - points to an array of pointers to the command-line
  1817. //                    arguments
  1818. //         usNumArgs - specifies the number of command-line arguments,
  1819. //                     including the program name (ppchArgs[0])
  1820. //         pccdFormat - points to an array of CSCMDDESC structs describing
  1821. //                      the valid command-line arguments:
  1822. //
  1823. //                      usId - specifies a unique id assigned to the switch.
  1824. //                             This is used by the pfnCallback function.
  1825. //                      achSwitch - points to the switch string, without the
  1826. //                                  leading "-" or "/".
  1827. //                      usNumArgs - specifies the number of arguments the
  1828. //                                  switch requires.
  1829. //                      usFlags - specifies a combination of SPCL_FLG_*
  1830. //                                constants describing the switch's attributes:
  1831. //
  1832. //                                SPCL_CASESENSITIVE specifies that achSwitch
  1833. //                                                   is case-sensitive.
  1834. //                                SPCL_SUBSTRING     specifies that achSwitch
  1835. //                                                   is a substring of what
  1836. //                                                   will be encountered on
  1837. //                                                   the command line (e.g
  1838. //                                                   "-FPa" where "FP" is the
  1839. //                                                   switch).
  1840. //                                SPCL_ARGCONCAT     (valid only with
  1841. //                                                   SPCL_SUBSTRING)
  1842. //                                                   specifies that the first
  1843. //                                                   argument is concatenated
  1844. //                                                   to the switch name (e.g.
  1845. //                                                   "-FPa" where "a" is the
  1846. //                                                   argument)
  1847. //                      pfnCallback - points to a function which is called
  1848. //                                    whenever a switch match is found.  It
  1849. //                                    takes the following arguments:
  1850. //
  1851. //                                    USHORT - the identifier of the switch as
  1852. //                                             specified in the CSCMDDESC
  1853. //                                             structure.
  1854. //                                    PCHAR * - the switch arguments.
  1855. //                                    USHORT - the number of arguments.
  1856. //                                    PVOID - application-defined data
  1857. //                                    Returns - TRUE if successful, FALSE
  1858. //                                              otherwise.
  1859. //         usNumSwitches - specifies the number of CSCMDDESC structures are
  1860. //                         pointed to by pccdFormat.
  1861. //         pfnError - points to an error function which is called whenever
  1862. //                    CmnStrParseCommandLine encounters an error.  It takes
  1863. //                    a USHORT - specifying a SPCL_ERR_* error id - followed
  1864. //                    by a PVOID which is the value of pvData.
  1865. //         pvData - application-defined data passed to pfnCallback
  1866. // Returns:  TRUE if successful, FALSE otherwise
  1867. //-------------------------------------------------------------------------
  1868.  
  1869. BOOL EXPENTRY CmnStrPadString(PCHAR pchString,
  1870.                               USHORT usSide,
  1871.                               USHORT usLength,
  1872.                               CHAR chPad);
  1873. //-------------------------------------------------------------------------
  1874. // This function pads a string to the specified length with the specified
  1875. // character.  It is assumed that the string is large enough to contain
  1876. // the result.
  1877. //
  1878. // Input:  pchString - points to the string to pad.  On exit, the string
  1879. //                     is padded
  1880. //         usSide - specifies the side on which to pad.  It can be SPS_LEFT
  1881. //                  or SPS_RIGHT.
  1882. //         usLength - specifies the desired length of the string.
  1883. //         chPad - specifies the character to pad with.
  1884. // Returns:  TRUE if successful, FALSE otherwise
  1885. //-------------------------------------------------------------------------
  1886.  
  1887. BOOL EXPENTRY CmnStrStripSpace(PCHAR pchString,USHORT usOptions);
  1888. //-------------------------------------------------------------------------
  1889. // This function removes the whitespace from the beginning or the end of the
  1890. // specified string.
  1891. //
  1892. // Input:  pchString - points to the string to strip
  1893. //         usOptions - SPS_LEFT, SPS_RIGHT, or a combination of both
  1894. //                     to specify from which side(s) the whitespace should
  1895. //                     be removed
  1896. // Returns:  TRUE if successful, FALSE otherwise
  1897. //-------------------------------------------------------------------------
  1898. #endif                           // #ifdef INCL_CMNSTR
  1899.  
  1900. #ifdef INCL_CMNVIO
  1901. //-------------------------------------------------------------------------
  1902. // Screen I/O routines
  1903. //-------------------------------------------------------------------------
  1904. #define CmnVioLoadMessage              CMNVIOLOADMESSAGE
  1905. #define CmnVioDisplayMessage           CMNVIODISPLAYMESSAGE
  1906. #define CmnVioGetString                CMNVIOGETSTRING
  1907.  
  1908. BOOL EXPENTRY CmnVioLoadMessage(PCHAR pchMsgFile,
  1909.                                 ULONG ulId,
  1910.                                 PCHAR pchBuf,
  1911.                                 ULONG ulSzBuf);
  1912. //-------------------------------------------------------------------------
  1913. // This function loads a message from the specified message file.
  1914. //
  1915. // Input:  pchMsgFile - pointer to the message file name to load from
  1916. //         ulId - id of the message to load
  1917. //         pchBuf - pointer to the receiving buffer
  1918. //         ulSzBuf - size of the buffer pointed to by pchBuf
  1919. // Output:  pchBuf - points to the message text
  1920. // Returns:  TRUE if successful, FALSE otherwise
  1921. //-------------------------------------------------------------------------
  1922.  
  1923. BOOL EXPENTRY CmnVioDisplayMessage(PCHAR pchMsgFile,ULONG ulId,...);
  1924. //-------------------------------------------------------------------------
  1925. // This function puts a message to the screen in character mode.
  1926. //
  1927. // Input:  pchMsgFile - pointer to the message file name to load from
  1928. //         ulId - id of the message to load
  1929. // Returns:  TRUE if successful, FALSE otherwise
  1930. //-------------------------------------------------------------------------
  1931.  
  1932. BOOL CmnVioGetString(PCHAR pchBuf,ULONG ulSzBuf,ULONG ulOptions);
  1933. //-------------------------------------------------------------------------
  1934. // This function gets a string from the user.  The behavior of this
  1935. // function can be influenced by the options specified:
  1936. //
  1937. //    VGS_UNREADABLE    - the string should be unreadable.
  1938. //
  1939. // This function requires that the ANSI device driver is loaded.
  1940. //
  1941. // Input:  pchBuf - points to the buffer to hold the result
  1942. //         ulSzBuf - specifies the size of the buffer pointed to by pchBuf
  1943. //         ulOptions - one or more VGS_* constants
  1944. // Output:  pchBuf - points to the buffer containing the result
  1945. // Returns:  TRUE if successful, FALSE otherwise
  1946. //-------------------------------------------------------------------------
  1947. #endif                           // #ifdef INCL_CMNVIO
  1948.  
  1949. #ifdef INCL_CMNWIN
  1950. //-------------------------------------------------------------------------
  1951. // Windowing routines
  1952. //-------------------------------------------------------------------------
  1953. #define CmnWinDisplayMessage           CMNWINDISPLAYMESSAGE
  1954. #define CmnWinCenterWindow             CMNWINCENTERWINDOW
  1955. #define CmnWinSavePosition             CMNWINSAVEPOSITION
  1956. #define CmnWinRestorePosition          CMNWINRESTOREPOSITION
  1957. #define CmnWinSavePosToBuffer          CMNWINSAVEPOSTOBUFFER
  1958. #define CmnWinRestorePosFromBuffer     CMNWINRESTOREPOSFROMBUFFER
  1959.  
  1960. SHORT EXPENTRY CmnWinDisplayMessage(HWND hwndParent,
  1961.                                     HWND hwndOwner,
  1962.                                     ULONG ulStyle,
  1963.                                     HMODULE hmDll,
  1964.                                     USHORT usId,
  1965.                                     USHORT usHelpId,...);
  1966. //-------------------------------------------------------------------------
  1967. // This function puts a message to the screen in PM mode (using WinMessageBox).
  1968. // The title of the message box is assumed to have the message id usId|0x8000.
  1969. //
  1970. // Input:  hwndParent - handle of the parent window
  1971. //         hwndOwner - handle of the owning window
  1972. //         ulStyle - specifies the WinMessageBox styles
  1973. //         hmDll - handle of the DLL containing the message
  1974. //         usId - specifies the id of the message to load
  1975. //         usHelpId - specifies the id of the corresponding help panel
  1976. // Returns:  TRUE if successful, FALSE otherwise
  1977. //-------------------------------------------------------------------------
  1978.  
  1979. VOID EXPENTRY CmnWinCenterWindow(HWND hwndCenter);
  1980. //-------------------------------------------------------------------------
  1981. // This function centers the window within its parent
  1982. //
  1983. // Input:  hwndCenter - handle of the window to center
  1984. //-------------------------------------------------------------------------
  1985.  
  1986. BOOL EXPENTRY CmnWinSavePosition(HWND hwndWindow,
  1987.                                  HINI hiniProfile,
  1988.                                  PCHAR pchAppl,
  1989.                                  PCHAR pchKey);
  1990. //-------------------------------------------------------------------------
  1991. // This function saves the current position of the specified window in the
  1992. // specified .INI file
  1993. //
  1994. // Input:  hwndWindow - specifies the window to save
  1995. //         hiniProfile - specifies the profile to save to
  1996. //         pchAppl - specifies the application name to save as
  1997. //         pchKey - specifies the key name to save as
  1998. // Returns:  TRUE if successful, FALSE otherwise
  1999. //-------------------------------------------------------------------------
  2000.  
  2001. BOOL EXPENTRY CmnWinRestorePosition(HWND hwndWindow,
  2002.                                     HINI hiniProfile,
  2003.                                     PCHAR pchAppl,
  2004.                                     PCHAR pchKey);
  2005. //-------------------------------------------------------------------------
  2006. // This function restores the current position of the specified window from the
  2007. // specified .INI file
  2008. //
  2009. // Input:  hwndWindow - specifies the window to restore
  2010. //         hiniProfile - specifies the profile to restore from
  2011. //         pchAppl - specifies the application name to restore from
  2012. //         pchKey - specifies the key name to restore from
  2013. // Returns:  TRUE if successful, FALSE otherwise
  2014. //-------------------------------------------------------------------------
  2015.  
  2016. BOOL EXPENTRY CmnWinSavePosToBuffer(HWND hwndWindow,PCWPOSITION pcpPosition);
  2017. //-------------------------------------------------------------------------
  2018. // This function saves the current position of the specified window in the
  2019. // specified buffer
  2020. //
  2021. // Input:  hwndWindow - specifies the window to save
  2022. // Output:  pcpPosition - points to the variable containing the size and
  2023. //                        position data
  2024. // Returns:  TRUE if successful, FALSE otherwise
  2025. //-------------------------------------------------------------------------
  2026.  
  2027. BOOL EXPENTRY CmnWinRestorePosFromBuffer(HWND hwndWindow,
  2028.                                          PCWPOSITION pcpPosition);
  2029. //-------------------------------------------------------------------------
  2030. // This function restores the current position of the specified window from the
  2031. // specified buffer
  2032. //
  2033. // Input:  hwndWindow - specifies the window to restore
  2034. //         pcpPosition - points to the variable containing the size and
  2035. //                       position data
  2036. // Returns:  TRUE if successful, FALSE otherwise
  2037. //-------------------------------------------------------------------------
  2038. #endif                           // #ifdef INCL_CMNWIN
  2039.  
  2040. #ifdef __cplusplus
  2041. }
  2042. #endif                           // #ifdef __cplusplus
  2043.  
  2044. #pragma pack()
  2045.  
  2046. #endif                           // #ifndef COMMONLIB_INCLUDED
  2047.