home *** CD-ROM | disk | FTP | other *** search
/ PC Press 1997 July / Sezamfile97_2.iso / windows / program / activex / axtsamp.exe / TSBRANCH.EXE / STOSERVE / STOSERVE.TXT < prev   
Text File  |  1997-01-05  |  7KB  |  130 lines
  1.  
  2. STOSERVE - Structured Storage in an in-process server
  3.  
  4.  
  5. SUMMARY
  6. =======
  7.  
  8. The STOSERVE sample introduces the COPaper COM object, which models a
  9. sheet of white drawing paper. COPaper objects expose a set of features for
  10. free-form drawing on the paper surface using "ink" of specified color and
  11. width. The functionality is outwardly similar to other "scribble" C++
  12. tutorial samples. The difference in the STOSERVE/STOCLIEN samples is an
  13. architecture based primarily on COM technology. The electronic drawing
  14. paper features of COPaper objects are available to clients through a
  15. custom IPaper interface. COPaper implements the IPaper interface. A clear
  16. architectural distinction is kept between client and server. No graphical
  17. user interface (GUI) is provided by COPaper. The design of the COPaper
  18. object relies on the client for all GUI behavior. COPaper encapsulates
  19. only the server-based capture and storage of the drawn ink data.
  20.  
  21. The ink data that is drawn on the COPaper surface can be stored in and
  22. loaded from COM compound files. The IPaper Save and Load methods accept an
  23. IStorage interface pointer. COPaper uses this client-provided IStorage
  24. interface to store the drawing data.
  25.  
  26. The primary focus of this code sample is on the use of COM structured
  27. storage services as provided in the COM compound files implementation.
  28. STOSERVE works with the STOCLIEN code sample to illustrate the joint use
  29. of compound file storage by client and server.
  30.  
  31. COPaper is housed in an in-process server and is made publicly available
  32. as a custom COM component. Like all other servers in this tutorial series,
  33. STOSERVE is a self-registering COM server. It makes the COPaper object
  34. type available to clients as the DllPaper component using a
  35. CLSID_DllPaper registration in the Registry.
  36.  
  37. As was the case in the previous CONSERVE server, connectable object
  38. features are supported in COPaper. The IConnectionPointContainer interface
  39. is exposed, and an appropriate connection point is implemented. In this
  40. context, an outgoing custom IPaperSink interface is declared for use in
  41. sending notifications to the client.
  42.  
  43. The two IPaper and IPaperSink custom interfaces are declared in IPAPER.H
  44. located in the common sibling \INC directory. The GUIDs for the interfaces
  45. and objects are defined in PAPGUIDS.H located in that same common include
  46. directory.
  47.  
  48. The CThreaded facility in APPUTIL is used by STOSERVE to achieve thread
  49. safety, as it was in the FRESERVE sample. COPaper objects are derived from
  50. the CThreaded class and inherit its OwnThis and UnOwnThis methods. These
  51. methods allow only one thread at a time to have access to the STOSERVE
  52. server and to COPaper objects managed by the server.
  53.  
  54. For functional descriptions and a tutorial code tour of STOSERVE, see the
  55. Code Tour section in STOSERVE.HTM. For details on setting up the
  56. programmatic usage of STOSERVE, see the Usage section in STOSERVE.HTM. To
  57. read STOSERVE.HTM, run TUTORIAL.EXE in the main tutorial directory and
  58. click the STOSERVE lesson in the table of lessons. You can also achieve
  59. the same thing by clicking the STOSERVE.HTM file after locating the main
  60. tutorial directory in the Windows Explorer. See also STOCLIEN.HTM in the
  61. main tutorial directory for more details on the STOCLIEN client
  62. application and how it works with STOSERVE.DLL. You must build
  63. STOSERVE.DLL before building or running STOCLIEN.
  64.  
  65. STOSERVE's makefile automatically registers STOSERVE's DllPaper COM
  66. component in the registry. This component must be registered before
  67. STOSERVE is available to outside COM clients as a server for that
  68. component. This self-registration is done using the REGISTER.EXE utility
  69. built in the REGISTER sample. To build or run STOSERVE, you should build
  70. the REGISTER code sample first.
  71.  
  72. For details on setting up your system to build and test the code samples
  73. in this ActiveX Tutorial series, see TUTORIAL.HTM. The supplied MAKEFILE
  74. is Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE
  75. command in the Command Prompt window.
  76.  
  77. Usage
  78. -----
  79.  
  80. STOSERVE is a DLL that is intended primarily as a COM server. Although it
  81. can be implicitly loaded by linking to its associated .LIB file, it is
  82. normally used after an explicit LoadLibrary call, usually from within the
  83. COM function CoGetClassObject. STOSERVE is a self-registering in-process
  84. server. The makefile that builds this sample automatically registers this
  85. server in the registry. You can manually initiate its self-registration by
  86. issuing the following command at the command prompt:
  87.  
  88.   nmake register
  89.  
  90. You can also directly invoke the REGISTER.EXE command at the command prompt
  91. while in the STOSERVE directory.
  92.  
  93.   ..\register\register.exe stoserve.dll
  94.  
  95. These registration commands require a prior build of the REGISTER sample
  96. in this series, as well as a prior build of STOSERVE.DLL.
  97.  
  98. To use STOSERVE, a client program does not need to include STOSERVE.H or
  99. link to STOSERVE.LIB. A COM client of STOSERVE obtains access solely
  100. through its object's CLSID and COM services. For STOSERVE, that CLSID is
  101. CLSID_DllPaper (defined in file PAPGUIDS.H in the \INC sibling directory).
  102. The STOCLIEN code sample shows how the client obtains this access.
  103.  
  104.  
  105. FILES
  106. =====
  107.  
  108. Files         Description
  109.  
  110. STOSERVE.TXT  This file.
  111. MAKEFILE      The generic makefile for building the STOSERVE.DLL
  112.               code sample of this lesson.
  113. STOSERVE.H    The include file for declaring as imported or defining as
  114.               exported the service functions in STOSERVE.DLL.
  115. STOSERVE.CPP  The main implementation file for STOSERVE.DLL. Has DllMain
  116.               and the COM server functions (for example, DllGetClassObject).
  117. STOSERVE.RC   The DLL resource definition file for the executable.
  118. STOSERVE.ICO  The icon resource for the executable.
  119. SERVER.H      The include file for the server control C++ object.
  120. SERVER.CPP    The implementation file for the server control C++ object.
  121. FACTORY.H     The include file for the server's class factory COM objects.
  122. FACTORY.CPP   The implementation file for the server's class factories.
  123. CONNECT.H     The include file for the connection point enumerator,
  124.               connection point, and connection enumerator classes.
  125. CONNECT.CPP   The implementation file for the connection point enumerator,
  126.               connection point, and connection enumerators objects.
  127. PAPER.H       The include file for the COPaper COM object class.
  128. PAPER.CPP     The implementation file for the COPaper COM object class
  129.               and the connection points.
  130.