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 / marshal / marshal.txt < prev    next >
Encoding:
Text File  |  1997-09-09  |  6.4 KB  |  129 lines
  1.  
  2. MARSHAL - Standard Marshaling of Custom Interfaces
  3.  
  4.  
  5. SUMMARY
  6. =======
  7.  
  8. The MARSHAL sample anticipates the interaction of a client and
  9. out-of-process server in the LOCCLIEN and LOCSERVE samples. For a client
  10. like LOCCLIEN to use the COM objects in an out-of-process server like
  11. LOCSERVE requires marshaling the car-related interfaces used in the
  12. previous COM samples of this series. The MARSHAL sample creates a
  13. proxy/stub DLL that provides standard marshaling for the ICar, IUtility,
  14. and ICruise custom interfaces.
  15.  
  16. The Microsoft Interface Definition Language (MIDL) compiler is used
  17. to compile the interface specifications (expressed using the MIDL language
  18. in the MICARS.IDL file). MIDL.EXE is a utility provided as part of the
  19. Microsoft Platform SDK. The MIDL compilation of MICARS.IDL generates
  20. additional source files: MICARS.H, MICARS_I.C, MICARS_P.C, and DLLDATA.C.
  21.  
  22. In the series of COM Tutorial code samples, MARSHAL works with the
  23. LOCSERVE and LOCCLIEN samples to illustrate a COM client using the
  24. interfaces on COM objects in an out-of-process local server. In this
  25. sample series, only standard marshaling is used for the custom ICar,
  26. IUtility, and ICruise interfaces. Later samples in the series which use
  27. these interfaces across apartment, process, or machine boundaries (for
  28. example, APTSERVE, APTCLIEN, and REMCLIEN) also rely on MARSHAL.DLL for
  29. standard marshaling of these interfaces.
  30.  
  31. The MARSHAL sample demonstrates a simple and efficient way to create a
  32. marshaling DLL for custom interfaces. Default definitions are generated
  33. for the DllMain, DllGetClassObject, DllCanUnloadNow, GetProxyDllInfo,
  34. DllRegisterServer, and DllUnregisterServer functions. With this technique,
  35. all that is needed is a makefile, a .DEF file, and an input .IDL file
  36. specifying the interfaces. However, there may be occasions when you want
  37. more control over the content of the marshaling DLL. For example, you may
  38. want to perform some action within DllMain during DLL_PROCESS_ATTACH, you
  39. may want to code explicit control over the registration and unregistration
  40. of the marshaling server, or you may want to add standard module version
  41. information to the DLL resources. For coverage of these areas, see the
  42. subsequent MARSHAL2 sample. MARSHAL2 produces a marshaling DLL that
  43. marshals the same custom interfaces as MARSHAL. When registered,
  44. MARSHAL2.DLL is functionally equivalent to MARSHAL.DLL and replaces it.
  45. The makefile for the MARSHAL2.DLL does not automatically register the
  46. server to achieve this replacement. You must enable this in MARSHAL2's
  47. makefile. For the MARSHAL2 lesson, see MARSHAL2.HTM.
  48.  
  49. For functional descriptions and a tutorial code tour of MARSHAL, see the
  50. Code Tour section in MARSHAL.HTM. For details on setting up the
  51. programmatic usage of MARSHAL.DLL, see the Usage section in MARSHAL.HTM.
  52. To read MARSHAL.HTM, run TUTORIAL.EXE in the main tutorial directory and
  53. click the MARSHAL lesson in the table of lessons. You can also do the same
  54. thing by double-clicking the MARSHAL.HTM file after locating the main
  55. tutorial directory in Windows Explorer. For more details on the LOCCLIEN
  56. client and the LOCSERVE server and how MARSHAL.DLL supports their
  57. operation, see LOCSERVE.HTM and LOCCLIEN.HTM in the main tutorial
  58. directory. Because those code samples rely on MARSHAL.DLL, you must build
  59. MARSHAL DLL before building or running LOCCLIEN and LOCSERVE. MARSHAL's
  60. makefile automatically registers MARSHAL's proxy and stub interface
  61. marshalers in the system registry. This registration must be done before
  62. these interfaces can be used by COM clients or servers in LOCSERVE,
  63. LOCCLIEN, and later samples of the series.
  64.  
  65. MARSHAL's self-registration is done using the REGISTER.EXE utility built
  66. in the REGISTER sample. To build or run MARSHAL, you must build the
  67. REGISTER code sample first.
  68.  
  69. For details on setting up your system to build and test the code samples
  70. in this COM Tutorial series, see TUTORIAL.HTM. The supplied MAKEFILE
  71. is Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE
  72. command in the Command Prompt window.
  73.  
  74.  
  75. Usage
  76. -----
  77.  
  78. MARSHAL.DLL is built solely as a marshaling DLL for the specified
  79. interfaces. Although it can be implicitly loaded by linking to its
  80. associated .LIB file, it is normally used on behalf of a COM client that
  81. is using the interfaces across apartment, process, or machine boundaries.
  82. In these cases COM automatically loads this DLL as needed. Before COM can
  83. find and load the MARSHAL DLL to support marshaling of its supported
  84. interfaces, the MARSHAL server must be registered in the registry as the
  85. marshaling server for those interfaces. MARSHAL is a self-registering
  86. in-process server.
  87.  
  88. The makefile that builds this sample automatically registers the server in
  89. the registry. You can manually initiate its self-registration by issuing
  90. the following command at the command prompt in the MARSHAL directory:
  91.  
  92.   nmake register
  93.  
  94. This assumes that you have a compilation environment set up. If not, you
  95. can also directly invoke the REGISTER.EXE command at the command prompt
  96. while in the MARSHAL directory.
  97.  
  98.   ..\register\register.exe marshal.dll
  99.  
  100. These registration commands require a prior build of the REGISTER sample
  101. in this series, as well as a prior build of MARSHAL.DLL.
  102.  
  103. In this series, the makefiles use the REGISTER.EXE utility from the
  104. REGISTER sample. Recent releases of the Microsoft Platform SDK and
  105. Visual C++ include a utility, REGSVR32.EXE, which can be used in a
  106. similar fashion to register in-process servers and marshaling DLLs.
  107.  
  108.  
  109. FILES
  110. =====
  111.  
  112. Files        Description
  113.  
  114. MARSHAL.TXT  This file.
  115. MAKEFILE     The generic makefile for building the MARSHAL.DLL
  116.              code sample.
  117. MICARS.IDL   The MIDL interface specifications for ICar, IUtility,
  118.              and ICruise.
  119. MARSHAL.DEF  The module definition file. Exports server housing functions.
  120. MICARS.H     Generated by compiling MICARS.IDL. The interface include
  121.              file for the specified interfaces.
  122. MICARS_I.C   Generated by compiling MICARS.IDL. The data definitions
  123.              of the GUIDs for the marshaled interfaces.
  124. MICARS_P.C   Generated by compiling MICARS.IDL. The actual proxy and
  125.              stub functions for the interface methods.
  126. DLLDATA.C    Generated by compiling MICARS.IDL. Contains routines for
  127.              the proxies and default definitions for the DllMain,
  128.              DllRegisterServer, and DllUnregisterServer functions.
  129.