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

  • Artículo

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