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

Text File | 1997-09-09 | 10KB | 194 lines

PERTEXT - IPersistStreamInit Persistent Object Server


SUMMARY
=======

PERTEXT is the second sample in a group of samples that covers various
techniques for implementing COM object persistence. The first sample,
PERSERVE, covers persistence by implementing the IPersistStream standard
interface. This sample, PERTEXT, covers persistence by implementing the
IPersistStreamInit standard interface. The third sample, PERDRAW, covers
persistence by implementing the IPersistStorage standard interface. The
fourth sample, PERCLIEN, covers how a client exploits the kinds of
persistence provided the PERSERVE, PERTEXT, and PERDRAW server components.

The PERTEXT sample introduces the COTextPage COM object, which
encapsulates the data of an editable page of text. COTextPage objects
expose a set of interfaces whose methods make the objects connectable,
persistent managers of text data. Client access to this data is available
through an ITextPage custom interface. COTextPage implements the ITextPage
interface.

The PERTEXT sample keeps a clear architectural distinction between client
and server. Among other things, COTextPage provides no graphical user
interface (GUI), relying instead upon the client for all GUI behavior.

The PERCLIEN client provides the GUI display and manages the list of
pages, the contents of which are stored in a compound file that contains
both the contents of the list and of each page in that list. The user of
PERCLIEN can edit the content of two types of pages: text pages and
drawing pages. Text pages have data that the user can edit using a simple
windowed text editor. Drawing pages have drawing data that the user can
edit using free-form, scribble-like functionality based on the earlier
STOSERVE and STOCLIEN samples. Both types of editing are done in separate
client windows. For more information, see PERCLIEN.HTM.

Storage in the compound file is achieved because the components provide
persistent COM objects that encapsulate the page list and edited page
data. PERSERVE houses a persistent object that encapsulates the single
page list kept in each compound file containing such pages. PERTEXT houses
a persistent object that encapsulates the edited text data for each text
page. PERDRAW houses a persistent object that encapsulates the drawing
data for each drawing page.

The COPageList object in the PERSERVE sample encapsulates the persistent
page list data. COPageList implements the IPersistStream standard
interface to expose control of the page list storage located in the
client-provided stream of a compound file. The COTextPage object in this
PERTEXT sample encapsulates the data of an edited text page. COTextPage
implements the IPersistStreamInit standard interface to expose control of
the text data storage that is located in the client-provided stream of a
compound file. In contrast to these stream-based persistent objects, the
CODrawPage object in the PERDRAW sample encapsulates the persistent
drawing-ink data. CODrawPage implements the IPersistStorage standard
interface to expose control of the drawing-ink data storage located in the
client-provided substorage of a compound file.

This code sample focuses primarily on COTextPage's implementation of the
IPersistStreamInit interface to provide stream-based persistence for a COM
object. IPersistStreamInit's InitNew method is the main difference between
the IPersistStream interface used in the PERSERVE sample and the
IPersistStreamInit interface used in the PERTEXT sample. This sample
covers the InitNew method in detail. PERTEXT works with the PERCLIEN code
sample to illustrate the joint use by client and server of
IPersistStreamInit-based persistence.

COTextPage's support for object persistence is the primary means of
storing the text page data. COTextPage stores its text data in a
client-provided stream located in a structured storage compound file. The
compound file has a unique format because of the various streams and
storages used. The client identifies these compound files as page files
with a .PAG extension. The client controls the use of the containing
compound file and provides COTextPage with a pointer to the IStream
interface to load and save its text data in the compound file. The IStream
pointer is passed to COTextPage in calls to the IPersistStreamInit
interface methods.

COTextPage also exposes an ITextPage custom interface to manipulate the
text that is encapsulated in the text page. ITextPage exposes the
GetLength, GetText, PutText, and Clear methods.

COTextPage also supports connectable object features. The
IConnectionPointContainer interface is exposed, an appropriate connection
point is implemented, and an outgoing custom ITextPageSink interface is
declared to send notifications to the client.

The two ITextPage and ITextPageSink custom interfaces are declared in
IPAGES.H located in the common INC directory. PAGEGUID.H, which contains
the GUIDs for the interfaces and objects, is also located in that same
directory.

The PERTEXT sample uses the CThreaded facility in APPUTIL to achieve
thread safety in the server housing and the class factory. Because the
PERTEXT.DLL is generally accessed from a Single Threaded Apartment (STA)
as an in-process server, COTextPage instances are not coded as thread-safe
using the CThreaded facility. The CLSID_TextPage component is registered
as supporting the apartment threading model.

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

The PERTEXT server provides a TextPage component that can create instances
of the COTextPage COM object. COTextPage is housed in the PERTEXT.DLL
in-process server and is made publicly available as a custom COM
component. Like all other servers in this tutorial series, PERTEXT.DLL is
a self-registering COM server. It makes the COTextPage object type
available to clients as the TextPage component in the PERTEXT server using
a CLSID_TextPage registration in the Registry.

PERTEXT's makefile automatically registers its TextPage COM component in
the registry, which it must do before clients can use PERTEXT.DLL as a
server for the TextPage component. This self-registration is started in
the makefile using the REGISTER.EXE utility built in the REGISTER sample.
To build or run PERTEXT.DLL, you must 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 PERTEXT.DLL, a client program does not need to include PERTEXT.H or
link to PERTEXT.LIB. A COM client of PERTEXT.DLL obtains access solely
through its object's CLSID and COM services. For PERTEXT.DLL, that CLSID
is CLSID_TextPage (defined in PAGEGUID.H in the INC sibling directory).
The PERCLIEN code sample shows how the client obtains this access.

PERTEXT.DLL is intended primarily as a 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. PERTEXT.DLL 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 PERTEXT 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 PERTEXT directory.

  ..\register\register.exe pertext.dll

These registration commands require a prior build of both the REGISTER
sample and PERTEXT.DLL.

In this series, the makefiles use the REGISTER.EXE utility from the
REGISTER sample. Recent releases of the Microsoft 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

PERTEXT.TXT   This file.
MAKEFILE      The generic makefile for building the PERTEXT.DLL
              code sample of this lesson.
PERTEXT.H     The include file for declaring as imported or defining as
              exported the service functions in PERTEXT.DLL.
PERTEXT.CPP   The main implementation file for PERTEXT.DLL. Has DllMain
              and the COM server functions (for example, DllGetClassObject).
PERTEXT.DEF   The module definition file. Exports server housing functions.
PERTEXT.RC    The DLL resource definition file for the executable.
PERTEXT.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 C++ 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.
CONNECT.H     The include file for the connection point enumerator,
              connection point, and connection enumerator classes.
CONNECT.CPP   The implementation file for the connection point enumerator,
              connection point, and connection enumerators objects.
TEXTPAGE.H    The include file for the COTextPage COM object class.
TEXTPAGE.CPP  The implementation file for the COTextPage COM object class
              and the connection points.