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

  • Статья

Предоставляет потенциально отличную, но логически эквивалентную структуру 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