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 / freserve / freserve.txt < prev    next >
Encoding:
Text File  |  1997-08-05  |  5.0 KB  |  106 lines
  1.  
  2. FRESERVE - Free-threaded COM objects in an in-process server
  3.  
  4.  
  5. SUMMARY
  6. =======
  7.  
  8. The FRESERVE sample shows how to construct a COM object in a free-threaded
  9. in-process server. This sample departs from the sport utility vehicle
  10. metaphor and associated interfaces used in other samples of this series.
  11. FRESERVE introduces a new custom interface, IBall, and a new COM object,
  12. COBall. COBall implements the IBall interface. Both COBall and its
  13. in-process server are coded to support COM free threading in anticipation
  14. of their use by the free-threaded client, FRECLIEN, in the next lesson.
  15.  
  16. The CThreaded facility in APPUTIL is used to achieve thread safety as it
  17. was in the previous APTSERVE sample. COBall objects are derived from the
  18. CThreaded class and so inherit its OwnThis and UnOwnThis methods. These
  19. methods enforce mutually exclusive access to the FRESERVE server and to
  20. free-threaded COBall objects managed by the server.
  21.  
  22. FRESERVE works with the FRECLIEN code sample to illustrate FRESERVE's COM
  23. server facilities in a free-threaded server and the subsequent manipulation
  24. of its components by a free-threaded client.
  25.  
  26. For functional descriptions and a tutorial code tour of FRESERVE, see the
  27. Code Tour section in FRESERVE.HTM. For details on setting up the
  28. programmatic usage of FRESERVE, see the Usage section in FRESERVE.HTM. To
  29. read FRESERVE.HTM, run TUTORIAL.EXE in the main tutorial directory and
  30. click the FRESERVE lesson in the table of lessons. You can also achieve
  31. the same thing by clicking the FRESERVE.HTM file after locating the main
  32. tutorial directory in the Windows Explorer. See also FRECLIEN.HTM in the
  33. main tutorial directory for more details on the FRECLIEN client
  34. application and how it works with FRESERVE.DLL. You must build
  35. FRESERVE.DLL before building or running FRECLIEN.
  36.  
  37. FRESERVE's makefile automatically registers FRESERVE's DllBall component
  38. in the registry. This component must be registered before FRESERVE is
  39. available to outside COM clients as a server for that component. This
  40. self-registration is done using the REGISTER.EXE utility built in the
  41. previous REGISTER lesson. To build or run FRESERVE, you should build the
  42. REGISTER code sample first.
  43.  
  44. For details on setting up your system to build and test the code samples
  45. in this COM Tutorial series, see TUTORIAL.HTM. The supplied MAKEFILE
  46. is Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE
  47. command in the Command Prompt window.
  48.  
  49. Usage
  50. -----
  51.  
  52. To use FRESERVE, a client program does not need to include FRESERVE.H or
  53. link to FRESERVE.LIB. A COM client of FRESERVE obtains access solely
  54. through its component's CLSID and COM services. For FRESERVE, that CLSID
  55. is CLSID_DllBall (defined in file BALLGUID.H in the INC sibling
  56. directory). The FRECLIEN code sample shows how the client obtains this
  57. access.
  58.  
  59. FRESERVE is a DLL that is intended primarily as a free-threaded COM
  60. server. Although it can be implicitly loaded by linking to its associated
  61. .LIB file, it is normally used after an explicit LoadLibrary call, usually
  62. from within COM's CoGetClassObject function. FRESERVE is a
  63. self-registering in-process server.
  64.  
  65. The makefile that builds this sample automatically registers the server in
  66. the registry. You can manually initiate its self-registration by issuing
  67. the following command at the command prompt in the FRESERVE directory:
  68.  
  69.   nmake register
  70.  
  71. You can also directly invoke the REGISTER.EXE command at the command prompt
  72. while in the FRESERVE directory.
  73.  
  74.   ..\register\register.exe freserve.dll
  75.  
  76. These registration commands require a prior build of the REGISTER sample
  77. in this series, as well as a prior build of FRESERVE.DLL.
  78.  
  79. In this series, the makefiles use the REGISTER.EXE utility from the
  80. REGISTER sample. Recent releases of the Win32 Platform SDK and Visual C++
  81. include a utility, REGSVR32.EXE, which can be used in a similar fashion to
  82. register in-process servers and marshaling DLLs.
  83.  
  84.  
  85. FILES
  86. =====
  87.  
  88. Files         Description
  89.  
  90. FRESERVE.TXT  This file.
  91. MAKEFILE      The generic makefile for building the FRESERVE.DLL
  92.               code sample of this lesson.
  93. FRESERVE.H    The include file for declaring as imported or defining as
  94.               exported the service functions in FRESERVE.DLL.
  95. FRESERVE.CPP  The main implementation file for FRESERVE.DLL. Has DllMain
  96.               and the COM server functions (for example, DllGetClassObject).
  97. FRESERVE.DEF  The module definition file. Exports server housing functions.
  98. FRESERVE.RC   The DLL resource definition file for the executable.
  99. FRESERVE.ICO  The icon resource for the executable.
  100. SERVER.H      The include file for the server control C++ object.
  101. SERVER.CPP    The implementation file for the server control object.
  102. FACTORY.H     The include file for the server's class factory COM objects.
  103. FACTORY.CPP   The implementation file for the server's class factories.
  104. BALL.H        The include file for the COBall COM object class.
  105. BALL.CPP      The implementation file for the COBall COM object class.
  106.