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 provides a standard FORMATETCstructure that is logically equivalent to one that is more complex. You use this method to determine whether two different FORMATETCstructures would return the same data, removing the need for duplicate rendering.

Syntax 

HRESULT GetCanonicalFormatEtc(
  FORMATETC* 
pFormatetcIn,
  FORMATETC* 
pFormatetcOut
);

Parameters

pFormatetcIn

[in] Pointer to the FORMATETCstructure that defines the format, medium, and target device that the caller wants to use to retrieve data in a subsequent call such as to the IDataObject::GetDatamethod. The TYMEDmember is not significant in this case and should be ignored.

pFormatetcOut

[out] Pointer to a FORMATETCstructure that contains the most general information possible for a specific rendering, making it canonically equivalent to pFormatetcIn.

The caller must allocate this structure and the GetCanonicalFormatEtcmethod must fill in the data.

To retrieve data in a subsequent call such as IDataObject::GetData, the caller uses the supplied value of pFormatetcOut, unless the value supplied is NULL.

This value is NULL if the method returns DATA_S_SAMEFORMATETC.

The TYMEDmember is not significant in this case and should be ignored.

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

The returned FORMATETCstructure is different from the one that was passed.

DATA_S_SAMEFORMATETC

The FORMATETCstructures are the same and NULL is returned in pFormatetcOut.

DV_E_LINDEX

Invalid value for lindex; currently, only -1 is supported.

DV_E_FORMATETC

Invalid value for pFormatetc.

OLE_E_NOTRUNNING

The object application is not running.

Remarks

If a data object can supply exactly the same data for more than one requested FORMATETCstructure, IDataObject::GetCanonicalFormatEtccan supply a canonical, or standard FORMATETCthat gives the same rendering as a set of more complicated FORMATETCstructures.

For example, it is common for the data returned to be insensitive to the target device specified in any one of a set of otherwise similar FORMATETCstructures.

Notes to Callers

A call to this method can determine whether two calls to IDataObject::GetDataon a data object, specifying two different FORMATETCstructures, would actually produce the same renderings, thus eliminating the need for the second call and improving performance.

If the call to GetCanonicalFormatEtcresults in a canonical format being written to the pFormatetcOutparameter, the caller then uses that structure in a subsequent call to IDataObject::GetData.

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

Notes to Implementers

Conceptually, it is possible to think of FORMATETCstructures in groups defined by a canonical FORMATETCstructure that provides the same results as each of the group members.

In constructing the canonical FORMATETCstructure, you should make sure it contains the most general information possible that still produces a specific rendering.

For data objects that never provide device-specific renderings, the simplest implementation of this method is to copy the input FORMATETCstructure to the output FORMATETCstructure, store a NULL in the ptdfield of the output FORMATETCstructure, and return DATA_S_SAMEFORMATETC.

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