6.3.11 Creating Objects

A client application can put linked and embedded objects in a document by pasting them from the clipboard, creating them from a file, copying them from other objects, or by starting a server application to create them directly.

6.3.11.1 Object-Creation Functions

Each of the following functions creates an embedded or linked object in a specified document:

Function Description

OleClone Creates an exact copy of an object.
OleCopyFromLink Creates an embedded object that is a copy of a linked object.
OleCreate Creates an embedded object of a specified class.
OleCreateFromClip Creates an object from the clipboard. This function typically creates an embedded object.
OleCreateFromFile Creates an object by using the contents of a file. This function typically creates an embedded object.
OleCreateFromTemplate Creates an embedded object by using another object as a template.
OleCreateInvisible Creates an object without displaying the server application to the user.
OleCreateLinkFromClip Creates an object by using information on the clipboard. This function typically creates a linked object.
OleCreateLinkFromFile Creates an object by using the contents of a file. This function typically creates a linked object.
OleObjectConvert Creates an object that supports a specified protocol by converting an existing object.

Each of these functions requires a parameter that points to an OLEOBJECT structure when the function returns. Server applications often create an OLEOBJECT structure whenever an object is created; OLEOBJECT points to functions that describe how the server interacts with the object. Before the client library gives the client application a pointer to this structure, the library includes with the structure some internal information corresponding to the OwnerLink or ObjectLink data. This internal information allows the client library to identify the correct server when an OLE function such as OleActivate passes it a pointer to an OLEOBJECT structure. For more information about the OLEOBJECT structure, see Section 6.4.1, “Starting a Server Application.”

Each new object must have a name that is unique to the client document. Although meaningful object names can be helpful, some applications assign unique object names simply by incrementing a counter for each new object. For more information about object names, see Section 6.3.3, “Document Management.”

If a client application implements the Insert Object command, it should use the registration database to find out what OLE servers are available and then list those servers for the user. When the user selects one of the servers and chooses the OK button, the client can use the OleCreate function to create an object at the current position.

The OleCopyFromLink, OleCreate, and OleCreateFromTemplate functions always create an embedded object. The other object-creation functions can create either an embedded object or a linked object, depending on the order and type of available data.

If a client application's callback function receives the OLE_RELEASE notification after the client calls the OleCreate or OleCreateFromFile function, the client should respond by calling the OleQueryReleaseError function. If OleQueryReleaseError shows that there was an error when the object was created, the client application should delete the object.

Whenever an object-creation function returns OLE_WAIT_FOR_RELEASE, the calling application should either wait for the OLE_RELEASE notification or notify the user that the object cannot be created. For more information, see Section 6.3.6, “Asynchronous Operations.”

If a client application accepts files dropped from File Manager, it should respond to the WM_DROPFILES message by calling the OleCreateFromFile function and specifying Packager for the lpszClass parameter.

6.3.11.2 Paste and Paste Link Commands

A client application should follow these steps to create an embedded or linked object by pasting from the clipboard:

1.Call the OleQueryCreateFromClip function to determine whether to enable the Paste command. If this function fails when StdFileEditing is specified for the lpszProtocol parameter, call it again, specifying Static.

2.Call the OleQueryLinkFromClip function to determine whether to enable the Paste Link command.

If the user chooses the Paste command, open the clipboard and call the OleCreateFromClip function.

If the user chooses Paste Link, open the clipboard and call the OleCreateLinkFromClip function.

3.Close the clipboard.

4.Call the OleQueryType function to determine the kind of object created by the creation function. (Depending on the order of clipboard data, OleCreateFromClip can sometimes create a linked object and OleCreateLinkFromClip can sometimes create an embedded object.)

The client application should put the pasted data or object into the document at the current position. The client should select the object so that the user can work with it immediately. If both the OleQueryCreateFromClip and OleQueryLinkFromClip functions fail but there is data on the clipboard that the client can interpret, the client should enable the Paste command.

If the information on the clipboard is incomplete—for example, if Native data is not accompanied by the OwnerLink format—the Paste command should insert a static object into the document. (A static object consists of the presentation data for an object; it cannot be edited by using standard OLE techniques. Attempts to open static objects fail and generate no notifications.)

If the client application implements the Paste Special command, it should use the EnumClipboardFormats function to produce a list of data formats on the clipboard. The client should also check the registration database to find the full name of the server application. The Paste Link button in the Paste Special dialog box works in exactly the same way as the Paste Link command on the Edit menu.

If the DDE Link format is available on the clipboard instead of ObjectLink format, the client application should perform the same link operation that it supported prior to the implementation of OLE.