IDataObject.GetCanonicalFormatEtc(FORMATETC, FORMATETC) Method


Provides a standard FORMATETC structure that is logically equivalent to a more complex structure. Use this method to determine whether two different FORMATETC structures would return the same data, removing the need for duplicate rendering.

 int GetCanonicalFormatEtc(System::Runtime::InteropServices::ComTypes::FORMATETC % formatIn, [Runtime::InteropServices::Out] System::Runtime::InteropServices::ComTypes::FORMATETC % formatOut);
public int GetCanonicalFormatEtc (ref System.Runtime.InteropServices.ComTypes.FORMATETC formatIn, out System.Runtime.InteropServices.ComTypes.FORMATETC formatOut);
abstract member GetCanonicalFormatEtc : FORMATETC * FORMATETC -> int
Public Function GetCanonicalFormatEtc (ByRef formatIn As FORMATETC, ByRef formatOut As FORMATETC) As Integer



A pointer to a FORMATETC structure, passed by reference, that defines the format, medium, and target device that the caller would like to use to retrieve data in a subsequent call such as GetData(FORMATETC, STGMEDIUM). The TYMED member is not significant in this case and should be ignored.


When this method returns, contains a pointer to a FORMATETC structure that contains the most general information possible for a specific rendering, making it canonically equivalent to formatetcIn. The caller must allocate this structure and the GetCanonicalFormatEtc(FORMATETC, FORMATETC) method must fill in the data. To retrieve data in a subsequent call such as GetData(FORMATETC, STGMEDIUM), the caller uses the supplied value of formatOut, unless the value supplied is null. This value is null if the method returns DATA_S_SAMEFORMATETC. The TYMED member is not significant in this case and should be ignored. This parameter is passed uninitialized.


This method supports the standard return values E_INVALIDARG, E_UNEXPECTED, and E_OUTOFMEMORY, as well as the following:

Value Description
S_OK The returned FORMATETC structure is different from the one that was passed.
DATA_S_SAMEFORMATETC The FORMATETC structures are the same and null is returned in the formatOut parameter.
DV_E_LINDEX There is an invalid value for lindex; currently, only -1 is supported.
DV_E_FORMATETC There is an invalid value for the pFormatetc parameter.
OLE_E_NOTRUNNING The application is not running.


For more information about IDataObject::GetCanonicalFormatEtc, see the MSDN Library.

Applies to