home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / com / tutsamp / stoserve / stoserve.txt < prev   
Encoding:
Text File  |  1997-08-05  |  6.9 KB  |  139 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. The
  28. use of the standard IStorage and IStream interfaces is covered. STOSERVE
  29. works with the STOCLIEN code sample to illustrate the joint use of
  30. compound file storage by client and server.
  31.  
  32. COPaper is housed in an in-process server and is made publicly available
  33. as a custom COM component. Like all other servers in this tutorial series,
  34. STOSERVE is a self-registering COM server. It makes the COPaper object
  35. type available to clients as the DllPaper component using a
  36. CLSID_DllPaper registration in the Registry.
  37.  
  38. As was the case in the previous CONSERVE server, connectable object
  39. features are supported in COPaper. The IConnectionPointContainer interface
  40. is exposed, and an appropriate connection point is implemented. In this
  41. context, an outgoing custom IPaperSink interface is declared for use in
  42. sending notifications to the client.
  43.  
  44. The two IPaper and IPaperSink custom interfaces are declared in IPAPER.H
  45. located in the common sibling \INC directory. The GUIDs for the interfaces
  46. and objects are defined in PAPGUIDS.H located in that same common include
  47. directory.
  48.  
  49. The CThreaded facility in APPUTIL is used by STOSERVE to achieve thread
  50. safety, as it was in the FRESERVE sample. COPaper objects are derived from
  51. the CThreaded class and inherit its OwnThis and UnOwnThis methods. These
  52. methods allow only one thread at a time to have access to the STOSERVE
  53. server and to COPaper objects managed by the server.
  54.  
  55. For functional descriptions and a tutorial code tour of STOSERVE, see the
  56. Code Tour section in STOSERVE.HTM. For details on setting up the
  57. programmatic usage of STOSERVE, see the Usage section in STOSERVE.HTM. To
  58. read STOSERVE.HTM, run TUTORIAL.EXE in the main tutorial directory and
  59. click the STOSERVE lesson in the table of lessons. You can also achieve
  60. the same thing by clicking the STOSERVE.HTM file after locating the main
  61. tutorial directory in the Windows Explorer. See also STOCLIEN.HTM in the
  62. main tutorial directory for more details on the STOCLIEN client
  63. application and how it works with STOSERVE.DLL. You must build
  64. STOSERVE.DLL before building or running STOCLIEN.
  65.  
  66. STOSERVE's makefile automatically registers STOSERVE's DllPaper COM
  67. component in the registry. This component must be registered before
  68. STOSERVE is available to outside COM clients as a server for that
  69. component. This self-registration is done using the REGISTER.EXE utility
  70. built in the REGISTER sample. To build or run STOSERVE, you should build
  71. the REGISTER code sample first.
  72.  
  73. For details on setting up your system to build and test the code samples
  74. in this COM Tutorial series, see TUTORIAL.HTM. The supplied MAKEFILE is
  75. Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE
  76. command in the Command Prompt window.
  77.  
  78. Usage
  79. -----
  80.  
  81. To use STOSERVE, a client program does not need to include STOSERVE.H or
  82. link to STOSERVE.LIB. A COM client of STOSERVE obtains access solely
  83. through its object's CLSID and COM services. For STOSERVE, that CLSID is
  84. CLSID_DllPaper (defined in file PAPGUIDS.H in the \INC sibling directory).
  85. The STOCLIEN code sample shows how the client obtains this access.
  86.  
  87. STOSERVE is a DLL that is intended primarily as a COM server. Although it
  88. can be implicitly loaded by linking to its associated .LIB file, it is
  89. normally used after an explicit LoadLibrary call, usually from within the
  90. COM function CoGetClassObject. STOSERVE is a self-registering in-process
  91. server.
  92.  
  93. The makefile that builds this sample automatically registers the server in
  94. the registry. You can manually initiate its self-registration by issuing
  95. the following command at the command prompt in the STOSERVE directory:
  96.  
  97.   nmake register
  98.  
  99. You can also directly invoke the REGISTER.EXE command at the command prompt
  100. while in the STOSERVE directory.
  101.  
  102.   ..\register\register.exe stoserve.dll
  103.  
  104. These registration commands require a prior build of the REGISTER sample
  105. in this series, as well as a prior build of STOSERVE.DLL.
  106.  
  107. In this series, the makefiles use the REGISTER.EXE utility from the
  108. REGISTER sample. Recent releases of the Win32 Platform SDK and Visual C++
  109. include a utility, REGSVR32.EXE, which can be used in a similar fashion to
  110. register in-process servers and marshaling DLLs.
  111.  
  112.  
  113. FILES
  114. =====
  115.  
  116. Files         Description
  117.  
  118. STOSERVE.TXT  This file.
  119. MAKEFILE      The generic makefile for building the STOSERVE.DLL
  120.               code sample of this lesson.
  121. STOSERVE.H    The include file for declaring as imported or defining as
  122.               exported the service functions in STOSERVE.DLL.
  123. STOSERVE.CPP  The main implementation file for STOSERVE.DLL. Has DllMain
  124.               and the COM server functions (for example, DllGetClassObject).
  125. STOSERVE.DEF  The module definition file. Exports server housing functions.
  126. STOSERVE.RC   The DLL resource definition file for the executable.
  127. STOSERVE.ICO  The icon resource for the executable.
  128. SERVER.H      The include file for the server control C++ object.
  129. SERVER.CPP    The implementation file for the server control C++ object.
  130. FACTORY.H     The include file for the server's class factory COM objects.
  131. FACTORY.CPP   The implementation file for the server's class factories.
  132. CONNECT.H     The include file for the connection point enumerator,
  133.               connection point, and connection enumerator classes.
  134. CONNECT.CPP   The implementation file for the connection point enumerator,
  135.               connection point, and connection enumerators objects.
  136. PAPER.H       The include file for the COPaper COM object class.
  137. PAPER.CPP     The implementation file for the COPaper COM object class
  138.               and the connection points.
  139.