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 / dcdmarsh / dcdmarsh.txt < prev    next >
Text File  |  1997-09-09  |  6KB  |  109 lines
  1.  
  2. DCDMARSH - Standard Marshaling for DCOM
  3.  
  4.  
  5. SUMMARY
  6. =======
  7.  
  8. The DCDMARSH sample builds the DCDMARSH.DLL proxy/stub server.
  9. DCDMARSH.DLL works with DCDSERVE.EXE and DCOMDRAW.EXE to provide standard
  10. marshaling of the ISharePaper and IPaperSink custom interfaces across
  11. process and machine boundaries. In this set of samples, DCDMARSH.DLL is
  12. the marshaling server, DCDSERVE.EXE is the out-of-process component
  13. server, and DCOMDRAW.EXE is the client. As a Distributed COM (DCOM)
  14. sample, DCOMDRAW.EXE creates and uses components housed in the
  15. DCDSERVE.EXE server. Multiple DCOMDRAW clients running on multiple
  16. computers connected to a network can access a shared single COPaper object
  17. housed in the DCDSERVE.EXE server. Compared to previous samples requiring
  18. marshaling across process or machine boundaries, DCDMARSH requires no
  19. significant differences in how you provide standard marshaling for your
  20. custom interfaces. This lesson is therefore almost completely based on the
  21. standard marshaling techniques that were used in the MARSHAL sample. See
  22. the MARSHAL lesson for more details on these techniques.
  23.  
  24. The Microsoft Interface Definition Language (MIDL) compiler is used to
  25. compile the interface specifications (expressed using the MIDL language in
  26. the PAPINT.IDL file). Microsoft provides the MIDL.EXE as part of the
  27. Platform SDK. The MIDL compilation of PAPINT.IDL generates the PAPINT.H,
  28. PAPINT_I.C, PAPINT_P.C, and DLLDATA.C source files. The primary source for
  29. the DCDMARSH sample is in the PAPINT.IDL file. It contains the IDL
  30. specifications for the interfaces that DCDSERVE.DLL marshals. After the
  31. makefile copies the MIDL-generated PAPINT.H file to the common INC
  32. directory, PAPINT.H is available for use by such samples as DCDMARSH and
  33. DCOMDRAW.
  34.  
  35. For functional descriptions and a tutorial code tour of the DCDMARSH
  36. sample, see the Code Tour section in DCDMARSH.HTM. For details on setting
  37. building and registering DCDMARSH.DLL, see the Usage section in
  38. DCDMARSH.HTM. To read DCDMARSH.HTM, run TUTORIAL.EXE in the main tutorial
  39. directory and click the DCDMARSH lesson in the table of lessons. You can
  40. do the same thing by double-clicking the DCDMARSH.HTM file after locating
  41. the main tutorial directory in the Windows Explorer. See also DCDSERVE.HTM
  42. and DCOMDRAW.HTM in the main tutorial directory for more details on this
  43. client and server and how DCDMARSH.DLL supports their operation. Because
  44. those code samples rely on DCDMARSH.DLL, you must build it before building
  45. or running DCOMDRAW and DCDSERVE. DCDMARSH's makefile automatically
  46. registers DCDMARSH's proxy and stub interface marshalers in the system
  47. registry. This registration must be done before these interfaces can be
  48. used by COM clients or servers in the DCDSERVE and DCOMDRAW samples.
  49.  
  50. For details on setting up your system to build and test the code samples
  51. in this COM Tutorial series, see TUTORIAL.HTM. The supplied MAKEFILE
  52. is Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE
  53. command in the Command Prompt window.
  54.  
  55.  
  56. Usage
  57. -----
  58.  
  59. DCDMARSH.DLL is built solely as a marshaling DLL for certain interfaces.
  60. Although it can be implicitly loaded by linking to its associated .LIB
  61. file, it is normally used on behalf of a COM client using the interfaces
  62. across apartment, process, or machine boundaries. In these cases COM loads
  63. this DLL when needed. Before COM can find and load DCDMARSH.DLL to provide
  64. marshaling for its supported interfaces, the DCDMARSH server must be
  65. registered in the registry as the marshaling server for those interfaces.
  66. DCDMARSH is a self-registering in-process server. It exports the standard
  67. DllRegisterServer and DllUnregisterServer functions.
  68.  
  69. The makefile that builds this sample automatically registers the server in
  70. the registry. You can manually initiate its self-registration by issuing
  71. the following command at the command prompt in the DCDMARSH directory:
  72.  
  73.   nmake register
  74.  
  75. This assumes that you have a compilation environment set up. If not, you
  76. can also directly invoke the REGISTER.EXE command at the command prompt
  77. while in the DCDMARSH directory.
  78.  
  79.   ..\register\register.exe dcdmarsh.dll
  80.  
  81. These registration commands require a prior build of the REGISTER sample
  82. in this series, as well as a prior build of DCDMARSH.DLL.
  83.  
  84. In this series, the makefiles use the REGISTER.EXE utility from the
  85. REGISTER sample. Recent releases of the Platform SDK and Visual C++
  86. include a utility, REGSVR32.EXE, that can be used in a similar fashion to
  87. register in-process servers and marshaling DLLs.
  88.  
  89.  
  90. FILES
  91. =====
  92.  
  93. Files        Description
  94.  
  95. DCDMARSH.TXT This file.
  96. MAKEFILE     The generic makefile for building the code sample.
  97. DCDMARSH.DEF The module definition file. Exports server housing functions.
  98. PAPINT.IDL   The MIDL interface specifications for ISharePaper and
  99.              IPaperSink.
  100. PAPINT.H     Generated by compiling PAPINT.IDL. The interface include
  101.              file for the specified interfaces. Included by other modules.
  102. PAPINT_I.C   Generated by compiling PAPINT.IDL. The data definitions
  103.              of the GUIDs for the marshaled interfaces.
  104. PAPINT_P.C   Generated by compiling PAPINT.IDL. The actual proxy and
  105.              stub functions for the interface methods.
  106. DLLDATA.C    Generated by compiling PAPINT.IDL. Contains routines for
  107.              the proxies and default definitions for the DllMain,
  108.              DllRegisterServer, and DllUnregisterServer functions.
  109.