======================================================================
Microsoft Product Support Services Application Note (Text File)
WW0532: OBJECT LINKING AND EMBEDDING (OLE)
======================================================================
Revision Date: 4/92
No Disk Included

The following information applies to Microsoft(R) Windows(TM) version
3.1.

--------------------------------------------------------------------
| INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY |
| ACCOMPANY THIS DOCUMENT (collectively referred to as an |
| Application Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY |
| KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO |
| THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A |
| PARTICULAR PURPOSE. The user assumes the entire risk as to the |
| accuracy and the use of this Application Note. This Application |
| Note may be copied and distributed subject to the following |
| conditions: 1) All text must be copied without modification and |
| all pages must be included; 2) If software is included, all files |
| on the disk(s) must be copied without modification [the MS-DOS(R) |
| utility DISKCOPY is appropriate for this purpose]; 3) All |
| components of this Application Note must be distributed together; |
| and 4) This Application Note may not be distributed for profit. |
| |
| Copyright 1992 Microsoft Corporation. All Rights Reserved. |
| Microsoft and MS-DOS are registered trademarks and Windows is a |
| trademark of Microsoft Corporation. |
--------------------------------------------------------------------


INTRODUCTION TO OBJECT LINKING AND EMBEDDING
============================================

Object linking and embedding (OLE) is a technique for implementing
"compound document" features by making simple extensions to existing
applications that run under Microsoft Windows. This technique allows
you to view and manipulate various forms of information (for example,
spreadsheets, text, and graphics) in the context of a single document.
Rather than having to manually switch between different applications,
you can alter data by simply selecting and double-clicking the object
of interest. The process of running application code is automated and
is invisible to you.


THE PROGRESSION FROM CLIPBOARD TO DDE TO OLE
============================================

The need to integrate information from different applications is not
new. In the past, users have taken advantage of the Windows Clipboard,
and more recently, dynamic data exchange (DDE) to accomplish this.

The Clipboard provides a basic means for moving data between
applications. You select the desired information in the source
document, transfer the information to the Clipboard by choosing Copy
from the Edit menu, then place the information in the target document
using the Paste command on the Edit menu.

Data transfers through the Clipboard are static. This means that if
the source information changes, you must manually copy the revisions
to the target document if you want the target document to stay up to
date. Additionally, the target application must understand the format
of the data being transferred to it through the Clipboard. A word
processor that accepts an ASCII text string, for example, will not be
likely to understand a set of cells from a spreadsheet.

DDE complements the Clipboard's static data exchange capability by
creating a link between the target document and the source document.
The target document uses this link to dynamically retrieve the
associated data whenever it is updated in the source document.
Therefore, you do not need to remember to update each file that
contains the data.

Microsoft created OLE because there are scenarios that are not served
by either Clipboard or DDE linking--in particular, situations that
involve compound documents. Note that OLE does not replace either DDE
or the Clipboard, but rather complements them by providing additional
functionality.

OLE employs both the Clipboard and DDE linking mechanisms and the
Copy, Paste, and Paste Link commands. That is, you still select and
copy the data from the source, and paste or paste link the data to the
client. The OLE specification defines a set of rules that client
applications can use to decide whether to import pasted information as
an object or as converted data when both options are possible. A new
Paste Special command is also defined to give you explicit control
over the choice of format.


BENEFITS OF OLE
==============

- An application that implements OLE allows you to move away from an
application-centered view of computing, in which the tool used to
complete a task is a single application, and move toward a document-
centered view, in which you employ as many tools as necessary to
complete the job.

- OLE allows applications to specialize in performing one job very
well. A word processing application that implements OLE, for
example, does not necessarily need any illustration tools; users
can put illustrations into their documents and edit those
illustrations using any illustration application that supports OLE.
An example of such a relationship is the one between Microsoft Word
for Windows and the illustration application Microsoft Draw, which
is included with Word.

- Applications are automatically extensible for future data formats
because the content of an object does not matter to the containing
document.

- You can concentrate on the tasks you are performing, instead of on
the applications required to complete the tasks.

- Files can be more compact because linking to objects allows a file
to use an object without having to store that object's data.

- A document can be printed or transmitted without using the
application that originally produced the document.

- Linked objects in a file can be updated dynamically.


FEATURES OF OLE NOT FOUND IN DDE
================================

Feature Description
------- -----------

Extensibility for future The OLE libraries can be updated in
enhancements future releases to support new data
formats, link tracking, and other new
features of OLE as they are developed.

Persistent embedding and The OLE libraries do most of the work
linking of objects of activating objects when an embedded
document is reopened, by
reestablishing the conversation
between a client and server. In
contrast, establishing a DDE link is
either your responsibility (if there
is no link) or the application's
responsibility (if the link is
persistent).

Rendering of common data The OLE libraries assume the burden of
formats rendering common data formats in a
display context. DDE applications must
do this work themselves.

Server rendering of The OLE libraries facilitate the
specialized data formats rendering of specialized data formats
in the client's display context. The
server application or object handler
actually performs the rendering. The
client application has to do very
little work to render the embedded or
linked data in its display context.

Activation of embedded The OLE libraries support activating a
and linked objects server application (the application
associated with the object) to edit a
linked or embedded object to render
data. Activating servers for data
rendering and editing is beyond the
scope of DDE.

Creation of objects and The OLE libraries do most of the work
links from the Clipboard when an application is using the
Windows Clipboard to copy and paste
links or exchange objects. In
contrast, DDE applications must
directly call the Windows Clipboard
functions to perform such operations.

Creation of objects and The OLE libraries provide direct
links from files support for using files to exchange
data. No DDE protocol is defined for
this purpose.


OBJECT LINKING AND EMBEDDING TERMINOLOGY
========================================

COMPOUND DOCUMENT
=================

A compound document is a single OLE document that contains data in
several different formats (for example, a Write document that contains
an embedded drawing and a Word-Art object). A compound document uses
the facilities of different OLE applications to present the different
kinds of data it contains.

Note that a compound document can incorporate links to information,
rather than the information itself. If a document uses links, it
requires minimal storage and is updated automatically whenever the
linked data changes.

When you are working with a compound document, you do not need to know
which data formats are compatible with one another or how to find and
start the applications that created the data. Whenever you choose part
of a compound document, the server application starts automatically.
For example, a compound document could be a brochure that includes
text, charts, cells of financial data, and illustrations. By selecting
different data within the brochure, you can automatically switch
between the word processor, spreadsheet, and graphics programs that
produced its components.


CLIENT
======

A client is a document that contains objects managed by other
applications, or the application that manages such documents. The OLE
client applications that are included with Microsoft Windows 3.1 are
Write and Cardfile. Other examples of OLE clients are Microsoft Word
for Windows and Microsoft Excel for Windows.


SERVER APPLICATION
==================

A server application is an application that provides editing and
rendering services for a linked and embedded object. When you double-
click an object in a client document, the server application is
invoked. A new instance of the server application is started even if
one is already running. (The advantage of starting a new instance of
the server application is that it is initially dedicated to the
current object and does not contain any unrelated document windows.)

Paintbrush is an OLE server application that is included with
Microsoft Windows 3.1. Other examples of OLE server applications are
Microsoft Excel, Microsoft PowerPoint, and Microsoft Draw.


OBJECT
======

An object is any data that can be displayed in a compound document and
manipulated by a user. An object can be anything from a single cell in
a spreadsheet to an entire document or illustration. When an object is
incorporated into a document, it maintains an association with the
application that produced it. OLE applications are "opaque"; that is,
the client application never looks inside the object and therefore
doesn't need to understand its contents. The client simply calls
functions in the OLE libraries when it needs to display an object or
invoke the server application for editing purposes.


EMBEDDED OBJECT
===============

An embedded object is an object that is completely contained within
the client document. For example, when a range of spreadsheet cells
from Microsoft Excel is embedded in a Microsoft Write file, all the
data associated with the cells, including any formulas, is saved as
part of the Write file. The name of the server for the spreadsheet
(Microsoft Excel) is saved along with the data. While working with the
Write file, you can double-click this embedded object (the range of
cells), and Microsoft Excel will start automatically so that you can
edit those cells.


LINKED OBJECT
=============

A linked object is a reference, or link, to data shared by a server
application and a client. If the range of spreadsheet cells from our
example is a linked object instead of an embedded object, the data is
stored in a Microsoft Excel file and only the link to the data is
saved with the Write file. The server then "presents" the data, in the
proper format, to the client document (see "Presentation Data" below).
You can still double-click the object to bring up the server
application (in this case, Microsoft Excel) and edit the information.


PRESENTATION DATA
=================

Presentation data is formatted data sent from the server application
to the client so that the client can display and print the object.
(Presentation data is referenced by an ObjectLink.)


OBJECT CLASS
============

The object class describes the type of information an object contains,
and is assigned by the server application. Examples of Microsoft
object classes include picture (Microsoft Paintbrush), worksheet
(Microsoft Excel for Windows), and document (Microsoft Word for
Windows).


DOCUMENT NAME/ITEM NAME
=======================

The document name and item name identify the object within whatever
server application or document it resides.


OBJECTLINK
==========

An ObjectLink is a DDE and Clipboard format that carries a descriptor
of a source object. The ObjectLink contains the class, document, and
item that identify a linked object. An ObjectLink is represented
internally by three null-terminated strings followed by a null string
(that is, a null character). (This format describes a linked object.)


OWNERLINK
=========

An OwnerLink is a DDE and Clipboard format that carries a descriptor
of the owner of an OLE object. An OwnerLink has the same format as an
ObjectLink, and is used to communicate information about the owner of
an object, which may be distinct from the source. (This format
describes an embedded object.)


NATIVE
======

Native is the format of the data that defines the object; this format
and its interpretation are known only to the server application.
Native format data is transferred between the client and the server
application in the case of embedded objects, where a client document
provides permanent storage and the server application provides editing
features.


VERB
====

The types of actions you can perform on an object are called verbs.
For example, two common verbs for an object are play and edit. The
nature of an object determines the verbs that you can initiate; for
example, you typically play a voice annotation and edit a text file.
The typical use for an object is called the "primary verb." Double-
clicking an object usually executes the action specified by the
primary verb. Other possible verbs for an object are called "secondary
verbs." (Note that many objects support only one verb.)


PACKAGE
=======

A package is a type of OLE object that encapsulates another object, a
file, or a command line inside a graphic representation (such as an
icon or bitmap). When you double-click the graphic object, the OLE
libraries execute the primary verb of the object contained in the
package. The graphic part of a package is always an embedded object,
not a link; thus, the graphic is saved as part of the client document.
The package contents can be an embedded object, a linked object, a
static object, or a command line.

Packages are useful for presenting compact "token" views of large
files or OLE objects. An application can also use packages as
hyperlinks. You can use Microsoft's Object Packager (PACKAGER.EXE), a
packager application that ships with Windows 3.1, to associate a file
or data selection with a particular icon or graphic. (The secondary
verb for a package is "edit package"; when you choose this verb,
Object Packager starts.)


OLE LIBRARIES
=============


DATA TRANSFER IN OLE
====================

Applications use three dynamic-link libraries (DLLs)--OLECLI.DLL,
OLESVR.DLL, and SHELL.DLL--to implement object linking and embedding.
OLECLI.DLL and OLESVR.DLL support object linking and embedding, while
SHELL.DLL supports the system registration database. These libraries
can be included with any products developed under Windows version 3.1
to ensure the products will run under Windows version 3.0.


COMMUNICATION BETWEEN OLE LIBRARIES
===================================

Client applications use functions from the OLE application programming
interface (API) to inform the client library, OLECLI.DLL, that a user
wants to perform an operation on an object. The client library uses
DDE messages to communicate with the server library, OLESVR.DLL. The
server library is responsible for starting and stopping the server
application, directing the interaction with the server application's
callback functions, and maintaining communication with the client
library.

When a server application modifies an embedded object, the server
application notifies the server library of changes. The server library
then notifies the client library, and the client library calls back to
the client application, informing it that the changes have occurred.
Typically, the client application then forces the embedded object to
be redrawn in the document file. If the server application changes a
linked object, the client library is notified that the object has
changed and should be redrawn.


OBJECT HANDLERS
===============

Some server applications implement a fourth kind of OLE library called
an "object handler." Object handlers are DLLs that act as
intermediaries between client and server applications. Typically, an
object handler is supplied by the developer of a server application as
a way of improving performance. For example, an object handler can be
used to redraw a changed object if the presentation data for that

object could not be rendered by the client library.


OBJECT INSERTION METHODS
========================


INSERTING AN EMBEDDED OBJECT
============================

The basic procedure for inserting an embedded object is simple. For
example, to insert a Paintbrush drawing in a Write document:

1. In the server application (Paintbrush), select the drawing, then
choose the Copy command from the Edit menu.

2. Switch to the client application (Write), position the insertion
point at the desired location, and choose the Paste command from
the Edit menu.

Generally, in applications that support OLE, the Paste command will
embed the object that is on the Clipboard, as in the previous example.
Under some circumstances, however, the application may choose not to
embed the object. For example, suppose that the object is represented
on the Clipboard not only by the embedded object format but also by an
alternative format that completely represents the original data and
that the client application knows how to edit. In this case, the
client may choose to insert this editable alternative data rather than
embedding the object. (An example of this concept, though not
practical, is one in which the server and client are the same
application--for example, Word for Windows version 2.0).

Most applications, however, will not be able to provide full editing
capabilities for any alternative format, and they will simply embed
the object and allow the source application to provide editing tools.

Therefore, in most applications that support OLE, when the Clipboard
contains an object from another application, the Paste command embeds
the object in the current document. Note that in applications that do
not support OLE, the Paste command simply inserts a static copy of the
data, without providing easy access to the tools required for later
editing of the data.


INSERTING A LINKED OBJECT
=========================

Inserting links to objects is just as easy as embedding objects. To
continue the example using Paintbrush and Write, suppose that instead
of embedding the drawing, you wanted to insert a link to the drawing.
The following steps would be required:

1. In the server application (Paintbrush), select the drawing and
choose Copy from the Edit menu.

2. Switch to the client application (Write), position the insertion
point at the desired location, and choose Paste Link from the Edit
menu.

This procedure inserts in the Write document a link to the drawing.
The drawing is displayed in the Write document but is stored in the
original Paintbrush file. The link is an "automatic" link, meaning
that whenever the Paintbrush drawing file is changed, the drawing in
the Write file is updated dynamically.

Once a link exists in one document, it can be inserted in other
documents using the Copy and Paste commands. When a linked object,
including the ObjectLink format, is copied, all information describing
the object is copied to the Clipboard as one self-contained unit. When
the object is pasted into a client, it possesses the same attributes
as the original object from which it was copied.


PASTE SPECIAL
=============

The Paste Special command on the Edit menu allows you to control the
manner and format in which an object is inserted into a client
document. For example, you may want the data to be inserted as an
embedded object (rather than translated into a client-editable
format), so that the tools of the server application can easily be
invoked to edit the object. Alternatively, certain special tools or
editing operations might be available only when the data is in a
format that cannot be manipulated by the client application.

The dialog box activated by the Paste Special command enables you to
control the insertion of the object in the following ways:

- The Data Type list allows you to choose the format for the inserted
object. The first choice is generally the "object class name,"
which is the format the data takes in the server application.
Examples of object class names are Microsoft Excel Worksheet,
Microsoft PowerPoint Slide, and Microsoft Paintbrush Bitmap. The
other choices are the formats available on the Clipboard: Formatted
Text (meaning RTF, or rich-text format), Unformatted Text, Picture,
and Bitmap.

- Paste and Paste Link buttons are provided so that you can override
the default choice made by the client application. Both choices
translate the data into the selected format and insert the data
into the document. The Paste button does not establish a link to
the original source of the data. If you have selected the object
class name rather than a data format, the data is inserted as an
embedded object instead of being translated into a client-editable
format. The Paste Link button establishes an automatic link to the
original source of the data.

NOTE: Not all Windows applications contain the Paste Special
command.



INSERT OBJECT
=============

To facilitate the embedding of blank objects, applications may
implement an Insert Object command. In applications that include an
Insert menu (for example, Microsoft Word for Windows), the command
appears on that menu and is labeled "Object." In applications that do
not include an Insert menu, the command appears on the Edit menu and
is called "Insert Object." The dialog box that appears when you choose
the Insert Object command contains the Object Type list, a list of
object names drawn from the registration database maintained by the
system in the REG.DAT file.

To embed an object, select its name from the list, and choose the OK
button (or press ENTER). This activates the server application for the
selected object. The server application then displays a blank window
in which you can create and edit the object. After creating and
editing the object, choose Update from the File menu of the server
application. This command inserts the object where the insertion point
was positioned in the client when the Insert Object command was
chosen. You can then close the server application by choosing Exit
from the File menu, and return to the client document.

NOTE: Not all Windows applications contain the Insert Object
command.


OBJECT ACTIONS
==============


VIEWING OBJECTS
===============

Complex compound documents may contain several linked or embedded
objects (OLE objects), interspersed with objects that are native to
the document. Because OLE objects support different operations than
those supported by the native objects, it is convenient if you can
visually distinguish OLE objects from native ones. For this purpose,
applications should provide visual indications of OLE object
boundaries. The boundaries of a particular object should appear
whenever the object is selected. In addition, applications should
provide a way for all object boundaries to be turned on or off at
once, to facilitate easy viewing of all OLE objects in a document. For
example, applications may reveal object boundaries, as well as other
normally hidden information, through a Hidden Structure command on the
View menu or through a Show All check box in a Preferences dialog box.

The exact method of indicating object boundaries depends on the nature
of the client application and the type of OLE object. Three possible
methods are:

1. Complete borders surrounding the object. For VGA monitors, the
border should be dark gray; for non-VGA monitors, the border should
be a 50-percent gray pattern.

2. Special graphic characters (for example, "{" and "}") at the
beginning and end of the object.

3. Distinctive formatting (for example, a dotted underline) that is
not used elsewhere in the client.


EDITING OBJECTS
===============

Double-Clicking the Object
--------------------------

Once linked or embedded objects are inserted in a document, the
standard user interface provides three methods for editing them. The
first method involves double-clicking the object or object boundary to
invoke a new instance of the server application, with the OLE object
as the active document.

Note that in the following situations, a new instance of the server
application is not started:

- The object is already open in an existing instance of the server
application. In this case, the existing instance should be brought
to the front.

- The server application is a multiple document interface (MDI)
application and is the same as the client application. The
appropriate behavior depends on whether the link is external or
internal.

External links: Suppose that one Word document contains a link to
another Word document. In this case, double-clicking the link
should not start a new instance of Word. Instead, if the document
window for the server document is already open within the current
instance of Word, then that document window should be brought to
the front. If no document window is open for the server document, a
new document window should be opened for it within the current
instance of Word.

Internal links: In contrast to the preceding example, suppose that
the link in the original Word document refers to another part of
that same document. If you double-click the link, the current
document window should scroll to show the source of the link.

When the server application's window opens, the object is loaded into
the window. For embedded objects, the window is initially sized to
show only the portion of the object displayed in the client. You can
resize the window to display additional portions of the embedded
object. When linked objects are used, the entire linked file is
loaded, and the linked portion is selected. You can then modify the
object with the tools provided by the server application.

Updating Objects from Non-MDI Server Applications
-------------------------------------------------

When a non-MDI application (for example, Paintbrush) functions as a
server application for an embedded object, the Save command on the
File menu changes to Update. This change occurs ONLY FOR EMBEDDED
OBJECTS, not for linked objects. The Update command updates the object
in the client but does not close the server application. The server
application remains open so you can make further changes after noting
the effects (for example, repagination) of the update on the client.
Updates to embedded objects can be undone through the Undo command on
the client's Edit menu.

If you attempt to exit the server application without updating the
object, a warning message is displayed, asking if you want to update
the client document ("Update ?").

When an embedded object is being edited, the Save As command on the
File menu can be used to save a copy of the object in a separate file.
If the client file has not yet been updated, the "Update filename>?" warning message is displayed before the Save As dialog box
appears. Choosing New from the File menu also displays the "Update
?" warning message.

When the server closes, the focus returns to the client. If you
attempt to close the client while server documents for that client are
still open, the server documents are closed first, after the usual
checks for unsaved data.

Updating Objects from MDI Server Applications
---------------------------------------------

The procedure for editing and updating objects from MDI server
applications is similar to the procedure for non-MDI server
applications, with the following exceptions.

If the focus changes from the embedded object window to a "normal"
document window (that is, one containing an existing file or a new
document), the Update command on the File menu changes back to Save.
If the embedded object window regains the focus, Save becomes Update
again.

When New is chosen from the File menu, the window containing the
embedded object remains open. Therefore, the "Update filename>?" warning message is not displayed if the client file has
not yet been updated.

Updating Objects Using the Links Command
----------------------------------------

The second method for editing OLE objects involves two commands on the
Edit menu. The Links command produces a dialog box that allows you to
change the type of updating (automatic or manual) for links, update
linked objects, cancel links, repair broken links, and invoke the
verbs associated with linked objects. The Links dialog box should use
object-specific verbs if possible; otherwise, the generic verbs
"activate" and "edit" should be used.

When the Links dialog box opens, the Links list shows each link in the
document; links in the current selection are highlighted. Embedded
objects in the current selection are not shown in the list. As you
select different links in the Links list, the verbs on the two object-
specific buttons will change accordingly.

Below the Links list, the dialog box contains two Update option
buttons: Automatic and Manual. These buttons reflect whether the
currently selected links are automatically updated whenever the linked
file changes or whether they must be manually updated.

The Update Now button in the Links dialog box updates all links
selected in the Links list. The presentations of the linked objects in
the client are updated to reflect the current data in the linked
(server) files.

The Cancel Link button in the Links dialog box permanently breaks the
link between the client and the server application. The linked object
in the client is changed to a picture that can no longer be edited or
updated through the standard OLE techniques. The picture can still be
edited using the cut/copy/paste techniques, but it will not retain all
the data present in the original linked object. No link boundaries
will be displayed for the picture.

The Change Link button in the Links dialog box is dimmed if the
selection in the Links list includes multiple links to multiple files.
Otherwise, if all the selected links are linked to the same file, the
button is active and leads to a dialog box exactly like the File Open
dialog box, except that the title is Change Link (in most
applications). The Change Link dialog box allows you to change the
file to which a link refers. This feature has two uses. First, it
allows broken links to be reestablished. Second, the dialog box allows
a single client that operates on linked data files to be successively
connected to different linked files. This flexibility in providing
data to the client is particularly useful for applications such as
spreadsheets and databases.

In addition to these standard options, an application's Links dialog
box may also include a list box for changing the format in which the
object is displayed.

Updating and Acting Upon Objects
Using the