Método IDataObject::GetCanonicalFormatEtc (objidl.h)

Fornece uma estrutura FORMATETC potencialmente diferente, mas logicamente equivalente. Você usa esse método para determinar se duas estruturas FORMATETC diferentes retornariam os mesmos dados, removendo a necessidade de renderização duplicada.

Sintaxe

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

Parâmetros

[in] pformatectIn

Um ponteiro para a estrutura FORMATETC que define o formato, o dispositivo médio e de destino que o chamador gostaria de usar para recuperar dados em uma chamada subsequente, como IDataObject::GetData. O membro tymed não é significativo nesse caso e deve ser ignorado.

[out] pformatetcOut

Um ponteiro para uma estrutura FORMATETC que contém as informações mais gerais possíveis para uma renderização específica, tornando-a canonicamente equivalente a pformatetcIn. O chamador deve alocar essa estrutura e o método GetCanonicalFormatEtc deve preencher os dados. Para recuperar dados em uma chamada subsequente como IDataObject::GetData, o chamador usa o valor especificado de pformatetcOut, a menos que o valor especificado seja NULL. Esse valor será NULL se o método retornar DATA_S_SAMEFORMATETC. O membro tymed não é significativo nesse caso e deve ser ignorado.

Retornar valor

Esse método pode retornar os valores a seguir.

Código de retorno	Descrição
S_OK	A estrutura FORMATETC retornada é diferente daquela que foi passada.
DATA_S_SAMEFORMATETC	As estruturas FORMATETC são as mesmas e NULL é retornado em pformatetcOut.
DV_E_LINDEX	O valor de lindex não é válido; Atualmente, há suporte apenas para -1.
DV_E_FORMATETC	O valor de pformatetc não é válido.
OLE_E_NOTRUNNING	O aplicativo de objeto não está em execução.
E_UNEXPECTED	Ocorreu um erro inesperado.
E_INVALIDARG	O parâmetro dwDirection não é válido.
E_OUTOFMEMORY	Não havia memória suficiente disponível para esta operação.

Comentários

Se um objeto de dados puder fornecer exatamente os mesmos dados para mais de uma estrutura FORMATETC solicitada, GetCanonicalFormatEtc poderá fornecer um "canonical" ou FORMATETC padrão que fornece a mesma renderização que um conjunto de estruturas FORMATETC mais complicadas. Por exemplo, é comum que os dados retornados não sejam sensíveis ao dispositivo de destino especificado em qualquer um de um conjunto de estruturas FORMATETC semelhantes.

Anotações para chamadores

Uma chamada para esse método pode determinar se duas chamadas para IDataObject::GetData em um objeto de dados, especificando duas estruturas FORMATETC diferentes, produziriam realmente as mesmas renderizações, eliminando assim a necessidade da segunda chamada e melhorando o desempenho. Se a chamada para GetCanonicalFormatEtc resultar em um formato canônico sendo gravado no parâmetro pformatetcOut , o chamador usará essa estrutura em uma chamada subsequente para IDataObject::GetData.

Anotações aos implementadores

Conceitualmente, é possível pensar em estruturas FORMATETC em grupos definidos por um FORMATETC canônico que fornece os mesmos resultados que cada um dos membros do grupo. Ao construir o FORMATETC canônico, você deve garantir que ele contenha as informações mais gerais possíveis que ainda produzem uma renderização específica.

Para objetos de dados que nunca fornecem renderizações específicas do dispositivo, a implementação mais simples desse método é copiar o FORMATETC de entrada para a saída FORMATETC, armazenar um NULL no membro ptd do FORMATETC de saída e retornar DATA_S_SAMEFORMATETC.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	objidl.h

Confira também

Idataobject