| #include <ole.h> |
| OLESTATUS OleGetData(lpObject, cfFormat, lphData) | |||||
| LPOLEOBJECT lpObject; | /* address of object to query | */ | |||
| OLECLIPFORMAT cfFormat; | /* format for retrieved data | */ | |||
| HANDLE FAR* lphData; | /* address of memory to contain data | */ | |||
The OleGetData function retrieves data in the requested format from the specified object and supplies the handle of a memory or graphics device interface (GDI) object containing the data.
lpObject
Points to the object from which data is retrieved.
cfFormat
Specifies the format in which data is returned. This parameter can be one of the predefined clipboard formats or the value returned by the RegisterClipboardFormat function.
lphData
Points to the handle of a memory object that contains the data when the function returns.
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_BLANK
OLE_ERROR_FORMAT
OLE_ERROR_OBJECT
OLE_WARN_DELETE_DATA
If the OleGetData function returns OLE_WARN_DELETE_DATA, the client application owns the data and should free the memory associated with the data when the client has finished using it. For other return values, the client should not free the memory or modify the data, because the data is controlled by the client library. If the application needs the data for long-term use, it should copy the data.
The OleGetData function typically returns OLE_WARN_DELETE_DATA if an object handler generates data for an object that the client library cannot interpret. In this case, the client application is responsible for controlling that data.
When the OleGetData function specifies CF_METAFILE or CF_BITMAP, the lphData parameter points to a GDI object, not a memory object, when the function returns. OleGetData supplies the handle of a memory object for all other formats.