Microsoft KB Archive/83248

{| = WW0532: Object Linking and Embedding (OLE) =
 * width="100%"|

Last reviewed: May 1, 1997

Article ID: Q83248 3.10 WINDOWS kbfile kbdisplay kbsound kbappnote kbole The information in this article applies to:


 * Microsoft Windows operating system version 3.1

Microsoft Product Support Services offers an Application Note that describes object linking and embedding (OLE), compares OLE to dynamic data exchange (DDE), and explains how to insert, view, and edit embedded objects. This Application Note is titled &quot;Object Linking And Embedding (OLE)&quot; (WW0532).

You can obtain this Application Note from the following sources:


 * Microsoft's World Wide Web Site on the Internet
 * The Internet (Microsoft anonymous ftp server)
 * Microsoft Download Service (MSDL)
 * Microsoft FastTips Technical Library
 * Microsoft Product Support Services

For complete information, see the &quot;To Obtain This Application Note&quot; section at the end of this article.

THE TEXT OF WW0532
Microsoft(R) Product Support Services Application Note (Text File) WW0532: OLE Revision Date: 9/94 No Disk Included The following information applies to Microsoft Windows(TM) and Windows for Workgroups, versions 3.1 and 3.11. | INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY   |
 * ACCOMPANY THIS DOCUMENT (collectively referred to as an Application|
 * Note) IS PROVIDED &quot;AS IS&quot; 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 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(C) 1992-1994 Microsoft Corporation. All Rights Reserved.|
 * Microsoft and MS-DOS are registered trademarks and Windows is a   |
 * trademark of Microsoft Corporation.                               |

INTRODUCTION TO OLE =================== OLE is a technique for implementing &quot;OLE document&quot; 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 current. 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 OLE 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 OLE 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 OLE embedding and | The OLE libraries do most of the OLE linking of objects      | work 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 formats                     | of 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 and   | The OLE libraries support activating linked objects              | a 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 links| The OLE libraries do most of the from the Clipboard          | work 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 links| The OLE libraries provide direct from files                  | support for using files to exchange | data. No DDE protocol is defined for | this purpose.

OLE LINKING AND OLE EMBEDDING TERMINOLOGY =========================================

OLE DOCUMENT
An OLE document is a document that contains data in several different formats (see Figure 1). An OLE document uses the facilities of different OLE applications to present the different kinds of data it contains.

Note that an OLE 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.

 Figure 1. An OLE document

When you are working with an OLE 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 an OLE document, the server application starts automatically. For example, an OLE 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. Figure 1 shows Write acting as a client. 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.)

 Figure 2. Microsoft Draw--an OLE server application

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 an OLE 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 &quot;opaque&quot;; 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.

 Figure 3. The Insert Object dialog box from Microsoft Word for Windows

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 &quot;presents&quot; the data, in the proper format, to the client document (see &quot;Presentation Data&quot; 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 &quot;primary verb.&quot; Double- clicking an object usually executes the action specified by the primary verb. Other possible verbs for an object are called &quot;secondary verbs.&quot; (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 &quot;token&quot; 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 &quot;edit package&quot;; 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 OLE. OLECLI.DLL and OLESVR.DLL support OLE, while SHELL.DLL supports the system registration database. These libraries can be included with any products developed under Windows versions 3.1 and 3.11 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 &quot;object handler.&quot; 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 ob- ject 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 correct 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 OLE 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 OLE embedding objects. To continue the example using Paintbrush and Write, suppose that instead of OLE 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 correct 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 &quot;automatic&quot; 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 &quot;object class name,&quot; 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 OLE 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 &quot;Object.&quot; In applications that do not include an Insert menu, the command appears on the Edit menu and is called &quot;Insert Object.&quot; 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 OLE documents may contain several linked or embedded objects (OLE objects), interspersed with objects that are native to the docu- ment. 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, applica- tions 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 infor- mation, 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, &quot;{&quot; and &quot;}&quot;) at the beginning and end of the object.
 * 3) Distinctive formatting (for example, a dotted underline) that is not used elsewhere in the client.

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 (&quot;Update ?&quot;).

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 &quot;Update ?&quot; warning message is displayed before the Save As dialog box appears. Choosing New from the File menu also displays the &quot;Update ?&quot; 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 &quot;normal&quot; 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 &quot;Update ?&quot; 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 &quot;activate&quot; and &quot;edit&quot; 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 &quot;Object Class Name&quot; Object Command
The third method for editing OLE objects involves the &quot;Object Class Name&quot; Object command on the Edit menu, which allows you to choose one of an object's verbs. If the selection in the document is a single embedded object, the class name placeholder is typically replaced by the class and name of the object (for example, &quot;Microsoft Excel Worksheet&quot;). If an object supports only one verb, the name of the verb should precede the class name in the menu item (for example, &quot;Edit WPDocument Object&quot;). When an object supports more than one verb, choosing this menu item brings up a menu listing each of the verbs associated with the selected object.

REGISTRATION ============ When a server application is installed, it registers itself as an OLE server application with the system registration database (REG.DAT). This database is supported by SHELL.DLL. To register itself as an OLE server application, a server application records in the database that it supports one or more OLE protocols. The protocols currently supported are &quot;StdFileEditing&quot; and &quot;StdExecute.&quot; StdFileEditing is the protocol for linked and embedded objects. StdExecute is used only by applications that support the OleExecute function. The entries in the registration database are used whenever an application or library needs information about an OLE server application. For example, client applications that support the Insert Object command refer to the database in order to list the OLE server applications that could provide a new object. The client applications also use the registration database to retrieve the name of the server application for the Paste Special dialog box.

The registration database stores key/value pairs, where keys and values are null-terminated strings. Keys are hierarchically structured, with the names of the components and keys separated by backslash (\) characters. To be available for OLE transactions, a server application should register the key/value pairs shown in the following example when the server application is installed. The class name and server application path should be registered for every class the server application supports. If a class has an object-handler library, it should be registered using the &quot;handler&quot; keyword. An application should also register all the verbs its class or classes support. An application's verbs must be sequential; for example, if an object supports three verbs, the primary verb is 0 and the other verbs must be 1 and 2.

The following example shows the form of the key/value pairs as they would be added to a database using the Registration Information Editor, REGEDIT.EXE. An application could also use the registration API to add this information to the database.

HKEY_CLASSES_ROOT\ = readable version of class name HKEY_CLASSES_ROOT\<.ext> = HKEY_CLASSES_ROOT\ \protocol\StdFileEditing\server = HKEY_CLASSES_ROOT\ \protocol\\StdFileEditing\handler = HKEY_CLASSES_ROOT\ \protocol\StdFileEditing\verb\0 = HKEY_CLASSES_ROOT\ \protocol\StdFileEditing\verb\1 = Server applications that support the OleExecute function also add the following line to REG.DAT: HKEY_CLASSES_ROOT\ \protocol\StdExecute\Server = Server applications can register data formats that they accept on calls to the OleSetData function or that they can return when a client calls the OleRequestData function. Clients can use this registered information to initialize newly created objects or to manipulate data with the server application. Client applications should not depend on the requested data format because the calls can be rejected by the server application. For compatibility with earlier applications, the system registration service also reads and writes registration information in the [embedding] section of the WIN.INI initialization file. A sample [embedding] section follows:

[embedding] ExcelWorksheet=Worksheet created by Microsoft Excel,Excel Worksheet, EXCEL.EXE, picture WordDocument=Word Document,Word Document,C:\WINWORD\WINWORD.EXE, picture SoundRec=Sound Recorder Waveform Audio,Sound,SoundRec.exe,picture Package=Package,Package,packager.exe,picture PBrush=Paintbrush Picture,Paintbrush Picture,pbrush.exe,picture The syntax is: =,,/, [picture] The keyword &quot;picture&quot; indicates that the server application can produce metafiles for use when rendering objects. Note that a server application can register the entire path for its executable file, or register only the file's name and arguments. Registering only the filename without the path will cause the server application to fail if the application is installed in a directory that is not mentioned in the PATH environment variable in the AUTOEXEC.BAT file. Generally, registering the path and filename is recommended instead of registering only the filename. In the above example, you may want to verify that the directory containing EXCEL.EXE is mentioned in your PATH environment variable.

TO OBTAIN THIS APPLICATION NOTE
You can find WW0532.EXE (size: 26124 bytes) , a self-extracting file, on the following services:   Microsoft's World Wide Web Site on the Internet On the www.microsoft.com home page, click the Support icon. Click Knowledge Base, and select the product. Enter kbfile #|WW0532.EXE (size: 26124 bytes), and click GO! Open the article, and click the button to download the file.   Internet (anonymous FTP) ftp ftp.microsoft.com Change to the Softlib/Mslfiles folder. Get WW0532.EXE (size: 26124 bytes)   Microsoft Download Service (MSDL) Dial (425) 936-6735 to connect to MSDL Download WW0532.EXE (size: 26124 bytes) 

For additional information about downloading, please see the following article in the Microsoft Knowledge Base: ARTICLE-ID: Q119591 TITLE    : How to Obtain Microsoft Support Files from Online Services You can have this Application Note mailed or faxed to you from the automated Microsoft FastTips Technical Library, which you can call 24 hours a day, 7 days a week at (800) 936-4200. NOTE: The FastTips Technical Library is available only to customers within the U.S. and Canada. If you are unable to access the source(s) listed above, you can have this Application Note mailed or faxed to you by calling Microsoft Product Support Services Monday through Friday, 6:00 A.M. to 6:00 P.M. Pacific time at (425) 637-7098. If you are outside the United States, contact the Microsoft subsidiary for your area.
 * }