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

Proporciona una estructura FORMATETC potencialmente diferente pero lógicamente equivalente. Use este método para determinar si dos estructuras FORMATETC diferentes devolverían los mismos datos, lo que elimina la necesidad de representación duplicada.

Sintaxis

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

Parámetros

[in] pformatectIn

Puntero a la estructura FORMATETC que define el formato, el medio y el dispositivo de destino que el autor de la llamada desea usar para recuperar datos en una llamada posterior, como IDataObject::GetData. El miembro tymed no es significativo en este caso y debe omitirse.

[out] pformatetcOut

Puntero a una estructura FORMATETC que contiene la información más general posible para una representación específica, lo que lo convierte en equivalente canónicamente a pformatetcIn. El llamador debe asignar esta estructura y el método GetCanonicalFormatEtc debe rellenar los datos. Para recuperar datos en una llamada posterior como IDataObject::GetData, el llamador usa el valor especificado de pformatetcOut, a menos que el valor especificado sea NULL. Este valor es NULL si el método devuelve DATA_S_SAMEFORMATETC. El miembro tymed no es significativo en este caso y debe omitirse.

Valor devuelto

Este método puede devolver los siguientes valores.

Código devuelto	Descripción
S_OK	La estructura FORMATETC devuelta es diferente de la que se pasó.
DATA_S_SAMEFORMATETC	Las estructuras FORMATETC son las mismas y se devuelve NULL en pformatetcOut.
DV_E_LINDEX	El valor de lindex no es válido; actualmente, solo se admite -1.
DV_E_FORMATETC	El valor de pformatetc no es válido.
OLE_E_NOTRUNNING	La aplicación de objeto no se está ejecutando.
E_UNEXPECTED	Se produjo un error inesperado.
E_INVALIDARG	El parámetro dwDirection no es válido.
E_OUTOFMEMORY	No había memoria suficiente disponible para esta operación.

Comentarios

Si un objeto de datos puede proporcionar exactamente los mismos datos para más de una estructura FORMATETC solicitada, GetCanonicalFormatEtc puede proporcionar un "canónico" o estándar FORMATETC que proporciona la misma representación que un conjunto de estructuras FORMATETC más complicadas. Por ejemplo, es habitual que los datos devueltos no sean sensibles al dispositivo de destino especificado en cualquiera de un conjunto de estructuras FORMATETC similares.

Notas a los autores de llamadas

Una llamada a este método puede determinar si dos llamadas a IDataObject::GetData en un objeto de datos, especificando dos estructuras FORMATETC diferentes, generarían realmente las mismas representaciones, lo que elimina la necesidad de la segunda llamada y mejora el rendimiento. Si la llamada a GetCanonicalFormatEtc da como resultado que se escriba un formato canónico en el parámetro pformatetcOut , el llamador usa esa estructura en una llamada posterior a IDataObject::GetData.

Notas para los implementadores

Conceptualmente, es posible pensar en estructuras FORMATETC en grupos definidos por un FORMATETC canónico que proporciona los mismos resultados que cada uno de los miembros del grupo. Al construir el FORMATETC canónico, debe asegurarse de que contiene la información más general posible que todavía genera una representación específica.

Para los objetos de datos que nunca proporcionan representaciones específicas del dispositivo, la implementación más sencilla de este método es copiar el FORMATETC de entrada en el FORMATETC de salida, almacenar un VALOR NULL en el miembro ptd de la salida FORMATETC y devolver DATA_S_SAMEFORMATETC.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	objidl.h

Consulte también

IDataObject