FRESERVE - Free-threaded COM objects in an in-process server


SUMMARY
=======

The FRESERVE sample shows how to construct a COM object in a free-threaded
in-process server. This sample departs from the sport utility vehicle
metaphor and associated interfaces used in other samples of this series.
FRESERVE introduces a new custom interface, IBall, and a new COM object,
COBall. COBall implements the IBall interface. Both COBall and its
in-process server are coded to support COM free threading in anticipation
of their use by the free-threaded client, FRECLIEN, in the next lesson.

The CThreaded facility in APPUTIL is used to achieve thread safety as it
was in the previous APTSERVE sample. COBall objects are derived from the
CThreaded class and so inherit its OwnThis and UnOwnThis methods. These
methods enforce mutually exclusive access to the FRESERVE server and to
free-threaded COBall objects managed by the server.

FRESERVE works with the FRECLIEN code sample to illustrate FRESERVE's COM
server facilities in a free-threaded server and the subsequent manipulation
of its components by a free-threaded client.

For functional descriptions and a tutorial code tour of FRESERVE, see the
Code Tour section in FRESERVE.HTM. For details on setting up the
programmatic usage of FRESERVE, see the Usage section in FRESERVE.HTM. To
read FRESERVE.HTM, run TUTORIAL.EXE in the main tutorial directory and
click the FRESERVE lesson in the table of lessons. You can also achieve
the same thing by clicking the FRESERVE.HTM file after locating the main
tutorial directory in the Windows Explorer. See also FRECLIEN.HTM in the
main tutorial directory for more details on the FRECLIEN client
application and how it works with FRESERVE.DLL. You must build
FRESERVE.DLL before building or running FRECLIEN.

FRESERVE's makefile automatically registers FRESERVE's DllBall component
in the registry. This component must be registered before FRESERVE is
available to outside COM clients as a server for that component. This
self-registration is done using the REGISTER.EXE utility built in the
previous REGISTER lesson. To build or run FRESERVE, you should build the
REGISTER code sample first.

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
-----

To use FRESERVE, a client program does not need to include FRESERVE.H or
link to FRESERVE.LIB. A COM client of FRESERVE obtains access solely
through its component's CLSID and COM services. For FRESERVE, that CLSID
is CLSID_DllBall (defined in file BALLGUID.H in the INC sibling
directory). The FRECLIEN code sample shows how the client obtains this
access.

FRESERVE is a DLL that is intended primarily as a free-threaded COM
server. Although it can be implicitly loaded by linking to its associated
.LIB file, it is normally used after an explicit LoadLibrary call, usually
from within COM's CoGetClassObject function. FRESERVE is a
self-registering in-process server.

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 FRESERVE directory:

  nmake register

You can also directly invoke the REGISTER.EXE command at the command prompt
while in the FRESERVE directory.

  ..\register\register.exe freserve.dll

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

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


FILES
=====

Files         Description

FRESERVE.TXT  This file.
MAKEFILE      The generic makefile for building the FRESERVE.DLL
              code sample of this lesson.
FRESERVE.H    The include file for declaring as imported or defining as
              exported the service functions in FRESERVE.DLL.
FRESERVE.CPP  The main implementation file for FRESERVE.DLL. Has DllMain
              and the COM server functions (for example, DllGetClassObject).
FRESERVE.DEF  The module definition file. Exports server housing functions.
FRESERVE.RC   The DLL resource definition file for the executable.
FRESERVE.ICO  The icon resource for the executable.
SERVER.H      The include file for the server control C++ object.
SERVER.CPP    The implementation file for the server control object.
FACTORY.H     The include file for the server's class factory COM objects.
FACTORY.CPP   The implementation file for the server's class factories.
BALL.H        The include file for the COBall COM object class.
BALL.CPP      The implementation file for the COBall COM object class.