Extends OleCreate 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 OleCreate.
HRESULT OleCreateEx(
REFCLSID rclsid, //Class of object to create
REFIID riid, //Reference to the identifier of the
// interface of object to return
DWORD dwFlags, //Value from OLECREATE
// enumeration
DWORD renderopt, //Value from OLERENDER
// enumeration
ULONG cFormats, //Number of FORMATETC
// structures in rgFormatEtc
DWORD rgAdvf, //Points to an array of cFormats DWORD
// elements
LPFORMATETC rgFormatEtc, //Points to an array of cFormats
// FORMATETC structures; NULL otherwise
LPADVISESINK pAdviseSink, //IAdviseSink pointer
// (custom caching); NULL (default
// caching); NULL otherwise
DWORD* rgdwConnection, //Location to return array of dwConnection
// values
LPOLECLIENTSITE pClientSite,
//Pointer to the primary interface the
// object will use to request services
LPSTORAGE pStg, //Pointer to storage to use for object
LPVOID FAR* ppvObj //Address of output variable that receives
// the interface pointer requested in riid
);
This function supports the standard return value E_INVALIDARG, as well as the following:
The following call to OleCreate:
OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);
is equivalent to the following call to OleCreateEx:
DWORD advf = ADVF_PRIMEFIRST;
OleCreateEx(rclsid, 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. Since 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 pFormatEtc, 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 pFormatEtc. These containers pass NULL for pAdviseSink.
Containers performing all their own data- or presentation-caching perform these same steps, but pass a non-NULL pAdviseSink. 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.
Windows NT: Use version 4.0 or later.
Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in ole2.h.
Import Library: Included as a resource in ole32.dll.
OleCreate, IOleCache::Cache, IDataObject::DAdvise, IOleObject::SetClientSite, IAdviseSink::OnDataChange, IStorage, OLERENDER, FORMATETC, ADVF