OLESTATUS OleCreateFromFile(lpszProtocol, lpClient, lpszClass, lpszFile,
lhClientDoc, lpszObjname, lplpObject,
renderopt, cfFormat)
LPCSTR lpszProtocol;
LPOLECLIENT lpClient;
LPCSTR lpszClass;
LPCSTR lpszFile;
LHCLIENTDOC lhClientDoc;
LPCSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;
The OleCreateFromFile function creates an embedded object from the contents of a named file.
| Parameter | Description |
| lpszProtocol | Points to a null-terminated string specifying the name of the protocol required for the new embedded object. Currently this value can be "StdFileEditing" (the name of the OLE 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 client DLL 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. |
| 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 the forward-slash ("/") character. |
| lplpObject | Points to a variable where the client DLL 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_none | The client DLL does not obtain any presentation data and does not draw the object. | |
| olerender_draw | The client calls the OleDraw function, and the client DLL obtains and manages presentation data. | |
| olerender_format | The client calls the OleGetData function to retrieve data in a specific format. The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter. |
| cfFormat | Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to the OleGetData function. If this clipboard format is CF_METAFILEPICT, CF_DIB, or CF_BITMAP, the DLL manages the data and draws the object. The client DLL does not support drawing for any other formats. |
When a client application calls the OleCreateFromFile function, the server is started to render the Native and presentation data and then closed. (If the server and document are already open, this function simply retrieves the information, without closing the server.) The server does not show the object to the user for editing.
The olerender_none rendering option is typically used to support hyperlinks. With this option, the client does not call the OleDraw function and calls the OleGetData function 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 the OleDraw function) 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.
If a client application accepts files dropped from File Manager, it should respond to the WM_DROPFILES message by calling OleCreateFromFile and specifying "Packager" for the lpszClass parameter.
The return value is OLE_OK if successful; otherwise, it could be one of the following:
OLE_ERROR_CLASS
OLE_ERROR_HANDLE
OLE_ERROR_MEMORY
OLE_ERROR_NAME
OLE_ERROR_PROTOCOL
OLE_WAIT_FOR_RELEASE
See AlsoOleCreate, OleCreateFromTemplate, OleDraw, OleGetData