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 / marshal2 / marshal2.txt < prev    next >
Text File  |  1997-09-09  |  7KB  |  130 lines
  1.  
  2. MARSHAL2 - Self-Registration of Standard Marshaling Servers
  3.  
  4.  
  5. SUMMARY
  6. =======
  7.  
  8. The MARSHAL2 sample shows an alternate and more advanced technique for
  9. building a proxy/stub marshaling DLL for the ICar, IUtility, and ICruise
  10. custom interfaces. The previous MARSHAL sample illustrated the system
  11. default method of producing the marshaling DLL. That method controlled the
  12. conditional compilation of the DLLDATA.C file to generate default
  13. definitions for the DllMain, DllRegisterServer, and DllUnregisterServer
  14. functions in the DLL. WMARSHAL2 does not generate these default functions.
  15. Instead, they coded explicitly.  Thus, this lesson has more detail on the
  16. content of these functions.
  17.  
  18. Although the default definitions of these functions are adequate for most
  19. programming, there may be occasions when you want more control over the
  20. content of the marshaling DLL. For example, you might want to perform some
  21. action within DllMain during DLL_PROCESS_ATTACH, you might want to code
  22. explicit control over the registration and unregistration of the
  23. marshaling server, or you might want to add standard module version
  24. information to the DLL resources. This sample covers these areas.
  25.  
  26. As in the MARSHAL sample, the Microsoft Interface Definition Language
  27. compiler (MIDL.EXE) is used to compile the interface definitions
  28. (expressed using the MIDL language in the MICARS.IDL file). MIDL.EXE is a
  29. utility provided as part of the Microsoft Platform Software Development
  30. Kit (SDK). The MIDL compilation of MICARS.IDL generates additional source
  31. files: MICARS.H, MICARS_I.C, MICARS_P.C, and DLLDATA.C.
  32.  
  33. In the series of COM Tutorial code samples, MARSHAL2 is an alternate
  34. marshaling DLL that can replace MARSHAL.DLL produced in the MARSHAL sample
  35. and can work with later samples in the series to provide standard
  36. marshaling for the custom ICar, IUtility, and ICruise interfaces. To
  37. achieve this, just register MARSHAL2.DLL. This will override any previous
  38. registration of MARSHAL.DLL. Since both of these DLLs provide proxy/stub
  39. marshaling for the same interfaces, the one registered most recently will
  40. replace the other if it is registered.
  41.  
  42. For functional descriptions and a tutorial code tour of MARSHAL2, see the
  43. Code Tour section in MARSHAL2.HTM. For details on setting up the
  44. programmatic usage of MARSHAL2, see the Usage section in MARSHAL2.HTM. To
  45. read MARSHAL2.HTM, run TUTORIAL.EXE in the main tutorial directory and
  46. click the MARSHAL2 lesson in the table of lessons. You can also do the
  47. same thing by double-clicking the MARSHAL2.HTM file after locating the
  48. main tutorial directory in Windows Explorer. For a simpler way to provide
  49. the same standard marshaling functionality that MARHSAL2 provides, see
  50. MARSHAL.HTM.
  51.  
  52. The subsequent samples in the series that require marshaling of the ICar,
  53. IUtility, and ICruise interfaces normally rely on the registration of
  54. MARSHAL.DLL as the marshaling DLL. MARSHAL.DLL is produced in the previous
  55. MARSHAL sample. MARSHAL2's makefile does not automatically register
  56. MARSHAL2.DLL as the marshaling DLL for those car-related interfaces.
  57. However, this registration can be enabled in MARSHAL2's makefile by
  58. uncommenting the appropriate lines. Registering MARSHAL2 will replace any
  59. prior registration of MARSHAL.DLL. Although, these two marshaling DLLs are
  60. functionally equivalent, there are subtle differences in how they perform
  61. their self-registration. For more details on how MARSHAL2.DLL performs
  62. self-registration see below.
  63.  
  64. If enabled in the makefile, MARSHAL2's self-registration is done using the
  65. REGISTER.EXE utility built in the REGISTER sample. To build or run
  66. MARSHAL2, you should build the REGISTER code sample first.
  67.  
  68. For details on setting up your system to build and test the code samples
  69. in this COM Tutorial series, see TUTORIAL.HTM. The supplied MAKEFILE is
  70. Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE
  71. command in the Command Prompt window.
  72.  
  73.  
  74. Usage
  75. -----
  76.  
  77. MARSHAL2 is a DLL that is built solely as a marshaling DLL for the
  78. specified interfaces. Although it can be implicitly loaded by linking to
  79. its associated .LIB file, it is normally used on behalf of a COM client
  80. that functions the server across apartment, process, or machine
  81. boundaries. COM loads this DLL automatically in these situations. Before
  82. COM can find and load MARSHAL2.DLL to support marshaling of its supported
  83. interfaces, the MARSHAL2 server must be registered in the registry as the
  84. marshaling server for those interfaces. MARSHAL2 is a self-registering
  85. in-process server. If enabled (see above), the makefile that builds this
  86. sample automatically registers the server in the registry. You can
  87. manually initiate its self-registration by issuing the following command
  88. at the command prompt in the MARSHAL2 directory:
  89.  
  90.   nmake register
  91.  
  92. This assumes that you have a compilation environment set up. If not, you
  93. can also directly invoke the REGISTER.EXE command at the command prompt
  94. while in the MARSHAL2 directory.
  95.  
  96.   ..\register\register.exe marshal2.dll
  97.  
  98. These registration commands require a prior build of both the REGISTER
  99. sample and the MARSHAL2 sample.
  100.  
  101. In this series, the makefiles use the REGISTER.EXE utility from the
  102. REGISTER sample. Recent releases of the Microsoft Platform SDK and Visual
  103. C++ include a utility, REGSVR32.EXE, which can be used in a similar
  104. fashion to register in-process servers and marshaling DLLs.
  105.  
  106.  
  107. FILES
  108. =====
  109.  
  110. Files         Description
  111.  
  112. MARSHAL2.TXT  This file.
  113. MAKEFILE      The generic makefile for building the MARSHAL2.DLL
  114.               code sample.
  115. MARSHAL2.CPP  The main implementation file for MARSHAL2.DLL. Has DllMain
  116.               and the self-registration functions.
  117. MARSHAL2.DEF  The module definition file. Exports server housing functions.
  118. MARSHAL2.RC   The DLL resource definition file for the executable.
  119. MARSHAL2.ICO  The icon resource for the executable.
  120. MICARS.IDL    The MIDL interface specifications for ICar, IUtility,
  121.               and ICruise.
  122. MICARS.H      Generated by compiling MICARS.IDL. The interface include
  123.               file for the specified interfaces.
  124. MICARS_I.C    Generated by compiling MICARS.IDL. The data definitions
  125.               of the GUIDs for the marshaled interfaces.
  126. MICARS_P.C    Generated by compiling MICARS.IDL. The actual proxy and
  127.               stub functions for the interface methods.
  128. DLLDATA.C     Generated by compiling MICARS.IDL. DLL data routines for
  129.               the proxies.
  130.