Метод IDataObject::EnumFormatEtc (objidl.h)

Статья
08/25/2023

Создает объект для перечисления форматов, поддерживаемых объектом данных.

Синтаксис

HRESULT EnumFormatEtc(
  [in]  DWORD          dwDirection,
  [out] IEnumFORMATETC **ppenumFormatEtc
);

Параметры

[in] dwDirection

Направление данных. Возможные значения поступают из перечисления DATADIR .

Значение DATADIR_GET перечисляет форматы, которые можно передать в вызов IDataObject::GetData. Значение DATADIR_SET перечисляет форматы, которые можно передать в вызов IDataObject::SetData.

[out] ppenumFormatEtc

Указатель на переменную указателя IEnumFORMATETC , которая получает указатель интерфейса на новый объект перечислителя.

Возвращаемое значение

Этот метод возвращает значение S_OK при успешном завершении. Ниже перечислены другие возможные значения.

Код возврата	Описание
E_INVALIDARG	Предоставленный dwDirection недопустим.
E_OUTOFMEMORY	Недостаточно доступной памяти для этой операции.
E_NOTIMPL	Направление, заданное dwDirection, не поддерживается.
OLE_S_USEREG	Требует, чтобы OLE перечисляли форматы из реестра.

EnumFormatEtc создает объект перечислителя, который можно использовать для определения всех способов, которыми объект данных может описывать данные в структуре FORMATETC , и предоставляет указатель на его интерфейс IEnumFORMATETC . Это один из стандартных интерфейсов перечислителя.

Примечания к вызывающим абонентам

Получив указатель, вызывающий объект может перечислить структуры FORMATETC , вызвав методы перечисления IEnumFORMATETC. Поскольку форматы могут меняться со временем, нет никакой гарантии, что перечислимый формат в настоящее время поддерживается, так как форматы могут меняться со временем. Соответственно, приложения должны рассматривать перечисление как указание на типы форматов, которые могут быть переданы. Вызывающий объект отвечает за вызов release после завершения работы с перечислителем.

EnumFormatEtc вызывается при выполнении одного из следующих действий:

Приложение вызывает OleSetClipboard. OLE должен определить, какие данные следует поместить в буфер обмена и нужно ли помещать форматы совместимости OLE 1 в буфер обмена.
Данные вставляется из буфера обмена или удаляется. Приложение использует первый допустимый формат.
Откроется диалоговое окно Специальная вставка . Целевое приложение создает список форматов из записей FORMATETC .

Примечания для разработчиков

Форматы можно регистрировать статически в реестре или динамически во время инициализации объекта. Если объект имеет неизменяемый список форматов и эти форматы зарегистрированы в реестре, OLE предоставляет реализацию объекта перечисления FORMATETC , который может перечислять форматы, зарегистрированные в реестре под определенным идентификатором CLSID. Указатель на интерфейс IEnumFORMATETC доступен через вызов вспомогательной функции OleRegEnumFormatEtc. Таким образом, в этом случае можно реализовать метод EnumFormatEtc просто с помощью вызова этой функции.

Приложения EXE могут эффективно выполнять то же самое, реализовав метод для возврата значения OLE_S_USEREG. Это возвращаемое значение указывает обработчику объектов по умолчанию вызвать OleRegEnumFormatEtc. Объектные приложения, реализованные как приложения-объекты DLL, не могут возвращать OLE_S_USEREG, поэтому должны вызывать OleRegEnumFormatEtc напрямую.

Закрытые форматы можно перечислить для объектов OLE 1, если они зарегистрированы в разделах RequestDataFormats или SetDataFormats в реестре. Кроме того, частные форматы можно перечислить для объектов OLE (все версии после OLE 1), если они зарегистрированы с помощью ключей GetDataFormats или SetDataFormats.

Для объектов OLE 1, серверы которых не имеют сведений RequestDataFormats или SetDataFormats, зарегистрированных в реестре, вызов EnumFormatEtc , передавая DATADIR_GET, перечисляет только собственные форматы и форматы метафайлов, независимо от того, поддерживают ли они эти или другие форматы. Вызов Метода EnumFormatEtc , передавая DATADIR_SET для таких объектов, перечисляет только собственный код, независимо от того, поддерживает ли объект настройку с другими форматами.

Структура FORMATETC, возвращаемая перечислением, обычно указывает на целевое устройство NULL (ptd). Это уместно, поскольку, в отличие от других членов FORMATETC, целевое устройство не участвует в решении объекта о том, может ли оно принимать или предоставлять данные в вызове SetData или GetData.

Элемент tymedFORMATETC часто указывает на то, что допускается несколько типов носителей хранения. Всегда следует маскировать и проверять это с помощью логического оператора OR.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	objidl.h