home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / wps / system / inimaint / accsswps.txt next >
Encoding:
Text File  |  1994-03-21  |  30.8 KB  |  865 lines
  1.  
  2.  
  3.                        ACCESS WPS INFORMATION
  4.  
  5.                          GENERAL DESCRIPTION
  6.  
  7. AccessWPS is a set of files that allow any PM program to access any
  8. WPS method, that can be legally used by a WPS application. 
  9.  
  10. AccessWPS has been developed by Carry Associates, 990 Ironwood Court,
  11. Marco Island, FL 33937. Our phone number is 813-642-9126 and the fax
  12. number is 813-642-1007. We are on Compuserve virtually everyday and
  13. our Compuserve ID is 72662,3616. If you have any questions or
  14. problems with this application, you should contact Carry Associates.
  15.  
  16. Normally, any developer that needs to use one of the methods of a WPS
  17. Object must use the SOM Compiler to develop their own WPS Object and
  18. then use that Object to actually call one of the WPS Object methods.
  19. The reason for this is that WPS runs as a separate process and it is
  20. only possible to call one of the WPS methods while running as part of
  21. the WPS process. The only way to run as part of the WPS process is to
  22. create a WPS Object.
  23.  
  24. AccessWPS solves this problem by creating a general purpose WPS Agent
  25. Object that can call any WPS Object method. The Agent Object can be
  26. invoked from any PM program by calling an API that is exactly the
  27. same as the WPS or SOM method, except that 'Acs' is appended to the
  28. front of the method name. For example, _somInit is called via
  29. AccessWPS by calling the Acs_somInit API. All of the 'Acs' API's
  30. return the exact same return as the corresponding WPS or SOM method,
  31. so it is as if it was possible to call the method directly from the
  32. PM application.
  33.  
  34.                      THE PROBLEM WITH POINTERS
  35.  
  36. The biggest with a general purpose WPS Agent concerns the area of
  37. pointers to various memory objects. Since WPS runs as a separate
  38. process, it cannot access any memory that belongs to the calling
  39. process and the calling process cannot access and memory that belongs
  40. to the WPS process. Therefore, a mechanism must be provided to
  41. address this problem.
  42.  
  43. Any developer using AccessWPS must be aware of 'hidden' pointers that
  44. are not obvious because the are hidden by some of the typedefs in the
  45. SOM and WPS header files. An example of this is the somId type. If
  46. you review the somtypes.h file, you will see that somId is actually a
  47. pointer to a pointer to the name of a Class or Object. What this
  48. means is that the developer must be careful to place the actual
  49. string pointed to in the shared memory area, see discussion below,
  50. before calling any of the SOM or WPS methods that use the somId data
  51. type. Failure to do this will result in either a NULL return from a
  52. method or, and worse, a protection violation in the WPS process.
  53.  
  54. AccessWPS provides two API's, AcsHeapAlloc and AcsHeapFree, which
  55. resolve the problem of how to pass memory objects to WPS. These two
  56. API's will allocate memory in a dynamically allocated memory pool
  57. that is shared between the WPS process and the user's process. This
  58. memory pool is allocated during the processing of the AcsInit API and
  59. is deleted during the processing of the AcsTerminate API. It is the
  60. responsibility of the developer that is using AccessWPS to insure
  61. that every pointer passed to WPS is a pointer that was returned by a
  62. call to the AcsHeapAlloc API. For example, to pass a string to WPS it
  63. is necessary to:
  64.  
  65. 1. Use AcsHeapAlloc to get a memory block that equals the length of
  66. the string plus one byte for the null character.
  67.  
  68. 2. Copy the string to the memory allocated via AcsHeapAlloc.
  69.  
  70. The above would also apply to any structure which is passed to WPS or
  71. a pointer that is passed and is pointing to an area that will contain
  72. returned information, this is done a lot with the _wpQuery type
  73. methods.
  74.  
  75. If a pointer to a structure is passed, after copying the structure to
  76. the memory block returned by AcsHeapAlloc, and the structure contains
  77. a pointer to another memory object or structure, the embedded pointer
  78. must also point to a memory block returned via AcsHeapAlloc.
  79.  
  80. Once the API call is complete, it is the responsibility of the
  81. developer to release any memory obtained via AcsHeapAlloc via the
  82. AcsHeapFree API. This memory should be treated more like stack space
  83. that as a heap. In other words, any memory obtained via AcsHeapAlloc
  84. should be returned via AcsHeapFree as quickly as possible.
  85.  
  86. The other memory problem concerns pointers that are returned as a
  87. result of calling one of the WPS methods.  It is possible that the
  88. returned value will be a pointer to memory that is allocated to the
  89. WPS process. This pointer cannot be used by the PM Application to
  90. access the memory object that is being pointed to, since the PM
  91. Application cannot access memory that belongs to a different process.
  92. The call to the 'Acs' API makes no attempt to resolve this problem.
  93. The reason no attempt is made is because it will often be the case
  94. that the returned pointer is only going to be used in a subsequent
  95. call to another WPS or SOM method, and the PM Application has no need
  96. to access the actual memory pointed to.  However, there are cases
  97. where the PM application needs access to the memory pointed to so an
  98. API has been provided, AcsResolvePointer, that will return a pointer
  99. to a memory object that can be used by the PM process that is a copy
  100. of the same memory in the WPS process. This memory object is
  101. allocated via DosAllocMem and it is the responsibility of the callin
  102. application to free the memory via DosFreeMem.
  103.  
  104. **********************************************************************
  105.  
  106.                         API PROCESSING FLOW
  107.  
  108. AccessWPS actually runs as two DLL's. One of the DLL's, AccssWPS.DLL
  109. runs as part of the user's process. The second DLL, AcsAgentDLL, runs
  110. as part of the WPS process. 
  111.  
  112. Before any WPS or SOM method can be called, the AccessWPS Agent
  113. Object must be created via the AcsIniT API call. This API will cause
  114. the Agent Class to be registered with WPS, will create an instance of
  115. the AccessWPS Object and the Agent Object will open an Object Window
  116. which will be used by both DLL's to communicate with each other. In
  117. addition, some shared memory areas and semaphores are created by the
  118. AccssWPS.DLL and the AcsAgent.DLL will get a pointer to these areas
  119. by using their names.
  120.  
  121. Once all processing is completed, the PM Application must issue the
  122. AcsTerminate API. This API will destroy the AcsAgent Object,
  123. unregister the AccessWPS class and free the shared memory objects and
  124. semaphores.
  125.  
  126. The actual processing flow for each WPS or SOM method is as follows:
  127.  
  128. 1. The call of the 'Acs' API actually calls a subroutine for that
  129. specific method in the AccssWPS.DLL.
  130.  
  131. 2. The AccssWPS.DLL routine will allocate shared memory to hold the
  132. passed parameters and the return and fill in the parameters to be
  133. passed to the WPS or SOM method. In addition, any API that requires
  134. the SOMClassManager object ID as one of the parameters will check
  135. this parameter for a NULL and, if a NULL is found, will substitute
  136. the actual SOMClassManager value. This is necessary because it is not
  137. possible to access this constant value except when running as part of
  138. the WPS process.
  139.  
  140. 3. Once the shared memory is filled, the AccssWPS.DLL file will post a
  141. message to the AcsAgent Object Window and then wait on an Event
  142. Semaphore.
  143.  
  144. 4. When the AcsAgent.DLL Object Window receives the message, it will
  145. call a routine that will actually invoke the requested method and put
  146. the value returned from the method, if there is one, in the
  147. appropriate place in the shared memory.
  148.  
  149. 5. The AcsAgent.DLL code will then post the Event Semaphore.
  150.  
  151. 6. The posting of the Event Semaphore will cause the AccssWPS.DLL
  152. code to fall through the Wait.
  153.  
  154. 7. The AccssWPS.DLL code will save the returned value, if there is
  155. any, free the shared memory allocated for this API call and return to
  156. the calling PM application.
  157.  
  158. **********************************************************************
  159.  
  160.                         INSTALLATION
  161.  
  162. AccessWPS consists of three DLL's, an Import Library, an Include
  163. file and a Test program.
  164.  
  165. The two of the three DLL's must be copied into a directory that is in
  166. the LIBPATH for the PM Application that will use them, the third
  167. AcsAgent.DLL must be in a directory that is specifically listed in
  168. the LIBPATH. Normally, the
  169. LIBPATH environment variable starts with '.;' which instructs OS/2 to
  170. look in the current directory for the DLL before looking in the other
  171. directories. This means that it is normally just fine to put the DLLs
  172. in the default directory when running an application that uses DLL's.
  173. However, this is not the case with the AcsAgent.DLL file of
  174. AccessWPS. This DLL is the file that implements the WPS Agent Class
  175. and is loaded by WPS, not your application. Therefore, both your app
  176. and the Installation test below will fail if this DLL is not in a
  177. directory that is specifically listed in the LIBPATH environment
  178. 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 preceed 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. preceed it. If none of these files preceed 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 worht 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 faliing 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 be Deregistered. I have not tried to
  292. remove the AcsAgent information manually becuace 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 Carry Associates 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.          Anthing 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 claa 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 non-zero 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 second 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. _wpQueryObjectID - Method accepts a single parameter, which is a
  580.                    WPObject pointer pointing to the Object and
  581.                    returns a PSZ string that is the Object ID.
  582.  
  583. Documented methods:
  584.  
  585. None.
  586.  
  587. **********************************************************************
  588.  
  589.                      NOT INCLUDED METHODS
  590.  
  591. The following methods are in the documentation and defined in the *.h
  592. files. However, they are not included in AccessWPS because they do
  593. not appear to be available to be called except by the System or
  594. during the processing of another method. If any developer believes
  595. there is a need for one of these methods, they can easily be included
  596. as part of AccessWPS.
  597.  
  598. SOMObject methods:
  599.  
  600. _somClassReady
  601. _somDispatchX
  602. _somEnvironmentNew
  603. _somPrintf
  604.  
  605. WPObject methods:
  606.  
  607. _wpAddObjectGeneralPage
  608. _wpAddObjectWindowPage
  609. _wpInsertPopupMenuItems
  610. _wpInsertSettingsPage
  611. _wpRestoreData
  612. _wpRestoreLong
  613. _wpRestoreString
  614. _wpSaveData
  615. _wpSaveLong
  616. _wpSaveString
  617.  
  618. WPDataFile methods:
  619.  
  620. _wpAddFileTypePage
  621.  
  622. WPDisk methods:
  623.  
  624. _wpAddDiskDetailsPage
  625.  
  626. WPDesk methods:
  627.  
  628. _wpAddDesktopLockup1Page
  629. _wpAddDesktopLockup2Page
  630. _wpAddDesktopLockup3Page
  631.  
  632. WPFileSystem methods:
  633.  
  634. _wpAddFile1Page
  635. _wpAddFile2Page
  636. _wpAddFile3Page
  637. _wpAddFileMenuPage
  638. _wpAddUserItemsToPopupMenu
  639.  
  640. WPFolder methods:
  641.  
  642. _wpAddFolderView1Page
  643. _wpAddFolderView2Page
  644. _wpAddFolderView3Page
  645. _wpAddFolderIncludePage
  646. _wpAddFolderSortPage
  647. _wpAddFolderBackgroundPage
  648.  
  649. WPProgram and WPProgramFile methods:
  650.  
  651. _wpAddProgramAssociationPage
  652. _wpAddProgramPage
  653. _wpAddProgramSessionPage
  654.  
  655. The following methods are not in the documentation but are defined in
  656. the *.h files. However, they are not included in AccessWPS because
  657. they do not appear to be available to be called except by the System
  658. or during the processing of another method. If any developer believes
  659. there is a need for one of these methods, they can easily be included
  660. as part of AccessWPS.
  661.  
  662. SOMObject methods:
  663.  
  664. _somTotalRegIds
  665. _somSetExpectedIds
  666. _somUniqueKey
  667. _somBeginPersistentIds
  668. _somEndPersistentIds
  669. _somConstructClass
  670. _somGenericApply
  671. _somVprintf
  672. _somPrefixLevel
  673. _somLPrintfsomLPrintf
  674. _somGetInstanceToken
  675. _somGetMemberToken
  676. _somGetInitFunction
  677. _somGetRelatedClasses
  678.  
  679. WPFolder methods:
  680.  
  681. _wpRestoreFldrRunObjs
  682. _wpStoreFldrRunObjs
  683.  
  684. **********************************************************************
  685.  
  686.                        MACRO METHODS
  687.  
  688. The following methods are documented as macros that start with SOM_.
  689. However, these methods are actually implemented via a normal method
  690. and are implemented in AccessWPS in the same way, that is, as normal
  691. Acs_som... methods
  692.  
  693. SOM_Resolve
  694. SOM_ResolveNoCheck
  695. SOM_ParentResolve
  696. SOM_CheckId
  697. SOM_CompareIds
  698. SOM_StringFromId
  699. SOM_IdFromString
  700.  
  701. **********************************************************************
  702.  
  703.                      UNDOCUMENTED METHODS
  704.  
  705. The following methods are present in the *.h files, but are not
  706. listed in the documentation. They are defined in all of the files, so
  707. they can be accessed via AccessWPS.
  708.  
  709. SOMObject methods:
  710.  
  711. Acs_somDataResolve
  712. Acs_somNewNoInit
  713. Acs_somRenewNoInit
  714. Acs_somGetMethodDescriptor
  715. Acs_somFindSMethod
  716. Acs_somFindSMethodOk
  717.  
  718. WPObject methods:
  719.  
  720. Acs_wpAppendObject
  721. Acs_wpAssertObjectMutexSem
  722. Acs_wpConfirmObjectTitle
  723. Acs_wpCreateAnother
  724. Acs_wpFindTaskRec
  725. Acs_wpModifyStyle
  726. Acs_wpQueryButtonAppearance
  727. Acs_wpQueryConcurrentView
  728. Acs_wpQueryMinWindow
  729. Acs_wpQueryNameClashOptions
  730. Acs_wpQueryTrueStyle
  731. Acs_wpReleaseObjectMutexSem
  732. Acs_wpReplaceObject
  733. Acs_wpRequestObjectMutexSem
  734. Acs_wpSetButtonAppearance
  735. Acs_wpSetConcurrentView
  736. Acs_wpSetMinWindow
  737. Acs_wpSetTaskRec
  738. Acs_wpViewObject
  739. Acs_wpclsQueryButtonAppearance
  740. Acs_wpclsQueryExtendedCriteria
  741. Acs_wpclsQuerySearchInfo
  742.  
  743. WPDataFile methods:
  744.  
  745. Acs_wpQueryAssociatedProgram
  746. Acs_wpSetAssociatedFileIcon
  747.  
  748. WPDisk methods:
  749.  
  750. Acs_wpQueryDriveLockStatus
  751. Acs_wpEjectDisk
  752. Acs_wpLockDrive
  753.  
  754. WPFileSystem methods:
  755.  
  756. Acs_wpConfirmRenameFileWithExt
  757. Acs_wpQueryAttr
  758. Acs_wpQueryCreation
  759. Acs_wpQueryLastAccess
  760. Acs_wpQueryLastWrite
  761. Acs_wpQueryFileSize
  762. Acs_wpQueryEASize
  763. Acs_wpQueryRefreshFlags
  764. Acs_wpSetAttr
  765. Acs_wpSetDateInfo
  766. Acs_wpSetFileSizeInfo
  767. Acs_wpSetRefreshFlags
  768. Acs_wpSetTitleAndRenameFile
  769. Acs_wpVerifyUpdateAccess
  770. Acs_wpclsQueryObjectFromPath
  771.  
  772. WPFolder methods:
  773.  
  774. Acs_wpContainsFolders
  775. Acs_wpFreeIconPosData
  776. Acs_wpInitIconPosData
  777. Acs_wpQueryFldrSort
  778. Acs_wpQueryIconPosition
  779. Acs_wpQueryOpenFolders
  780. Acs_wpSearchFolder
  781. Acs_wpSetFldrSort
  782. Acs_wpStoreIconPosData
  783.  
  784. **********************************************************************
  785.  
  786.                      AccessWPS ERROR CODES
  787.  
  788. 10100 - Initialization cannot create Object.
  789.  
  790. 10101 - Creation of Shared Heap failed.
  791.  
  792. 10102 - Creation of Shared Information Structure failed.
  793.  
  794. 10103 - Agent Object Window Pointer NULL.
  795.  
  796. 10104 - Free of Shared Heap failed.
  797.  
  798. 10105 - Free of Shared Information Structure failed.
  799.  
  800. 10106 - DosAllocMem failed.
  801.  
  802. 10107 - Null pointer passed to AcsResolvePointer.
  803.  
  804. 10108 - Agent Object not active.
  805.  
  806. 10109 - Semaphore Handling error.
  807.  
  808. 10110 - Dump API was passed a NULL Pointer.
  809.  
  810. 10111 - The AccessWPS Agent already exists or partially exists.
  811.  
  812. 10200 - Registration of Agent Class failed.
  813.  
  814. 10201 - Creation of Agent Object failed.
  815.  
  816. 10202 - Removal of Agent Object failed.
  817.  
  818. 10203 - Unable to Post Message to Agent Object Window.
  819.  
  820. 10204 - Error posting or waiting on Semaphore
  821.  
  822. 10205 - Null pointer passed to AcsDumpLine.
  823.  
  824. 10206 - Reserved.
  825.  
  826. 10207 - Reserved.
  827.  
  828. 10208 - Unknown AccessWPS error.
  829.  
  830. 10209 - AccessWPS Agent Object is not Active.
  831.  
  832. 10210 - Shared Heap has become Corrupted.
  833.  
  834. 10211 - Memory is Corrupted.
  835.  
  836. 20100 - Creation of Shared Heap failed.
  837.  
  838. 20101 - Creation of Shared Information Structure failed.
  839.  
  840. 20102 - Semaphore Handling error.
  841.  
  842. 20103 - Free of Shared Heap failed.
  843.  
  844. 20200 - Agent Class Creation Failed
  845.  
  846. 20201 - Agent Object Creation Failed.
  847.  
  848. 20202 - Reserved.
  849.  
  850. 20203 - Reserved.
  851.  
  852. 20204 - Reserved.
  853.  
  854. 20205 - Freeing of Shared Heap Memory Failed.
  855.  
  856. 20206 - Reserved.
  857.  
  858. 20207 - Reserved.
  859.  
  860. 20208 - Allocation of Shared Heap Memory Failed.
  861.  
  862. 20209 - Reserved.
  863.  
  864. 20210 - Semaphore Handling error.
  865.