Tricks of the Windows Gam…ming Gurus (2nd Edition)/Disc2.iso/msdn_vcb/samples/vc98/sdk/com/tutsamp/aptserve/aptserve.txt

Text File | 1997-08-05 | 8KB | 151 lines

APTSERVE - Apartment Model Local Server


SUMMARY
=======

The apartment model is a way of COM programming that associates a single
thread of execution with a family of COM objects in such a way that an
object in the family will be executed only on the thread of its apartment.
When this arrangement is constructed in a server, COM plays a role in
enforcing the single-thread rule for objects in the apartment by ensuring
that client calls on any thread to objects in a server apartment will only
be executed on the thread of the apartment.

The APTSERVE sample begins with the car-related COM Objects of the
previous LOCSERVE sample and rehouses them in an out-of-process local
server, APTSERVE.EXE, that uses the apartment threading model. To do so
requires little change to the COM objects themselves (COCar, COUtilityCar,
and COCruiseCar). The COCruiseCar object required some changes. In
LOCSERVE COCruiseCar reused the COCar object using aggregation. Since this
sample rehouses these objects within different apartments, COCruiseCar
must be recoded to reuse COCar using containment. But most importantly,
the server housing must undergo significant revision. This sample
introduces the new facilities to partition each class factory and its
created object instances into a separate apartment.

In this sample, an out-of-process COM server is partitioned into three
single-threaded apartments, each corresponding to the component types seen
in previous samples: AptCar, AptUtilityCar, and AptCruiseCar. These
components are known by their CLSIDs as: CLSID_AptCar,
CLSID_AptUtilityCar, and CLSID_AptCruiseCar. Appropriate class factories
for those components are also provided: CFCar, CFUtilityCar, and
CFCruiseCar. As compared to the implementation of these class factories in
previous lessons, no significant change to the class factories themselves
is required in this sample.

In the series of COM tutorial code samples, APTSERVE works with the
APTCLIEN code sample to illustrate APTSERVE's partitioning of the server
facilities for creating and manipulating components within separate
apartments and to show how the components are accessed by a client.

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

You must build APTSERVE.EXE before building or running APTCLIEN. The
accompanying makefile automatically registers APTSERVE components in the
registry. These components must be registered before APTSERVE is available
to outside COM clients as a server for those components. This registration
is done using the REGISTER.EXE utility built in the earlier REGISTER
lesson. To build or run APTSERVE, you should build the REGISTER code
sample first.

Like its predecessors, APTSERVE uses many of the utility classes and
services provided by APPUTIL. For more details on APPUTIL, study the
APPUTIL library's source code and APPUTIL.HTM, located in the main
tutorial directory.

As an out-of-process local server with apartment threading, APTSERVE
relies on standard marshaling for clients to use its interfaces across
both thread and process boundaries. Such marshaling is provided in the
MARSHAL.DLL server built in the previous lesson. To build or run APTSERVE,
you should build the MARSHAL 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.

Like the LOCSERVE/LOCCLIEN pair, APTSERVE uses APPUTIL's CSendLog trace
logging facility to allow display of internal APTSERVE behavior integrated
with client behavior in the APTCLIEN log display. See APTCLIEN.HTM for
more details setting up this logging operation. See LOCSERVE.HTM for
details on how CSendLog works.

Usage
-----

The APTSERVE application is meant to be used as an out-of-process COM
server. Out-of-process servers like APTSERVE are registered in the system
registry, and APTSERVE has built-in support for registering its
components. It accepts the following command line switches to register and
unregister:

    -RegServer or /RegServer to register
    -UnregServer or /UnregServer to unregister

String matches on these switches are case-insensitive. APTSERVE also
recognizes the standard -Embedding or /Embedding switch, which directs it
to run as an out-of-process server. This switch normally means that the
server will remain hidden when run by COM on behalf of a client. However,
for the tutorial purposes of this sample, APTSERVE can be run visible when
controlled by a client. You can manually direct APTSERVE to run visible by
starting it with an explicit -Embedding switch on its command line prior
to running the APTCLIEN client. If you attempt to run APTSERVE as a
stand-alone application with no command line switches, it will exit with
an error.

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

  nmake register

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

  ..\register\register.exe aptserve.exe

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


FILES
=====

Files        Description

APTSERVE.TXT This file.
MAKEFILE     The generic makefile for building the APTSERVE.EXE
             code sample of this tutorial lesson.
APTSERVE.H   The include file for the APTSERVE application. Contains
             class declarations, function prototypes, and resource
             identifiers.
APTSERVE.CPP The main implementation file for APTSERVE.EXE. Has WinMain
             and CMainWindow implementation, as well as the main menu
             dispatching.
APTSERVE.RC  The resource definition file for the executable.
APTSERVE.ICO The icon resource for the executable.
SERVER.H     The include file for the server control C++ object. Also
             used for APTSERVE externs.
SERVER.CPP   The implementation file for the server control object.
             Manages apartment threads, object counts, server lifetime,
             and the creation of class factories.
FACTORY.H    The include file for the server's class factory COM objects.
FACTORY.CPP  The implementation file for the server's class factories.
CAR.H        The include file for the COCar COM object class.
CAR.CPP      The implementation file for the COCar COM object class.
UTILCAR.H    The include file for the COUtililtyCar COM object class.
UTILCAR.CPP  The implementation file for the COUtilityCar COM object class.
CRUCAR.H     The include file for the COCruiseCar COM object class.
CRUCAR.CPP   The implementation file for the COCruiseCar COM object class.