home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 14 Text / 14-Text.zip / acslng.txt < prev    next >
Text File  |  1995-06-19  |  37KB  |  1,044 lines
  1.  
  2.  
  3.                        ACCESS WPS INFORMATION
  4.               Copyright 1993, 1994, 1995 by SofTouch Systems
  5.  
  6.                          GENERAL DESCRIPTION
  7.  
  8. AccessWPS is a set of files that allow any PM program to access any
  9. WPS method, that can be legally used by a WPS application. 
  10.  
  11. AccessWPS has been developed by SofTouch Systems. Our phone number is 
  12. 800-944-3028, ask for Felix Cruz, and the fax number is 405-632-6537. You 
  13. can order via Email by sending a message to Felix at 74774,705. The 
  14. Technical support person is Larry Martin whose Compuserve ID is 72662,3616. 
  15. If you have any questions or problems with this application, you should 
  16. contact Larry or SofTouch Systems
  17.  
  18. Normally, any developer that needs to use one of the methods of a WPS
  19. Object must use the SOM Compiler to develop their own WPS Object and
  20. then use that Object to actually call one of the WPS Object methods.
  21. The reason for this is that WPS runs as a separate process and it is
  22. only possible to call one of the WPS methods while running as part of
  23. the WPS process. The only way to run as part of the WPS process is to
  24. create a WPS Object.
  25.  
  26. AccessWPS solves this problem by creating a general purpose WPS Agent
  27. Object that can call any WPS Object method. The Agent Object can be
  28. invoked from any PM program by calling an API that is exactly the
  29. same as the WPS or SOM method, except that 'Acs' is appended to the
  30. front of the method name. For example, _somInit is called via
  31. AccessWPS by calling the Acs_somInit API. All of the 'Acs' API's
  32. return the exact same return as the corresponding WPS or SOM method,
  33. so it is as if it was possible to call the method directly from the
  34. PM application.
  35.  
  36.                      THE PROBLEM WITH POINTERS
  37.  
  38. The biggest with a general purpose WPS Agent concerns the area of
  39. pointers to various memory objects. Since WPS runs as a separate
  40. process, it cannot access any memory that belongs to the calling
  41. process and the calling process cannot access and memory that belongs
  42. to the WPS process. Therefore, a mechanism must be provided to
  43. address this problem.
  44.  
  45. Any developer using AccessWPS must be aware of 'hidden' pointers that
  46. are not obvious because the are hidden by some of the typedefs in the
  47. SOM and WPS header files. An example of this is the somId type. If
  48. you review the somtypes.h file, you will see that somId is actually a
  49. pointer to a pointer to the name of a Class or Object. What this
  50. means is that the developer must be careful to place the actual
  51. string pointed to in the shared memory area, see discussion below,
  52. before calling any of the SOM or WPS methods that use the somId data
  53. type. Failure to do this will result in either a NULL return from a
  54. method or, and worse, a protection violation in the WPS process.
  55.  
  56. AccessWPS provides two API's, AcsHeapAlloc and AcsHeapFree, which
  57. resolve the problem of how to pass memory objects to WPS. These two
  58. API's will allocate memory in a dynamically allocated memory pool
  59. that is shared between the WPS process and the user's process. This
  60. memory pool is allocated during the processing of the AcsInit API and
  61. is deleted during the processing of the AcsTerminate API. It is the
  62. responsibility of the developer that is using AccessWPS to insure
  63. that every pointer passed to WPS is a pointer that was returned by a
  64. call to the AcsHeapAlloc API. For example, to pass a string to WPS it
  65. is necessary to:
  66.  
  67. 1. Use AcsHeapAlloc to get a memory block that equals the length of
  68. the string plus one byte for the null character.
  69.  
  70. 2. Copy the string to the memory allocated via AcsHeapAlloc.
  71.  
  72. The above would also apply to any structure which is passed to WPS or
  73. a pointer that is passed and is pointing to an area that will contain
  74. returned information, this is done a lot with the _wpQuery type
  75. methods.
  76.  
  77. If a pointer to a structure is passed, after copying the structure to
  78. the memory block returned by AcsHeapAlloc, and the structure contains
  79. a pointer to another memory object or structure, the embedded pointer
  80. must also point to a memory block returned via AcsHeapAlloc.
  81.  
  82. Once the API call is complete, it is the responsibility of the
  83. developer to release any memory obtained via AcsHeapAlloc via the
  84. AcsHeapFree API. This memory should be treated more like stack space
  85. that as a heap. In other words, any memory obtained via AcsHeapAlloc
  86. should be returned via AcsHeapFree as quickly as possible.
  87.  
  88. The other memory problem concerns pointers that are returned as a
  89. result of calling one of the WPS methods.  It is possible that the
  90. returned value will be a pointer to memory that is allocated to the
  91. WPS process. This pointer cannot be used by the PM Application to
  92. access the memory object that is being pointed to, since the PM
  93. Application cannot access memory that belongs to a different process.
  94. The call to the 'Acs' API makes no attempt to resolve this problem.
  95. The reason no attempt is made is because it will often be the case
  96. that the returned pointer is only going to be used in a subsequent
  97. call to another WPS or SOM method, and the PM Application has no need
  98. to access the actual memory pointed to.  However, there are cases
  99. where the PM application needs access to the memory pointed to so an
  100. API has been provided, AcsResolvePointer, that will return a pointer
  101. to a memory object that can be used by the PM process that is a copy
  102. of the same memory in the WPS process. This memory object is
  103. allocated via DosAllocMem and it is the responsibility of the calling
  104. application to free the memory via DosFreeMem.
  105.  
  106. **********************************************************************
  107.  
  108.                         API PROCESSING FLOW
  109.  
  110. AccessWPS actually runs as two DLL's. One of the DLL's, AccssWPS.DLL
  111. runs as part of the user's process. The second DLL, AcsAgentDLL, runs
  112. as part of the WPS process. 
  113.  
  114. Before any WPS or SOM method can be called, the AccessWPS Agent
  115. Object must be created via the AcsInit API call. This API will cause
  116. the Agent Class to be registered with WPS, will create an instance of
  117. the AccessWPS Object and the Agent Object will open an Object Window
  118. which will be used by both DLL's to communicate with each other. In
  119. addition, some shared memory areas and semaphores are created by the
  120. AccssWPS.DLL and the AcsAgent.DLL will get a pointer to these areas
  121. by using their names.
  122.  
  123. Once all processing is completed, the PM Application must issue the
  124. AcsTerminate API. This API will destroy the AcsAgent Object,
  125. unregister the AccessWPS class and free the shared memory objects and
  126. semaphores.
  127.  
  128. The actual processing flow for each WPS or SOM method is as follows:
  129.  
  130. 1. The call of the 'Acs' API actually calls a subroutine for that
  131. specific method in the AccssWPS.DLL.
  132.  
  133. 2. The AccssWPS.DLL routine will allocate shared memory to hold the
  134. passed parameters and the return and fill in the parameters to be
  135. passed to the WPS or SOM method. In addition, any API that requires
  136. the SOMClassManager object ID as one of the parameters will check
  137. this parameter for a NULL and, if a NULL is found, will substitute
  138. the actual SOMClassManager value. This is necessary because it is not
  139. possible to access this constant value except when running as part of
  140. the WPS process.
  141.  
  142. 3. Once the shared memory is filled, the AccssWPS.DLL file will post a
  143. message to the AcsAgent Object Window and then wait on an Event
  144. Semaphore.
  145.  
  146. 4. When the AcsAgent.DLL Object Window receives the message, it will
  147. call a routine that will actually invoke the requested method and put
  148. the value returned from the method, if there is one, in the
  149. appropriate place in the shared memory.
  150.  
  151. 5. The AcsAgent.DLL code will then post the Event Semaphore.
  152.  
  153. 6. The posting of the Event Semaphore will cause the AccssWPS.DLL
  154. code to fall through the Wait.
  155.  
  156. 7. The AccssWPS.DLL code will save the returned value, if there is
  157. any, free the shared memory allocated for this API call and return to
  158. the calling PM application.
  159.  
  160. **********************************************************************
  161.  
  162.                         INSTALLATION
  163.  
  164. AccessWPS consists of three DLL's, an Import Library, an Include
  165. file and a Test program.
  166.  
  167. The two of the three DLL's must be copied into a directory that is in the 
  168. LIBPATH for the PM Application that will use them, the third AcsAgent.DLL 
  169. must be in a directory that is specifically listed in the LIBPATH. Normally, 
  170. the LIBPATH environment variable starts with '.;' which instructs OS/2 to
  171. look in the current directory for the DLL before looking in the other
  172. directories. This means that it is normally just fine to put the DLLs in the 
  173. default directory when running an application that uses DLL's. However, this 
  174. is not the case with the AcsAgent.DLL file of AccessWPS. This DLL is the 
  175. file that implements the WPS Agent Class and is loaded by WPS, not your 
  176. application. Therefore, both your app and the Installation test below will 
  177. fail if this DLL is not in a directory that is specifically listed in the 
  178. LIBPATH environment variable.
  179.  
  180. The Import Library, AccssWPS.LIB, must be copied to a directory that
  181. will make it available to the linker. This is normally a directory
  182. that is in the LIB= entry in the CONFIG.SYS file.
  183.  
  184. The Include file, AccssWPS.H, must be copied into a directory that
  185. will make it available to the compiler as an #include file. This is
  186. normally on of the directories in the INCLUDE= entry in the
  187. CONFIG.SYS file.
  188.  
  189. The Test program, AcsTest.exe, must be copied into a directory that
  190. will make it directly executable. This is normally a Directory that
  191. is in the PATH= entry in the CONFIG.SYS file.
  192.  
  193. The link of the PM Application must be modified so that the
  194. AccssWPS.LIB is included along with the other libraries.
  195.  
  196. Any C source module that calls any of the 'Acs' API's must include
  197. the AccssWPS.H include file. In addition, the source module must
  198. include the appropriate SOM or WPS #include file and the SOM and/or
  199. WPS include file must precede the AccssWPS.H file. The reason the SOM
  200. and/or WPS include files are required is because the 'Acs' API's use
  201. the same data types as the actual WPS and SOM methods and these data
  202. types are defined in the SOM and WPS include files. There are tests
  203. in the AccssWPS.H include file that will only include the AccessWPS
  204. API's that correspond to the SOM and/or WPS include files that
  205. precede it. If none of these files precede the AccssWPS.H file, then
  206. none of the API's...except the special ones like AcsInit...will be
  207. defined.
  208.  
  209. **********************************************************************
  210.  
  211.                     VALIDATING INSTALLATION
  212.  
  213. Once the DLL's and the AcsTest program have been installed, it is
  214. suggested that the AcsTest program be run to verify that everything
  215. is working correctly. The AcsTest program has no command line
  216. parameters and, if everything is working correctly it will:
  217.  
  218. 1. Sound a rising series of tones that indicate the program
  219. is starting.
  220.  
  221. 2. A window will appear with a Listbox as the Client area.
  222.  
  223. 3. You will see a series of messages that will appear as the test
  224. program goes through it's cycle. There should be no messages that
  225. indicate that any of the functions was completed unsuccessfully.
  226.  
  227. 4. There will normally be a delay of a few seconds from the time you
  228. see the message that the creation of the Agent Object is starting and
  229. the message that it is complete. This is because the AcsAgent and
  230. Accsswps DLL's are loaded at this point.
  231.  
  232. 5. Once the Object is created. You will see a line with the Version
  233. information on it. If there are any problems, you might be asked for
  234. this version information, so it is worth while noting it.
  235.  
  236. 6. Once the version information has been displayed, several lines of
  237. internal variable information will be displayed. These are the
  238. internal variables for both the Agent Object and the AccssWPS module.
  239. This is done primarily to give the developer some idea of the kind of
  240. information that is returned when the dump lines are requested. It
  241. also provides a sample of how to get the dump information, since the
  242. source code for the AcsTest program is now included in the package.
  243.  
  244. 7. To terminate the AcsTest program, simply use the Close entry on
  245. the System Menu. You will hear a falling series of tones as the
  246. program terminates indicating that the termination was successful.
  247.  
  248. 8. If there is any error during the execution of AcsTest, you will
  249. see the error message surrounded by several lines of asterisks. In
  250. addition, you will see an error message telling you that the test was
  251. not successful at the very end of the display. If you do not see the
  252. error lines at the end of the display, then the test was successful.
  253.  
  254. 9. There are two common errors that can occur because of some sort of
  255. problem installing and/or running AccessWPS. The error codes are
  256. 10200 and 10201. If you see either of these errors during the running
  257. of the test, simply run the test a second time and it should work
  258. without an error. If you get the error two times in a row, then there
  259. is no reason to try any further.
  260.  
  261. **********************************************************************
  262.  
  263.                          RECOVERY
  264.  
  265. If the AcsTest program will not run, then it is possible that some
  266. partial data has been left in the INI files. The purpose of this
  267. section is to discuss the places where one might look to manually fix
  268. the INI files, so that AccessWPS will work correctly. The intention
  269. is to continue to improve AccessWPS so that the initialization and
  270. termination routines will be able to handle these conditions
  271. automatically. However, a number of different kinds of things could
  272. happen to change things at any one time, including a new release of
  273. OS/2.
  274.  
  275. This section is starting small, but will be added to as time goes on.
  276. The section also assumes that the developer has a tool, such as
  277. IniMaint, for searching and editing the INI files.
  278.  
  279. If AcsTest will not run all the way through without an error:
  280.  
  281. 1. The most common problem is an entry in the PM_Workplace:Location
  282. Application in the OS2.INI file. If you see a Key Name with
  283. <AccessWPSObject>, then there is residual information. You should
  284. manually remove this Key Name. Once this is done you should probably
  285. remove any invalid WPS entries in the OS2.INI and OS2SYS.INI files by
  286. using the Repair function of IniMaint or some similar program.
  287.  
  288. 2. The PM_Objects Application in the OS2SYS.INI file lists all of the
  289. registered classes. After AccessWPS has run successfully, there
  290. should not be any reference to a Class with the name AcsAgent. If
  291. there is, then the Class has not been deregistered. I have not tried to
  292. remove the AcsAgent information manually because it has not been
  293. necessary. Running AcsTest should remove the information, even if the
  294. Creation of the Class and/or the Object is not successful. AcsTest
  295. attempt to do the normal termination functions even if the creation
  296. functions were not successful and this will normally clean up this
  297. entry.
  298.  
  299. 3. If none of the above fix the problem, then the Find capability of
  300. IniMaint or some similar program should be used to search both the
  301. Key Names and the Key Values of both the OS2.INI and OS2SYS.INI files
  302. to look for instances of AccessWPSObject or AcsAgent. If any
  303. instances are found, then two things should be done. First, you
  304. should notify SofTouch Systems so that the condition you have found
  305. can be incorporated into this section of the documentation. Second,
  306. you should, after insuring that you have a backup of your Desktop,
  307. manually remove the information. If you are not sure about the effect
  308. of the manual removal, it is strongly suggested that you perform a
  309. Shutdown and a Reboot to insure that the contents of the INI files
  310. and WPS are current with each other.
  311.  
  312. **********************************************************************
  313.  
  314.                      SPECIAL AccessWPS API's
  315.  
  316. In order to accomplish all of the necessary functions, there is a set
  317. of AccessWPS API's that do not parallel a corresponding SOM or WPS
  318. API. They are as follows:
  319.  
  320. BOOL AcsInit()
  321.  
  322. Purpose: Initialize the AccessWPS Agent Class and Object.
  323.  
  324. Returns: 0     - No error
  325.          non 0 - Error, see error code list
  326. Notes:
  327.  
  328. 1. This API must be called as the first API call. If it is not called
  329. all of the other API's will return the Not Initialized error code.
  330.  
  331. **********************************************************************
  332.  
  333. BOOL AcsTerminate()
  334.  
  335. Purpose: Terminate the AccessWPS Agent Class and Object and free the
  336.          shared memory objects.
  337.  
  338. Returns: 0     - No error
  339.          non 0 - Error - error code will appear in a message box on screen
  340.  
  341. Notes:
  342.  
  343. 1. There is no way to check to verify that this API has been called
  344. before the PM Application terminates. If it is not called, the Agent
  345. Object will be left and the shared memory will be left allocated.
  346.  
  347. **********************************************************************
  348.  
  349. PVOID AcsHeapAlloc(ULONG ulLength)
  350.  
  351. Purpose: To allocate a memory block in the Heap that is shared
  352.          between the Agent Object's process and the user's process
  353.          so that both processes can use it.
  354.  
  355. Returns: Valid Pointer - Successful Completion
  356.          NULL Pointer  - Allocation Error - error code will appear in
  357.                                             a message box on screen
  358.  
  359. Parameters:
  360.  
  361. ulLength  - The size of the memory object requested.
  362.  
  363. **********************************************************************
  364.  
  365. BOOL AcsHeapFree(PVOID pvMemory)
  366.  
  367. Purpose: To allocate a memory block in the Heap that is shared
  368.          between the Agent Object's process and the user's process
  369.          so that both processes can use it.
  370.  
  371. Returns: NO_ERROR      - Successful Completion
  372.          Anything Else  - Error - see Error List
  373.  
  374. Parameters:
  375.  
  376.  
  377. **********************************************************************
  378.  
  379. PVOID AcsResolvePointer(PVOID pvWPS, LONG lFixed, BOOL fVariable)
  380.  
  381. Purpose: To make available to the PM process an area of memory that
  382.          belongs to the WPS process. This is normally a pointer that
  383.          has been returned from a call to a WPS or SOM method.
  384.  
  385. Returns: Valid Pointer - Successful Completion
  386.          NULL Pointer  - Error - see AcsReturnError API
  387.  
  388. Parameters:
  389.  
  390. pvWPS     - The pointer to the WPS memory area. This is normally a
  391.             pointer returned from a call to a WPS or SOM method.
  392.  
  393. lFixed    - The length of the fixed area pointed to by the pointer
  394.             above. See the notes below.
  395.  
  396. fVariable - A flag indicating whether or not there is a variable
  397.             component to the memory object. This must always be a
  398.             valid C string that is terminated with a NULL character.
  399.             TRUE  - There is a variable portion.
  400.             FALSE - There is not a variable portion.
  401.  
  402. Notes:
  403.  
  404. 1. Since the WPS memory object could be a structure entry whose
  405. length cannot be determined by using the string length API, all
  406. memory objects whose length is known, should be requested using the
  407. lFixed field to specify the length.
  408.  
  409. 2. If the WPS memory object is a variable length string, then the
  410. lFixed value must be zero.
  411.  
  412. 3. Many of the WPS structure entries are compound entries. There is a
  413. fixed portion followed by a variable length name field. These
  414. pointers should be resolved by passing a nonzero lFixed length and
  415. TRUE as the fVariable entry. In this case, it is assumed that the
  416. fixed portion is first and is immediately followed by the variable
  417. string portion.
  418.  
  419. 4. The returned pointer is one that is allocated using AcsHeapAlloc.
  420. It is the responsibility of the calling application to free this
  421. memory using AcsHeapFree. If the memory is not freed before the
  422. returned pointer is used for a different purpose, the memory will be
  423. orphaned until the PM application terminates. The advantage of using
  424. AcsHeapAlloc for the returned pointer is that the pointer can then be
  425. used to pass the memory on to another WPS method without further
  426. processing.
  427.  
  428. Examples:
  429.  
  430. For all of the examples below, it is assumed that the pointer
  431. pvNotMine has been returned from a call to a WPS or SOM method.
  432.  
  433. If pvNotMine points to a variable length string:
  434.  
  435. pvReturn = AcsResolvePointer(pvNotMine, 0, TRUE);
  436.  
  437. If pvNotMine points to a fixed length 30 byte structure entry:
  438.  
  439. pvReturn = AcsResolvePointer(pvNotMine, 30, FALSE);
  440.  
  441. If pvNotMine points to a fixed length 40 byte structure entry that
  442. is followed by a variable length string:
  443.  
  444. pvReturn = AcsResolvePointer(pvNotMine, 40, TRUE);
  445.  
  446. **********************************************************************
  447.  
  448. BOOL AcsReturnError()
  449.  
  450. Purpose: Initialize the AccessWPS Agent Class and Object.
  451.  
  452. Returns: 0     - No error
  453.          non 0 - Error, see error code list
  454. Notes:
  455.  
  456. 1. This API is provided so that the Acs Error code can be accessed in
  457. those situations where is cannot be returned directly by the Acs API,
  458. such as for the AcsResolvePointer API.
  459.  
  460. 2. This API will only return the internal AccessWPS Logic Error Code,
  461. there are two other possible error codes, the one returned from a
  462. call to a Control Program API, the DOS Error Code, and the error
  463. caused by a call to a PM API, the PM Error code. Whenever any error
  464. is encountered, all three error codes are preserved. The additional
  465. error codes can be obtained by calling the AcsDumpLine API, which
  466. will format the error information into normal text lines.
  467.  
  468. **********************************************************************
  469.  
  470. VOID AcsVersion(PCHAR pchDataLine)
  471.  
  472. Purpose: To get the version of both the AcsAgent.DLL and the
  473.          AccssWPS.DLL.
  474.  
  475. Parameters:
  476.  
  477. pchDataLine - Pointer to a memory area that is at least 255 bytes
  478.               long, the returned version information will be
  479.               placed in this area.
  480.  
  481.  
  482. **********************************************************************
  483.  
  484. BOOL AcsDumpLine(PCHAR pchDataLine)
  485.  
  486. Purpose: If an error is returned, this API provides for a method of
  487.          obtaining a series of ASCII Text lines of data that reflect
  488.          the contents of the internal variables used by both DLL's.
  489.  
  490. Returns: FALSE         - This is the last line of dump data
  491.          TRUE          - There are more lines of dump data, so the same
  492.                          routine needs to be called again
  493.          Anything Else - Error, see error code list
  494.  
  495. Parameters:
  496.  
  497. pchDataLine - Pointer to a memory area that is at least 255 bytes
  498.               long, the returned line of dump information will be
  499.               placed in this area.
  500.  
  501. Notes:
  502.  
  503. 1. Once this routine is called the first time, it should be called
  504. over and over until it no longer returns TRUE. If this is not done,
  505. then next time the routine is called, it will try to pick up where it
  506. left off and the results could be unpredictable.
  507.  
  508. **********************************************************************
  509.  
  510.                  INCORRECTLY DOCUMENTED METHODS
  511.  
  512. For the following methods the documentation and the *.h files do not
  513. agree. AccessWPS has been implemented to agree with the *.h files.
  514. Refer to the AccssWPS.h file for the detailed prototype for these
  515. methods.
  516.  
  517. SOMObject methods:
  518.  
  519. Acs_somInitClass - There is an additional parameter passed to this
  520. method as the 2nd parameter. It is a zString and is the name of the
  521. Class.
  522.  
  523. WPObject methods:
  524.  
  525. Acs_wpCnrRemoveObject - The third parameter is not present in the *.h
  526. file. This method is only passed the first two parameters.
  527.  
  528. Acs_wpclsFindObjectFirst - There is an additional parameter, a
  529. pointer to a Class List, which is the second parameter which must be
  530. passed to the method. This parameter is an array of pointers to the
  531. list of Classes that should be searched. The last pointer must be a
  532. NULL pointer, which indicates the end of the list. If the second
  533. parameter is a NULL, then all classes are returned.
  534.  
  535. Acs_wpAllocMem - The third parameter is a pointer to a long and will
  536. contain the return code...I think.
  537.  
  538. WPPalette methods:
  539.  
  540. Acs_wpPaintCell - There is an additional parameter that is passed as
  541. the third parameter, a Presentation space to be used for the Paint.
  542. Also there is no return from the method, it is defined as VOID.
  543.  
  544. WPFileSystem methods:
  545.  
  546. Acs_wpSetType - There is third parameter, which is a pointer to a
  547. FEA2LIST structure.
  548.  
  549. WPFolder methods:
  550.  
  551. Acs_wpPopulate - The third parameter is a pointer to a zero
  552. terminated string, not a pointer to a folder object.
  553.  
  554. **********************************************************************
  555.  
  556.                      UNPROTOTYPED METHODS
  557.  
  558. The following methods are defined in the Documentation as being
  559. available for use. However, they do not have a prototype defined for
  560. them in the *.h file, although they are listed in the method table.
  561. This normally means they are defined as private methods. Therefore,
  562. they are not implemented in AccessWPS.
  563.  
  564. SOMObject methods:
  565.  
  566. _somGetMethodOffset 
  567.  
  568. WPPalette methods:
  569.  
  570. _wpShowPalettePointer
  571.  
  572. The following methods are not prototyped in the *.h files, but are
  573. implemented in AccessWPS. Some are documented and some are not.
  574.  
  575. Undocumented methods:
  576.  
  577. WPObject Methods:
  578.  
  579. PSZ Acs_wpQueryObjectID(WPObject *somSelf)
  580.  
  581.    Returns a PSZ string that is the Object ID.
  582.  
  583. BOOL Acs_wpSetObjectID(WPObject *somSelf, PSZ pszObjectID)
  584.  
  585.    Returns a TRUE if Object ID is set
  586.  
  587. WPObject *Acs_wpQueryContainer(WPObject *somSelf)
  588.  
  589.    Returns the Folder that contains the Object
  590.  
  591. HWND Acs_wpViewObject(WPObject *somSelf, HWND hwndCnr, ULONG ulView, ULONG ulOptional)
  592.  
  593.    Returns Handle of Container and opens View of Object or surfaces existing 
  594.       view.
  595.  
  596. HOBJECT Acs_wpQueryHandle(WPObject *somSelf)
  597.  
  598.    Return persistant Handle of Object
  599.  
  600. WPFileSystem Methods:
  601.  
  602. BOOL Acs_wpPrintPlainTextFile(WPFileSystem *somSelf, PPRINTDEST pPrintDest)
  603.  
  604.    Returns TRUE if Ascii File is printed at Destination.
  605.  
  606. PSZ Acs_wpQueryFilename(WPFileSystem *somSelf, PSZ pszFileName, BOOL fQualified)
  607.  
  608.    Returns Filename in pszFileName Buffer, fully qualified if fQualified is 
  609.       TRUE and unqualified if fQualified is FALSE. pszFileName must be at 
  610.       least CCHMAXPATH
  611.  
  612. BOOL Acs_wpIsDeleteable(WPObject *somSelf)
  613.  
  614.    Returns TRUE if Object can be Deleted and FALSE if not
  615.  
  616. BOOL Acs_wpSetDefaultIconPos(WPObject *somSelf, PPOINTL pPoint)
  617.  
  618.    Returns TRUE if Object Icon Position is set
  619.  
  620. BOOL Acs_wpQueryDefaultIconPos(WPObject *somSelf, PPOINTL pPoint)
  621.  
  622.    Returns TRUE if Object Icon Position is found
  623.  
  624. MINIRECORDCORE Acs_wpQueryCoreRecord(WPObject *somSelf)
  625.  
  626.    Returns a Pointer to the Object MINIRECORDCORE
  627.  
  628. VOID Acs_wpCnrRefreshDetails(WPObject *somSelf)
  629.  
  630.    Refreshes all current visible RECORDCORE structures
  631.  
  632. WPObject * Acs_wpQueryContainer(WPObject *somSelf)
  633.  
  634.    Returns Folder that contains this Object
  635.  
  636. VOID Acs_wpLocKObject(WPObject *somSelf)
  637.  
  638.    Increments the Lock Count for an Object
  639.  
  640. BOOL Acs_wpIsLocked(WPObject *somSelf)
  641.  
  642.    Returns TRUE if Object is Locked
  643.  
  644. VOID Acs_wpclsDecUsage(M_WPObject *somSelf)
  645.  
  646.    Decrements the Class Usage Count
  647.  
  648. VOID Acs_wpclsIncUsage(M_WPObject *somSelf)
  649.  
  650.    Increments the Class Usage Count
  651.  
  652. BOOL Acs_wpclsSetSettingsPageSize(M_WPObject *somSelf, PSIZEL pSizl)
  653.  
  654.    Returns TRUE if Settings Page size is set
  655.  
  656. BOOL Acs_wpclsSetIconData(M_WPObject *somSelf, PICONINFO pIconInfo)
  657.  
  658.    Returns TRUE if Class Object Icon is set
  659.  
  660. BOOL Acs_wpclsSetIcon(M_WPObject *somSelf, HPOINTER hptrNewIcon)
  661.  
  662.    Returns TRUE if Class Object Icon Handle is set
  663.  
  664. WPDisk Methods:
  665.  
  666. BOOL Acs_wpSetCorrectDiskIcon(WPDisk *somSelf)
  667.  
  668.    Returns TRUE if Disk Object set its Correct Icon
  669.  
  670. WPFolder Methods
  671.  
  672. BOOL Acs_wpModifyFldrFlags(WPFolder *somSelf, ULONG ulFlags, ULONG ulFlagMask)
  673.  
  674.    This is basically a _wpQueryFolderFlags and a _wpSetFolderFlags as an 
  675.       atomic operation
  676.  
  677. BOOL Acs_wpAddToContent(WPFolder *somSelf)
  678.  
  679.    Returns TRUE if Object added to Folder's Content List
  680.  
  681. BOOL Acs_wpDeleteFromContent(WPFolder *somSelf)
  682.  
  683.    Returns TRUE if Object deleted from Folder's Content List
  684.  
  685. CHAR *Acs_wpQueryIconViewPos(WPFolder *somSelf)
  686.  
  687.    Returns Pointer to IconViewPos array: x, y, cx and cy as set by wpSetup
  688.  
  689. WPFolder *Acs_wpAddFirstChild(WPFolder *somSelf)
  690.  
  691.    Returns Pointer to instantiated Child Object.
  692.    Used in place of wpPopulate to add only one child so tree view has correct 
  693.       expansion emphasis
  694.  
  695. WPShadow Methods
  696.  
  697. BOOL Acs_wpSetLinkToObject(WPShadow *somSelf, WPObject * FromObject)
  698.  
  699.    Returns TRUE if Shadow is Linked to From Object
  700.  
  701. WPFontPallette Methods
  702.  
  703. VOID Acs_wpGetFattrsFromPsz(WPFontPallette *somSelf, PSZ pszFont, PFATTRS pFattrs)
  704.  
  705.    Gets a FATTRS Data structure from a PresParam string
  706.  
  707. Documented methods:
  708.  
  709. None.
  710.  
  711. **********************************************************************
  712.  
  713.                      NOT INCLUDED METHODS
  714.  
  715. The following methods are in the documentation and defined in the *.h
  716. files. However, they are not included in AccessWPS because they do
  717. not appear to be available to be called except by the System or
  718. during the processing of another method. If any developer believes
  719. there is a need for one of these methods, they can easily be included
  720. as part of AccessWPS.
  721.  
  722. SOMObject methods:
  723.  
  724. _somClassReady
  725. _somDispatchX
  726. _somEnvironmentNew
  727. _somPrintf
  728.  
  729. WPObject methods:
  730.  
  731. _wpAddObjectGeneralPage
  732. _wpAddObjectWindowPage
  733. _wpInsertPopupMenuItems
  734. _wpInsertSettingsPage
  735. _wpRestoreData
  736. _wpRestoreLong
  737. _wpRestoreString
  738. _wpSaveData
  739. _wpSaveLong
  740. _wpSaveString
  741.  
  742. WPDataFile methods:
  743.  
  744. _wpAddFileTypePage
  745.  
  746. WPDisk methods:
  747.  
  748. _wpAddDiskDetailsPage
  749.  
  750. WPDesk methods:
  751.  
  752. _wpAddDesktopLockup1Page
  753. _wpAddDesktopLockup2Page
  754. _wpAddDesktopLockup3Page
  755.  
  756. WPFileSystem methods:
  757.  
  758. _wpAddFile1Page
  759. _wpAddFile2Page
  760. _wpAddFile3Page
  761. _wpAddFileMenuPage
  762. _wpAddUserItemsToPopupMenu
  763.  
  764. WPFolder methods:
  765.  
  766. _wpAddFolderView1Page
  767. _wpAddFolderView2Page
  768. _wpAddFolderView3Page
  769. _wpAddFolderIncludePage
  770. _wpAddFolderSortPage
  771. _wpAddFolderBackgroundPage
  772.  
  773. WPProgram and WPProgramFile methods:
  774.  
  775. _wpAddProgramAssociationPage
  776. _wpAddProgramPage
  777. _wpAddProgramSessionPage
  778.  
  779. The following methods are not in the documentation but are defined in
  780. the *.h files. However, they are not included in AccessWPS because
  781. they do not appear to be available to be called except by the System
  782. or during the processing of another method. If any developer believes
  783. there is a need for one of these methods, they can easily be included
  784. as part of AccessWPS.
  785.  
  786. SOMObject methods:
  787.  
  788. _somTotalRegIds
  789. _somSetExpectedIds
  790. _somUniqueKey
  791. _somBeginPersistentIds
  792. _somEndPersistentIds
  793. _somConstructClass
  794. _somGenericApply
  795. _somVprintf
  796. _somPrefixLevel
  797. _somLPrintfsomLPrintf
  798. _somGetInstanceToken
  799. _somGetMemberToken
  800. _somGetInitFunction
  801. _somGetRelatedClasses
  802.  
  803. WPFolder methods:
  804.  
  805. _wpRestoreFldrRunObjs
  806. _wpStoreFldrRunObjs
  807.  
  808. **********************************************************************
  809.  
  810.                        MACRO METHODS
  811.  
  812. The following methods are documented as macros that start with SOM_.
  813. However, these methods are actually implemented via a normal method
  814. and are implemented in AccessWPS in the same way, that is, as normal
  815. Acs_som... methods
  816.  
  817. SOM_Resolve
  818. SOM_ResolveNoCheck
  819. SOM_ParentResolve
  820. SOM_CheckId
  821. SOM_CompareIds
  822. SOM_StringFromId
  823. SOM_IdFromString
  824.  
  825. **********************************************************************
  826.  
  827.                      UNDOCUMENTED METHODS
  828.  
  829. The following methods are present in the *.h files, but are not
  830. listed in the documentation. They are defined in all of the files, so
  831. they can be accessed via AccessWPS.
  832.  
  833. SOMObject methods:
  834.  
  835. Acs_somDataResolve
  836. Acs_somNewNoInit
  837. Acs_somRenewNoInit
  838. Acs_somGetMethodDescriptor
  839. Acs_somFindSMethod
  840. Acs_somFindSMethodOk
  841.  
  842. WPObject methods:
  843.  
  844. Acs_wpAppendObject
  845. Acs_wpAssertObjectMutexSem
  846. Acs_wpConfirmObjectTitle
  847.    Returns results of Object Title Confirm Dialog:
  848.       NAMECLASH_RENAME           - Object to be Renamed
  849.       NAMECLASH_APPEND           - Object to be Appended to
  850.       NAMECLASH_REPLACE          - Object to be Replaced
  851.       NAMECLASH_NONE             - Object not Duplicated
  852.       NAMECLASH_RENAME_KEPPASSOC - 
  853.       NAMECLASH_NONE_KEPPASSOC   - 
  854. Acs_wpCreateAnother
  855.    Returns Pointer to new Object
  856. Acs_wpFindTaskRec
  857. Acs_wpModifyStyle
  858.    Returns TRUE if successful.
  859.    ULONG Style Mask set to TRUE to Setting and FALSE if Clearing
  860. Acs_wpQueryButtonAppearance
  861.    Return Frame Control Button Appearance
  862.       MINBUTTON
  863.       MAXBUTTON
  864.       DEFAULTBUTTON
  865. Acs_wpQueryConcurrentView
  866.    Returns Concurrent View behavior
  867.       CCVIEW_ON
  868.       CCVIEW_OFF
  869.       CCVIEW_DEFAULT - System Default
  870. Acs_wpQueryMinWindow
  871.    Returns Minimized Window behavior
  872.       MINWIN_DEFAULT - System Default
  873.       MINWIN_HIDDEN  - Hide Window
  874.       MINWIN_VIEWER  - Place in Viewer
  875.       MINWIN_DESKTOP - Place on Desktop
  876. Acs_wpQueryNameClashOptions
  877.    Returns Options not available in Name Clash Dialog
  878.       NO_NAMECLASH_RENAME  - Renames not allowed
  879.       NO_NAMECLASH_DIALOG  - Do not show Dialog
  880.       NO_NAMECLASH_APPEND  - Appends not allowed
  881.       NO_NAMECLASH_REPLACE - Replacements not allowed
  882. Acs_wpQueryTrueStyle
  883. Acs_wpReleaseObjectMutexSem
  884. Acs_wpReplaceObject
  885. Acs_wpRequestObjectMutexSem
  886. Acs_wpSetButtonAppearance
  887.       MINBUTTON
  888.       MAXBUTTON
  889.       DEFAULTBUTTON
  890. Acs_wpSetConcurrentView
  891.       CCVIEW_ON
  892.       CCVIEW_OFF
  893.       CCVIEW_DEFAULT - System Default
  894. Acs_wpSetMinWindow
  895.       MINWIN_DEFAULT - System Default
  896.       MINWIN_HIDDEN  - Hide Window
  897.       MINWIN_VIEWER  - Place in Viewer
  898.       MINWIN_DESKTOP - Place on Desktop
  899. Acs_wpSetTaskRec
  900. Acs_wpViewObject
  901. Acs_wpclsQueryButtonAppearance
  902. Acs_wpclsQueryExtendedCriteria
  903. Acs_wpclsQuerySearchInfo
  904.  
  905. WPDataFile methods:
  906.  
  907. Acs_wpQueryAssociatedProgram
  908. Acs_wpSetAssociatedFileIcon
  909.  
  910. WPDisk methods:
  911.  
  912. Acs_wpQueryDriveLockStatus
  913.    Returns the Number of Locks against the drive
  914. Acs_wpEjectDisk
  915.    Returns 0 if disk is ejected and DOS error if not
  916. Acs_wpLockDrive
  917.    Returns 0 if successful DOS error if not
  918.    BOOL Parameter TRUE increments locks and FALSE decrements locks
  919.  
  920. WPFileSystem methods:
  921.  
  922. Acs_wpConfirmRenameFileWithExt
  923. Acs_wpQueryAttr
  924.    Returns File Attributes
  925. Acs_wpQueryCreation
  926.    Returns 0 if FDATE and FTIME Filled
  927. Acs_wpQueryLastAccess
  928.    Returns 0 if FDATE and FTIME Filled
  929. Acs_wpQueryLastWrite
  930.    Returns 0 if FDATE and FTIME Filled
  931. Acs_wpQueryFileSize
  932.    Returns File Size
  933. Acs_wpQueryEASize
  934.    Returns EA Size
  935. Acs_wpQueryRefreshFlags
  936. Acs_wpSetAttr
  937.    Returns TRUE if Attrs set
  938. Acs_wpSetDateInfo
  939.    Returns 0 if successful DOS error if not
  940. Acs_wpSetFileSizeInfo
  941.    Returns 0 if successful DOS error if not
  942. Acs_wpSetRefreshFlags
  943. Acs_wpSetTitleAndRenameFile
  944. Acs_wpVerifyUpdateAccess
  945. Acs_wpclsQueryObjectFromPath
  946.    Returns Pointer to Object represented by Path
  947.  
  948. WPFolder methods:
  949.  
  950. Acs_wpContainsFolders
  951.    Returns TRUE is Folder Contains subfolders
  952. Acs_wpFreeIconPosData
  953. Acs_wpInitIconPosData
  954. Acs_wpQueryFldrSort
  955. Acs_wpQueryIconPosition
  956. Acs_wpQueryOpenFolders
  957.    Returns Open Folders
  958.    ULONG of QC_FIRST is first Folder, QC_NEXT is next Folder
  959. Acs_wpSearchFolder
  960. Acs_wpSetFldrSort
  961. Acs_wpStoreIconPosData
  962.  
  963. **********************************************************************
  964.  
  965.                      AccessWPS ERROR CODES
  966.  
  967. 10100 - Initialization cannot create Object.
  968.  
  969. 10101 - Creation of Shared Heap failed.
  970.  
  971. 10102 - Creation of Shared Information Structure failed.
  972.  
  973. 10103 - Agent Object Window Pointer NULL.
  974.  
  975. 10104 - Free of Shared Heap failed.
  976.  
  977. 10105 - Free of Shared Information Structure failed.
  978.  
  979. 10106 - DosAllocMem failed.
  980.  
  981. 10107 - Null pointer passed to AcsResolvePointer.
  982.  
  983. 10108 - Agent Object not active.
  984.  
  985. 10109 - Semaphore Handling error.
  986.  
  987. 10110 - Dump API was passed a NULL Pointer.
  988.  
  989. 10111 - The AccessWPS Agent already exists or partially exists.
  990.  
  991. 10200 - Registration of Agent Class failed.
  992.  
  993. 10201 - Creation of Agent Object failed.
  994.  
  995. 10202 - Removal of Agent Object failed.
  996.  
  997. 10203 - Unable to Post Message to Agent Object Window.
  998.  
  999. 10204 - Error posting or waiting on Semaphore
  1000.  
  1001. 10205 - Null pointer passed to AcsDumpLine.
  1002.  
  1003. 10206 - Reserved.
  1004.  
  1005. 10207 - Reserved.
  1006.  
  1007. 10208 - Unknown AccessWPS error.
  1008.  
  1009. 10209 - AccessWPS Agent Object is not Active.
  1010.  
  1011. 10210 - Shared Heap has become Corrupted.
  1012.  
  1013. 10211 - Memory is Corrupted.
  1014.  
  1015. 20100 - Creation of Shared Heap failed.
  1016.  
  1017. 20101 - Creation of Shared Information Structure failed.
  1018.  
  1019. 20102 - Semaphore Handling error.
  1020.  
  1021. 20103 - Free of Shared Heap failed.
  1022.  
  1023. 20200 - Agent Class Creation Failed
  1024.  
  1025. 20201 - Agent Object Creation Failed.
  1026.  
  1027. 20202 - Reserved.
  1028.  
  1029. 20203 - Reserved.
  1030.  
  1031. 20204 - Reserved.
  1032.  
  1033. 20205 - Freeing of Shared Heap Memory Failed.
  1034.  
  1035. 20206 - Reserved.
  1036.  
  1037. 20207 - Reserved.
  1038.  
  1039. 20208 - Allocation of Shared Heap Memory Failed.
  1040.  
  1041. 20209 - Reserved.
  1042.  
  1043. 20210 - Semaphore Handling error.
  1044.