Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method is called by a data consumer to obtain data from a source data object. The GetDatamethod renders the data described in the specified FORMATETCstructure and transfers it through the specified STGMEDIUMstructure. The caller then assumes responsibility for releasing the STGMEDIUMstructure.

Syntax 

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

Parameters

pFormatetc

[in] Pointer to the FORMATETCstructure that defines the format, medium, and target device to use when passing the data. It is possible to specify more than one medium by using the Boolean ORoperator, allowing the method to choose the best medium among those specified.

pmedium

[out] Pointer to the STGMEDIUMstructure that indicates the storage medium containing the returned data through its TYMEDmember and the responsibility for releasing the medium through the value of its pUnkForReleasemember.

If pUnkForReleaseis NULL, the receiver of the medium is responsible for releasing it; otherwise, pUnkForReleasepoints to the IUnknowninterface on the appropriate object so its Releasemethod can be called.

The medium must be allocated and filled in by IDataObject::GetData.

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

DV_E_DVASPECT

Invalid dwAspectvalue.

OLE_E_NOTRUNNING

The object application is not running.

STG_E_MEDIUMFULL

An error occurred when allocating the medium.

Remarks

A data consumer calls IDataObject::GetDatato retrieve data from a data object, conveyed through a storage medium (defined through the STGMEDIUMstructure).

Notes to Callers

You can specify more than one acceptable TYMEDmedium with the Boolean ORoperator. IDataObject::GetDatamust choose the medium that best represents the data from the ORvalues, do the allocation, and indicate responsibility for releasing the medium.

Data transferred across a stream extends from position zero of the stream pointer through to the position immediately before the current stream pointer (that is, the stream pointer position on exit).

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

Notes to Implementers

IDataObject::GetDatamust check all fields in the FORMATETCstructure. It is important that IDataObject::GetDatarender the requested aspect and, if possible, use the requested medium.

If the data object cannot comply with the information specified in the FORMATETC, the method should return DV_E_FORMATETC.

If an attempt to allocate the medium fails, the method should return STG_E_MEDIUMFULL.

It is important to fill in all of the fields in the STGMEDIUMstructure.

Although the caller can specify more than one medium for returning the data, IDataObject::GetDatacan supply only one medium.

If the initial transfer fails with the selected medium, this method can be implemented to try one of the other media specified before returning an error.

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