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 creates an object for enumerating the FORMATETCstructures for a data object. These structures are used in calls to the IDataObject::GetDataor IDataObject::SetDatamethod.

Syntax 

HRESULT EnumFormatEtc(
  DWORD 
dwDirection, 
  IEnumFORMATETC** 
ppenumFormatetc
);

Parameters

dwDirection

[in] Direction of the data through a value from the enumeration DATADIR.

Copy Code 
typedef enum tagDATADIR 
{ 
	DATADIR_GET = 1, 
	DATADIR_SET = 2, 
} DATADIR;

The value DATADIR_GET enumerates the formats that can be passed in to a call to IDataObject::GetData. The value DATADIR_SET enumerates those formats that can be passed in to a call to IDataObject::SetData.

ppenumFormatetc

[out] Address of the IEnumFORMATETC *pointer variable that receives the interface pointer to the new enumerator object.

Return Value

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY. The following table shows the additional return values for this method.

Value Description

S_OK

The enumerator object was successfully created.

E_NOTIMPL

The direction specified by dwDirectionis not supported.

OLE_S_USEREG

Requests that OLE enumerate the formats from the registry.

Remarks

IDataObject::EnumFormatEtccreates an enumerator object that can be used to determine all of the ways the data object can describe data in a FORMATETCstructure and supplies a pointer to its IEnumFORMATETCinterface. This is one of the standard enumerator interfaces.

Notes to Callers

Having obtained the pointer, the caller can enumerate the FORMATETCstructures by calling the enumeration methods of IEnumFORMATETC.

Because the formats can change over time, there is no guarantee that an enumerated format is currently supported. Accordingly, applications should treat the enumeration as a hint of the format types that can be passed.

The caller is responsible for calling IEnumFormatEtc::Releasewhen it is finished with the enumeration.

IDataObject::EnumFormatEtcis called when one of the following actions occurs:

  • An application calls OleSetClipboard. OLE must determine what data to place on the Clipboard and whether it is necessary to put OLE 1 compatibility formats on the Clipboard.

  • Data is being pasted from the Clipboard or dropped. An application uses the first acceptable format.

  • The Paste Specialdialog box is displayed. The target application builds the list of formats from the FORMATETCentries.

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

Notes to Implementers

Formats can be registered statically in the registry or dynamically during object initialization.

If an object has an unchanging list of formats and these formats are registered in the registry, OLE provides an implementation of a FORMATETCenumeration object that can enumerate formats registered under a specific CLSID in the registry.

A pointer to its IEnumFORMATETCinterface is available through a call to the helper function OleRegEnumFormatEtc. In this situation, therefore, you can implement the EnumFormatEtcmethod simply with a call to this function.

EXE applications can effectively do the same thing by implementing the method to return the value OLE_S_USEREG. This return value instructs the default object handler to call OleRegEnumFormatEtc.

Object applications that are implemented as DLL object applications cannot return OLE_S_USEREG, so OleRegEnumFormatEtcmust be called directly.

Private formats can be enumerated for OLE 1 objects, if they are registered with the RequestDataFormatsor SetDataFormatskeys in the registry. Also, private formats can be enumerated for OLE objects (all versions after OLE 1), if they are registered with the GetDataFormatsor SetDataFormatskeys.

For OLE 1 objects whose servers do not have RequestDataFormatsor SetDataFormatsinformation registered in the registry, a call to IDataObject::EnumFormatEtcpassing DATADIR_GET only enumerates the Native and Metafile formats, regardless of whether they support these formats or others.

Calling EnumFormatEtcpassing DATADIR_SET on such objects only enumerates Native, regardless of whether the object supports being set with other formats.

The FORMATETCstructure returned by the enumeration usually indicates a NULL target device ( ptd). This is appropriate because, unlike the other members of FORMATETC, the target device does not participate in the object's decision as to whether it can accept or provide the data in either a SetDataor GetDatacall.

The TYMEDmember of FORMATETCoften indicates that more than one kind of storage medium is acceptable. You should always mask and test for this by using a Boolean ORoperator.

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