OleCreateFromFileEx function (ole2.h)

Extends OleCreateFromFile functionality by supporting more efficient instantiation of objects in containers requiring caching of multiple presentation formats or data, instead of the single format supported by OleCreateFromFile.

Syntax

HRESULT OleCreateFromFileEx(
  [in]  REFCLSID        rclsid,
  [in]  LPCOLESTR       lpszFileName,
  [in]  REFIID          riid,
  [in]  DWORD           dwFlags,
  [in]  DWORD           renderopt,
  [in]  ULONG           cFormats,
  [in]  DWORD           *rgAdvf,
  [in]  LPFORMATETC     rgFormatEtc,
  [in]  IAdviseSink     *lpAdviseSink,
  [out] DWORD           *rgdwConnection,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Parameters

[in] rclsid

This parameter is reserved and must be CLSID_NULL.

[in] lpszFileName

Pointer to the name of the file from which the new object should be initialized.

[in] riid

Reference to the identifier of the interface of the object to return.

[in] dwFlags

This parameter can be 0 or OLECREATE_LEAVERUNNING (0x00000001).

[in] renderopt

Value taken from the OLERENDER enumeration.

[in] cFormats

When renderopt is OLERENDER_FORMAT, indicates the number of FORMATETC structures in the rgFormatEtc array, which must be at least one. In all other cases, this parameter must be zero.

[in] rgAdvf

When renderopt is OLERENDER_FORMAT, points to an array of DWORD elements, each of which is a combination of values from the ADVF enumeration. Each element of this array is passed in as the advf parameter to a call to either IOleCache::Cache or IDataObject::DAdvise, depending on whether pAdviseSink is NULL or non-NULL (see below). In all other cases, this parameter must be NULL.

[in] rgFormatEtc

When renderopt is OLERENDER_FORMAT, points to an array of FORMATETC structures. When pAdviseSink is NULL, each element of this array is passed as the pFormatEtc parameter to a call to the object's IOleCache::Cache. This populates the data and presentation cache managed by the objects in-process handler (typically the default handler) with presentation or other cacheable data. When pAdviseSink is non-NULL, each element of this array is passed as the pFormatEtc parameter to a call to IDataObject::DAdvise. This allows the caller (typically an OLE Container) to do its own caching or processing of data received from the object.

[in] lpAdviseSink

When renderopt is OLERENDER_FORMAT, may be either a valid IAdviseSink pointer, indicating custom caching or processing of data advises, or NULL, indicating default caching of data formats.

[out] rgdwConnection

Location to return the array of dwConnection values returned when the pAdviseSink interface is registered for each advisory connection using IDataObject::DAdvise, or NULL if the returned advisory connections are not needed. This parameter must be NULL if pAdviseSink is NULL.

[in] pClientSite

Pointer to the primary interface through which the object will request services from its container. This parameter may be NULL, in which case it is the caller's responsibility to establish the client site as soon as possible using IOleObject::SetClientSite.

[in] pStg

Pointer to the storage to use for the object and any default data or presentation caching established for it.

[out] ppvObj

Address of output pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvObj contains the requested interface pointer on the newly created object.

Return value

This function returns S_OK on success. Other possible values include the following.

Return code Description
E_NOINTERFACE
The provided interface identifier is invalid.
E_INVALIDARG
One or more parameters are invalid.

Remarks

The following call to OleCreateFromFile:

OleCreateFromFile(rclsid, lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

is equivalent to the following call to OleCreateFromFileEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(rclsid, lpszFileName, riid, renderopt, 1, &advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Existing instantiation functions (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile, and OleCreateLinkFromData) create only a single presentation or data format cache in the default cache location (within the '\001OlePresXXX' streams of the passed-in IStorage), during instantiation. Plus, these caches must be created when the object next enters the running state. Because most applications require caching at least two presentations (screen and printer) and may require caching data in a different format or location from the handler, applications must typically launch and shut down the object server multiple times in order to prime their data caches during object creation, i.e., Insert Object, Insert Object from File, and Paste Object.

Extended versions of these creation functions solve this problem. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, and OleCreateLinkFromDataEx, contain the following new parameters: dwFlags to indicate additional options, cFormats to indicate how many formats to cache, rgAdvf, from the ADVF enumeration, to specify the advise flags for each format to be cached, pAdviseSink to indicate whether presentation (default-handler) or data (non-default-handler) caching is required, rgdwConnection to return IDataObject::DAdvise cookies, and rgFormatEtc, an array of formats rather than a single format.

Containers requiring that multiple presentations be cached on their behalf by the object's handler can simply call these functions and specify the number of formats in cFormats, the ADVF flags for each format in rgAdvf, and the set of formats in rgFormatEtc. These containers pass NULL for pAdviseSink.

Containers performing all their own data- or presentation-caching perform these same steps, but pass a non-NULLpAdviseSink. They perform their own caching or manipulation of the object or data during IAdviseSink::OnDataChange. Typically, such containers never establish the advisory connections with ADVF_NODATA, although they are not prevented from doing so.

These new functions are for OLE Compound Documents. Using these functions, applications can avoid the repeated launching and initialization steps required by the current functions. They are targeted at OLE Compound Document container applications that use default data- and presentation-caching, and also at applications that provide their own caching and data transfer from the underlying IDataObject::DAdvise support.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header ole2.h
Library Ole32.lib
DLL Ole32.dll

See also

ADVF

FORMATETC

IAdviseSink::OnDataChange

IDataObject::DAdvise

IOleCache::Cache

IOleObject::SetClientSite

IStorage

OLERENDER

OleCreateFromFile