OleCreateLinkFromFile

3.1

#include <ole.h>

OLESTATUS OleCreateLinkFromFile(lpszProtocol, lpClient, lpszClass, lpszFile, lpszItem, lhClientDoc, lpszObjname, lplpObject, renderopt, cfFormat)
LPCSTR lpszProtocol;	/* address of string for protocol name	*/
LPOLECLIENT lpClient;	/* address of client structure	*/
LPCSTR lpszClass;	/* string for class name	*/
LPCSTR lpszFile;	/* address of string for filename	*/
LPCSTR lpszItem;	/* address of string for document part to link	*/
LHCLIENTDOC lhClientDoc;	/* long handle of client document	*/
LPCSTR lpszObjname;	/* address of string for object name	*/
LPOLEOBJECT FAR* lplpObject;	/* address of pointer to new object	*/
OLEOPT_RENDER renderopt;	/* rendering options	*/
OLECLIPFORMAT cfFormat;	/* clipboard format	*/

The OleCreateLinkFromFile function creates a linked object from a file that contains an object. If necessary, the library starts the server to render the presentation data, but the object is not shown in the server for editing.

Parameters

lpszProtocol

Points to a null-terminated string specifying the name of the required protocol. Currently, this value can be StdFileEditing (the name of the object linking and embedding protocol).

lpClient

Points to an OLECLIENT structure allocated and initialized by the client application. This pointer is used to locate the callback function and is passed in callback notifications.

lpszClass

Points to a null-terminated string specifying the name of the class for the new object. If this value is NULL, the library uses the extension of the filename pointed to by the lpszFile parameter to find the class name for the object.

lpszFile

Points to a null-terminated string specifying the name of the file containing the object.

lpszItem

Points to a null-terminated string identifying the part of the document to link to. If this value is NULL, the link is to the entire document.

lhClientDoc

Identifies the client document in which the object is being created.

lpszObjname

Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain a slash mark (/).

lplpObject

Points to a variable where the library will store the long pointer to the new object.

renderopt

Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value

Meaning

olerender_draw	The client calls the OleDraw function, and the library obtains and manages presentation data.
olerender_format	The client calls the OleGetData function to retrieve data in a specific format. The library obtains and manages the data in the requested format, as specified by the cfFormat parameter.
olerender_none	The client library does not obtain any presentation data and does not draw the object.

cfFormat

Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to OleGetData. If this clipboard format is CF_METAFILEPICT, CF_DIB, or CF_BITMAP, the library manages the data and draws the object. The library does not support drawing for any other formats.

Return Value

The return value is OLE_OK if the function is successful. Otherwise, it is an error value, which may be one of the following:

OLE_ERROR_CLASS
OLE_ERROR_HANDLE
OLE_ERROR_MEMORY
OLE_ERROR_NAME
OLE_ERROR_PROTOCOL
OLE_WAIT_FOR_RELEASE

Comments

The olerender_none rendering option is typically used to support hyperlinks. With this option, the client does not call OleDraw and calls OleGetData only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option, the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls OleDraw), and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a private presentation data format, or several different formats that it can choose among dynamically. Future implementations of object linking and embedding (OLE) may also exploit the flexibility that is inherent in this option.