IDataObject::GetDataHere
Called by a
data consumer to obtain data from a source data object. This method differs
from the GetData method in that the caller must allocate and free the
specified storage medium.
HRESULT GetDataHere(
|
FORMATETC
* pFormatetc, |
//Pointer to the FORMATETC structure |
|
STGMEDIUM
* pmedium |
//Pointer to the STGMEDIUM structure |
|
); |
|
Parameters
pFormatetc
[in] Pointer
to the FORMATETC structure that defines the format, medium, and target device
to use when passing the data. Only one medium can be specified in TYMED, and only the following
TYMED values are valid: TYMED_STORAGE, TYMED_STREAM, TYMED_HGLOBAL, or
TYMED_FILE.
pmedium
[out] Pointer
to the STGMEDIUM structure that defines the storage medium containing the data
being transferred. The medium must be allocated by the caller and filled in by IDataObject::GetDataHere.
The caller must also free the medium. The implementation of this method must
always supply a value of NULL for the punkForRelease member of the
STGMEDIUM structure to which this parameter points.
Return Values
This method
supports the standard return values E_INVALIDARG, E_UNEXPECTED, and
E_OUTOFMEMORY, as well as the following:
S_OK
Data was
successfully retrieved and placed in the storage medium provided.
DV_E_LINDEX
Invalid value
for lindex; currently, only -1 is supported.
DV_E_FORMATETC
Invalid value
for pFormatetc.
DV_E_TYMED
Invalid tymed
value.
DV_E_DVASPECT
Invalid dwAspect
value.
OLE_E_NOTRUNNING
Object
application is not running.
STG_E_MEDIUMFULL
The medium
provided by the caller is not large enough to contain the data.
Remarks
The IDataObject::GetDataHere
method is similar to IDataObject::GetData, except that the caller must both allocate and
free the medium specified in pmedium. GetDataHere renders the
data described in a FORMATETC
structure and copies the data into that caller-provided STGMEDIUM structure. For example, if
the medium is TYMED_HGLOBAL, this method cannot resize the medium or allocate a
new hGlobal.
Some media
are not appropriate in a call to GetDataHere, including GDI types such
as metafiles. The GetDataHere method cannot put data into a
caller-provided metafile. In general, the only storage media it is necessary to
support in this method are TYMED_ISTORAGE, TYMED_ISTREAM, and TYMED_FILE.
When the
transfer medium is a stream, OLE makes assumptions about where the data is
being returned and the position of the stream s seek pointer. In a GetData
call, the data returned is from stream position zero through just before the
current seek pointer of the stream (that is, the position on exit). For GetDataHere,
the data returned is from the stream position on entry through just before the
position on exit.
See Also