| OLESTATUS OleGetData(lpObject, cfFormat, phData) | |||||
| LPOLEOBJECT lpObject; | /* pointer to object to query | */ | |||
| OLECLIPFORMAT cfFormat; | /* format for retrieved data | */ | |||
| HANDLE FAR* phData; | /* pointer to memory to contain data | */ | |||
The OleGetData function retrieves data in the requested format from the specified object and supplies a handle to a memory 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.
phData
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 can 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 a format that is not one of the OLE formats—for example, CF_BITMAP—the phData parameter points to a GDI object, not a memory object, when the function returns. In this case, the application should call the DeleteObject function when OleGetData returns OLE_WARN_DELETE_DATA.
OleEnumFormats, OleSetData, RegisterClipboardFormat