Share via


IDataObject::GetDataHere

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method is 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.

Syntax

HRESULT GetDataHere(
  FORMATETC* pFormatetc,
  STGMEDIUM* pmedium
);

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.

    Only the following TYMED values are valid: TYMED_STORAGE, TYMED_STREAM, TYMED_HGLOBAL, and TYMED_FILE.

  • pmedium
    [in, 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 Value

This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY.

The following table shows the additional return values for this method.

Value Description

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

The 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.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

IDataObject::GetData
FORMATETC
STGMEDIUM