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

Статья
08/25/2023

Предоставляет потенциально отличную, но логически эквивалентную структуру FORMATETC . Этот метод используется для определения того, будут ли две разные структуры FORMATETC возвращать одни и те же данные, устраняя необходимость в дублировании отрисовки.

Синтаксис

HRESULT GetCanonicalFormatEtc(
  [in]  FORMATETC *pformatectIn,
  [out] FORMATETC *pformatetcOut
);

Параметры

[in] pformatectIn

Указатель на структуру FORMATETC , которая определяет формат, среднее и целевое устройство, которое вызывающий объект хотел бы использовать для получения данных в последующем вызове, например IDataObject::GetData. Элемент tymed в этом случае не имеет значения, и его следует игнорировать.

[out] pformatetcOut

Указатель на структуру FORMATETC , которая содержит наиболее общие сведения, доступные для конкретной отрисовки, что делает ее канонически эквивалентной pformatetcIn. Вызывающий объект должен выделить эту структуру, а метод GetCanonicalFormatEtc должен заполнить данные. Чтобы получить данные в последующем вызове , например IDataObject::GetData, вызывающий объект использует указанное значение pformatetcOut, если только не указано значение NULL. Это значение равно NULL , если метод возвращает DATA_S_SAMEFORMATETC. Элемент tymed в этом случае не имеет значения, и его следует игнорировать.

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

Этот метод может возвращать следующие значения.

Код возврата	Описание
S_OK	Возвращаемая структура FORMATETC отличается от переданной.
DATA_S_SAMEFORMATETC	Структуры FORMATETC одинаковы, и в pformatetcOut возвращается значение NULL.
DV_E_LINDEX	Недопустимое значение lindex ; В настоящее время поддерживается только -1.
DV_E_FORMATETC	Недопустимое значение для pformatetc .
OLE_E_NOTRUNNING	Приложение-объект не выполняется.
E_UNEXPECTED	Произошла непредвиденная ошибка.
E_INVALIDARG	Недопустимый параметр dwDirection .
E_OUTOFMEMORY	Недостаточно доступной памяти для этой операции.

Если объект данных может предоставлять одни и те же данные для нескольких запрошенных структур FORMATETC , GetCanonicalFormatEtc может предоставить "канонический" или стандартный FORMATETC , который обеспечивает ту же отрисовку, что и набор более сложных структур FORMATETC . Например, возвращаемые данные обычно нечувствительны к целевому устройству, указанному в любом из наборов аналогичных структур FORMATETC .

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

Вызов этого метода может определить, будут ли два вызова IDataObject::GetData в объекте данных с указанием двух разных структур FORMATETC на самом деле производить одни и те же отрисовки, тем самым устраняя необходимость второго вызова и повышая производительность. Если вызов GetCanonicalFormatEtc приводит к записи канонического формата в параметр pformatetcOut , вызывающий объект использует такую структуру в последующем вызове IDataObject::GetData.

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

Концептуально можно представить структуры FORMATETC в группах, определяемых каноническим FORMATETC , который предоставляет те же результаты, что и каждый из членов группы. При создании канонического FORMATETC необходимо убедиться, что он содержит наиболее общие сведения, которые по-прежнему создают определенную отрисовку.

Для объектов данных, которые никогда не предоставляют отрисовку для конкретного устройства, простейшая реализация этого метода заключается в копировании входных данных FORMATETC в выходные данные FORMATETC, хранении значения NULL в элементе ptd выходного элемента FORMATETC и возврате DATA_S_SAMEFORMATETC.

Требования

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

См. также раздел

Idataobject

Поделиться через