OleCreateFromData - OLE Programmer's Reference (ole.hlp)

OleCreateFromData

Creates an embedded object from a data transfer object retrieved either from the clipboard or as part of an OLE drag and drop operation. It is intended to be used to implement a paste from an OLE drag and drop operation.

HRESULT OleCreateFromData(

LPDATAOBJECT pSrcDataObj,	//Data transfer object holding data used to create new object
REFIID riid,	//Interface to be used to communicate with the new object
DWORD renderopt,	//Value from OLERENDER
LPFORMATETC pFormatEtc,	//Depending on renderopt, pointer to value from FORMATETC
LPOLECLIENTSITE pClientSite,	//Points to instance of IOleClientSite
LPSTORAGE pStg,	//Points to instance of IStorage used to store object
LPVOID FAR* ppvObj	//Receives a pointer to the interface requested in riid
);

Parameters
pSrcDataObj

Points to the data transfer object that holds the data from which the object is created.
riid

Identifies the interface the caller later uses to communicate with the new object (usually IID_IOleObject).

renderopt

A value from the enumeration OLERENDER that indicates the locally cached drawing or data retrieval capabilities the newly created object is to have. Additional considerations are described in the Comments section below.

pFormatEtc

A value from the enumeration OLERENDER that indicates the locally cached drawing or data retrieval capabilities the newly created object is to have. The OLERENDER value chosen affects the possible values for the pFormatEtc parameter.

pClientSite

Points to an instance of IOleClientSite, the primary interface through which the object will request services from its container. May be NULL.

pStg

Points to an instance of the IStorage interface to be used as the storage for the object. This parameter may not be NULL.

ppvObj

Receives a pointer to the interface requested in riid on the newly created object on return.

Return Values
S_OK

Indicates that the embedded object was created successfully.

OLE_E_STATIC

Indicates OLE can create only a static object.

DV_E_FORMATETC

Indicates no acceptable formats are available for object creation.

Comments
The OleCreateFromData function creates an embedded object from an instance of the IDataObject interface. The data object in this case is either the type retrieved from the clipboard with a call to the OleGetClipboard function or is part of an OLE drag and drop operation (the data object is passed to a call to IDropTarget::Drop).

If either the FileName or FileNameW clipboard format (CF_FILENAME) is present in the data transfer object, and CF_EMBEDDEDOBJECT or CF_EMBEDSOURCE do not exist, OleCreateFromData creates a package containing the indicated file. (Generally, it takes the first available format.) The Microsoft Windows NT File Manager places these formats on the clipboard when the user selects the File / Copy To Clipboard menu command.

If OleCreateFromData cannot create a package, it tries to create an object using the CF_EMBEDDEDOBJECT format. If that format is not available, OleCreateFromData tries to create it with the CF_EMBEDSOURCE format. If neither of these formats is available and the data transfer object supports the IPersistStorage interface, OleCreateFromData calls IPersistStorage::Save to have the object save itself.

If an existing linked object is selected, then copied, it appears on the clipboard as just another embeddable object. Consequently, a paste operation that invokes OleCreateFromData may create a linked object. After the paste operation, the container should call the QueryInterface function, requesting IID_IOleLink, to determine if a linked object was created.

Use the renderopt and pFormatetc parameters to control the caching capability of the newly created object. For information on how to determine what is to be cached, refer to the OLERENDER enumeration for a description of the interaction between renderopt and pFormatetc. However, values of renderopt also specifically affect the way OleCreateFromData initializes the cache.

When OleCreateFromData uses either the CF_EMBEDDEDOBJECT or the CF_EMBEDSOURCE clipboard format to create the embedded object, the main difference between the two is where the cache-initialization data is stored:

CF_EMBEDDEDOBJECT indicates that the source is an existing embedded object. It already has in its cache the appropriate data, and OLE uses this data to initialize the cache of the new object.
CF_EMBEDSOURCE indicates that the source data object contains the cache initialization information in formats other than CF_EMBEDSOURCE. OleCreateFromData uses these to initialize the cache of the newly embedded object.

The renderopt values affect cache initialization as follows:

Value	Description
OLERENDER_DRAW & OLERENDER_FORMAT	If the presentation information to be cached is currently present in the appropriate cache initialization pool, it is used. (Appropriate locations are in the source data object cache for CF_EMBEDDEDOBJECT, and in the other formats in the source data object for CF_EMBEDSOURCE.) If the information is not present, the cache is initially empty, but will be filled the first time the object is run. No other formats are cached in the newly created object.
OLERENDER_NONE	Nothing is to be cached in the newly created object. If the source has the CF_EMBEDDEDOBJECT format, any existing cached data that has been copied is removed.
OLERENDER_ASIS	If the source has the CF_EMBEDDEDOBJECT format, the cache of the new object is to contain the same cache data as the source object. For CF_EMBEDSOURCE, nothing is to be cached in the newly created object. This option should be used by more sophisticated containers. After this call, such containers would call IOleCache::Cache and IOleCache::Uncache to set up exactly what is to be cached. For CF_EMBEDSOURCE, they would then also call IOleCache::InitCache.