OLE Clipboard Formats and Conventions

ID: Q83659

The information in this article applies to:

SUMMARY

Because most OLE server applications can support a number of data formats, the OLE specification defines a data format convention that determines which data format a server application uses to place data on the clipboard. This article explains the Native, OwnerLink, and ObjectLink OLE clipboard data formats.

MORE INFORMATION

An OLE server application must call the RegisterClipboardFormat function to register the Native, OwnerLink, and ObjectLink OLE data formats. An OLE server application provides the data, which an OLE client application stores. The OLE libraries use the data to reconstruct an object when required.

Contents of OLE Formats

The Native data format presents the server application's internal data structures. In the process of opening and editing an embedded object, the server application reconstructs the object from native data. The structure of the data is defined only by the server application.

The OwnerLink data format describes an embedded object, identifying the class, document name, and name of an object. Each of these data is a null-terminated string. A server application creates OwnerLink data by concatenating the three identifying strings, with a null terminator on each, and appending a final null terminator. The following string is an example of OwnerLink data for a portion of a bitmap saved from Windows Paintbrush: 

   Paintbrush Picture\0Unused\0(20,10)-(90,100)\0\0
In the example above, Paintbrush Picture identifies the class of the object. Because the OwnerLink data format describes an embedded object, the document name field is not used in OLE version 1.0. The application specifies "Unused" as a place holder. The coordinates in the object name field describe the object. Other applications can use a name such as "Figure #1234."

The ObjectLink data format describes a linked object. While it contains the same data as the OwnerLink format, the document name and object name fields are much more important. For example, a linked object that originated in Paintbrush might be described with ObjectLink data as in the following: 

   Paintbrush Picture\0c:\\BITMAP.BMP\0(20,10)-(90,100)\0\0
The class name field is the same as the OwnerLink data. In this format, the document name identifies the actual filename of the link, and the object name identifies the portion of the file that makes up the object. Because a linked object is not required to refer to the entire file, the object name must identify the portion of the file that makes up the actual object. Another application may use a different object name, such as a range of cells in a spreadsheet, a slide number in a presentation, or a page number and line number in a document.

Placing OLE Data on the Clipboard

When the user cuts or copies data to the clipboard, an OLE server application renders the data to the clipboard. The OLE server must render the data in the three OLE formats, as appropriate. If the server can support other data formats, it can also render the data in these formats. The following list presents the data formats. The format that preserves the most information is listed first; subsequent formats lose fidelity.

A server application renders data in OwnerLink format only when it can provide an embedded object. It renders data in ObjectLink format only when the server has a known filename in which the object is stored, and only when the user is copying the data to the clipboard. If the object is new and it does not have a known filename, or if the user is cutting the data to the clipboard, the server does not provide the ObjectLink data format.

The CF_BITMAP, CF_DIB, and CF_METAFILEPICT formats provide a static graphic representation of an object. An OLE server application should always provide data in CF_METAFILEPICT format.

Additional reference words: 1.00 KBCategory: kbole kbprg KBSubcategory: LeOneCli LeOneSvr

Last Reviewed: February 17, 1995