DCDMARSH - Standard Marshaling for DCOM


SUMMARY
=======

The DCDMARSH sample builds the DCDMARSH.DLL proxy/stub server.
DCDMARSH.DLL works with DCDSERVE.EXE and DCOMDRAW.EXE to provide standard
marshaling of the ISharePaper and IPaperSink custom interfaces across
process and machine boundaries. In this set of samples, DCDMARSH.DLL is
the marshaling server, DCDSERVE.EXE is the out-of-process component
server, and DCOMDRAW.EXE is the client. As a Distributed COM (DCOM)
sample, DCOMDRAW.EXE creates and uses components housed in the
DCDSERVE.EXE server. Multiple DCOMDRAW clients running on multiple
computers connected to a network can access a shared single COPaper object
housed in the DCDSERVE.EXE server. Compared to previous samples requiring
marshaling across process or machine boundaries, DCDMARSH requires no
significant differences in how you provide standard marshaling for your
custom interfaces. This lesson is therefore almost completely based on the
standard marshaling techniques that were used in the MARSHAL sample. See
the MARSHAL lesson for more details on these techniques.

The Microsoft Interface Definition Language (MIDL) compiler is used to
compile the interface specifications (expressed using the MIDL language in
the PAPINT.IDL file). Microsoft provides the MIDL.EXE as part of the
Platform SDK. The MIDL compilation of PAPINT.IDL generates the PAPINT.H,
PAPINT_I.C, PAPINT_P.C, and DLLDATA.C source files. The primary source for
the DCDMARSH sample is in the PAPINT.IDL file. It contains the IDL
specifications for the interfaces that DCDSERVE.DLL marshals. After the
makefile copies the MIDL-generated PAPINT.H file to the common INC
directory, PAPINT.H is available for use by such samples as DCDMARSH and
DCOMDRAW.

For functional descriptions and a tutorial code tour of the DCDMARSH
sample, see the Code Tour section in DCDMARSH.HTM. For details on setting
building and registering DCDMARSH.DLL, see the Usage section in
DCDMARSH.HTM. To read DCDMARSH.HTM, run TUTORIAL.EXE in the main tutorial
directory and click the DCDMARSH lesson in the table of lessons. You can
do the same thing by double-clicking the DCDMARSH.HTM file after locating
the main tutorial directory in the Windows Explorer. See also DCDSERVE.HTM
and DCOMDRAW.HTM in the main tutorial directory for more details on this
client and server and how DCDMARSH.DLL supports their operation. Because
those code samples rely on DCDMARSH.DLL, you must build it before building
or running DCOMDRAW and DCDSERVE. DCDMARSH's makefile automatically
registers DCDMARSH's proxy and stub interface marshalers in the system
registry. This registration must be done before these interfaces can be
used by COM clients or servers in the DCDSERVE and DCOMDRAW samples.

For details on setting up your system to build and test the code samples
in this COM Tutorial series, see TUTORIAL.HTM. The supplied MAKEFILE
is Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE
command in the Command Prompt window.


Usage
-----

DCDMARSH.DLL is built solely as a marshaling DLL for certain interfaces.
Although it can be implicitly loaded by linking to its associated .LIB
file, it is normally used on behalf of a COM client using the interfaces
across apartment, process, or machine boundaries. In these cases COM loads
this DLL when needed. Before COM can find and load DCDMARSH.DLL to provide
marshaling for its supported interfaces, the DCDMARSH server must be
registered in the registry as the marshaling server for those interfaces.
DCDMARSH is a self-registering in-process server. It exports the standard
DllRegisterServer and DllUnregisterServer functions.

The makefile that builds this sample automatically registers the server in
the registry. You can manually initiate its self-registration by issuing
the following command at the command prompt in the DCDMARSH directory:

  nmake register

This assumes that you have a compilation environment set up. If not, you
can also directly invoke the REGISTER.EXE command at the command prompt
while in the DCDMARSH directory.

  ..\register\register.exe dcdmarsh.dll

These registration commands require a prior build of the REGISTER sample
in this series, as well as a prior build of DCDMARSH.DLL.

In this series, the makefiles use the REGISTER.EXE utility from the
REGISTER sample. Recent releases of the Platform SDK and Visual C++
include a utility, REGSVR32.EXE, that can be used in a similar fashion to
register in-process servers and marshaling DLLs.


FILES
=====

Files        Description

DCDMARSH.TXT This file.
MAKEFILE     The generic makefile for building the code sample.
DCDMARSH.DEF The module definition file. Exports server housing functions.
PAPINT.IDL   The MIDL interface specifications for ISharePaper and
             IPaperSink.
PAPINT.H     Generated by compiling PAPINT.IDL. The interface include
             file for the specified interfaces. Included by other modules.
PAPINT_I.C   Generated by compiling PAPINT.IDL. The data definitions
             of the GUIDs for the marshaled interfaces.
PAPINT_P.C   Generated by compiling PAPINT.IDL. The actual proxy and
             stub functions for the interface methods.
DLLDATA.C    Generated by compiling PAPINT.IDL. Contains routines for
             the proxies and default definitions for the DllMain,
             DllRegisterServer, and DllUnregisterServer functions.