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

 virtual int System.Runtime.InteropServices.ComTypes.IDataObject.GetCanonicalFormatEtc(System::Runtime::InteropServices::ComTypes::FORMATETC % pformatetcIn, [Runtime::InteropServices::Out] System::Runtime::InteropServices::ComTypes::FORMATETC % pformatetcOut) = System::Runtime::InteropServices::ComTypes::IDataObject::GetCanonicalFormatEtc;
int IDataObject.GetCanonicalFormatEtc (ref System.Runtime.InteropServices.ComTypes.FORMATETC pformatetcIn, out System.Runtime.InteropServices.ComTypes.FORMATETC pformatetcOut);
Function GetCanonicalFormatEtc (ByRef pformatetcIn As FORMATETC, ByRef pformatetcOut As FORMATETC) As Integer Implements IDataObject.GetCanonicalFormatEtc



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.



This member is an explicit interface member implementation. It can be used only when the DataObject is cast to an IDataObject interface.

Applies to