IEnumFORMATETC:IUnknown

Article
06/30/2006

This interface is used to enumerate an array of FORMATETC structures. IEnumFORMATETC has the same methods as all enumerator interfaces: Next, Skip, Reset, and Clone.

When to Implement

IEnumFORMATETC must be implemented by all data objects to support calls to the IDataObject::EnumFormatEtc method, which supplies a pointer to the enumerator's IEnumFORMATETC interface. If the data object supports a different set of FORMATETC information depending on the direction of the data (whether a call is intended for the SetData or GetData method of IDataObject), the implementation of IEnumFORMATETC must be able to operate on both.

The order of formats enumerated through the IEnumFORMATETC object should be the same as the order that the formats would be in when placed on the Clipboard. Typically, this order starts with private data formats and ends with presentation formats, such as CF_METAFILEPICT.

When to Use

Call the methods of IEnumFORMATETC when you need to enumerate the FORMATETC structures defining the formats and media supported by a given data object. This is necessary in most data transfer operations, such as Clipboard and drag-and-drop, so the object on the other end of the data transfer can determine whether the appropriate format and media for the data is supported.

Note To Implementers

If the IEnumFORMATETC::Next method returns a non-NULL DVTARGETDEVICE pointer in the ptd member of the FORMATETC structure, it must be allocated with the CoTaskMemAlloc function (or its equivalent).

Note to Callers

If the IEnumFORMATETC::Next method returns a non-NULL DVTARGETDEVICE pointer in the ptd member of the FORMATETC structure, the memory must be freed with the CoTaskMemFree function (or its equivalent). Failure to do so will result in a memory leak.

Methods

The following table shows the methods for this interface in alphabetical order.

IEnumFORMATETC method	Description
Clone	Creates another enumerator that contains the same enumeration state as the current enumerator.
Next	Retrieves the next celt items in the enumeration sequence.
Reset	Resets the enumeration sequence to the beginning.
Skip	Skips over the next specified number of elements in the enumeration sequence.

Remarks

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

Requirements

OS Versions: Windows CE 3.0 and later.
Header: Objidl.h, Objidl.idl.
Link Library: Ole32.lib, Uuid.lib.

Share via