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

Artículo
08/25/2023

Crea un objeto para enumerar los formatos admitidos por un objeto de datos.

Sintaxis

HRESULT EnumFormatEtc(
  [in]  DWORD          dwDirection,
  [out] IEnumFORMATETC **ppenumFormatEtc
);

Parámetros

[in] dwDirection

Dirección de los datos. Los valores posibles proceden de la enumeración DATADIR .

El valor DATADIR_GET enumera los formatos que se pueden pasar a una llamada a IDataObject::GetData. El valor DATADIR_SET enumera los formatos que se pueden pasar a una llamada a IDataObject::SetData.

[out] ppenumFormatEtc

Puntero a una variable de puntero IEnumFORMATETC que recibe el puntero de interfaz al nuevo objeto enumerador.

Valor devuelto

Este método devuelve S_OK cuando funciona correctamente. Otros valores posibles incluyen lo siguiente.

Código devuelto	Descripción
E_INVALIDARG	DwDirection proporcionado no es válido.
E_OUTOFMEMORY	Memoria insuficiente disponible para esta operación.
E_NOTIMPL	No se admite la dirección especificada por dwDirection .
OLE_S_USEREG	Solicita que OLE enumere los formatos del Registro.

Comentarios

EnumFormatEtc crea un objeto enumerador que se puede usar para determinar todas las formas en que el objeto de datos puede describir los datos en una estructura FORMATETC y proporciona un puntero a su interfaz IEnumFORMATETC . Se trata de una de las interfaces de enumerador estándar.

Notas a los autores de llamadas

Después de obtener el puntero, el autor de la llamada puede enumerar las estructuras FORMATETC llamando a los métodos de enumeración de IEnumFORMATETC. Dado que los formatos pueden cambiar con el tiempo, no hay ninguna garantía de que actualmente se admita un formato enumerado porque los formatos pueden cambiar con el tiempo. En consecuencia, las aplicaciones deben tratar la enumeración como una sugerencia de los tipos de formato que se pueden pasar. El autor de la llamada es responsable de llamar a Release cuando termine con el enumerador.

Se llama a EnumFormatEtc cuando se produce una de las siguientes acciones:

Una aplicación llama a OleSetClipboard. OLE debe determinar qué datos colocar en el Portapapeles y si es necesario colocar formatos de compatibilidad OLE 1 en el Portapapeles.
Los datos se pegan desde el Portapapeles o se quitan. Una aplicación usa el primer formato aceptable.
Se muestra el cuadro de diálogo Pegar especial . La aplicación de destino compila la lista de formatos de las entradas FORMATETC .

Notas para los implementadores

Los formatos se pueden registrar estáticamente en el Registro o dinámicamente durante la inicialización de objetos. Si un objeto tiene una lista de formatos sin cambiar y estos formatos se registran en el Registro, OLE proporciona una implementación de un objeto de enumeración FORMATETC que puede enumerar formatos registrados en un CLSID específico en el Registro. Hay disponible un puntero a su interfaz IEnumFORMATETC a través de una llamada a la función auxiliar OleRegEnumFormatEtc. En esta situación, por lo tanto, puede implementar el método EnumFormatEtc simplemente con una llamada a esta función.

Las aplicaciones EXE pueden hacer lo mismo mediante la implementación del método para devolver el valor OLE_S_USEREG. Este valor devuelto indica al controlador de objetos predeterminado que llame a OleRegEnumFormatEtc. Las aplicaciones de objeto que se implementan como aplicaciones de objetos DLL no pueden devolver OLE_S_USEREG, por lo que debe llamar directamente a OleRegEnumFormatEtc .

Los formatos privados se pueden enumerar para objetos OLE 1, si están registrados con las claves RequestDataFormats o SetDataFormats del Registro. Además, los formatos privados se pueden enumerar para objetos OLE (todas las versiones después de OLE 1), si están registrados con las claves GetDataFormats o SetDataFormats.

Para objetos OLE 1 cuyos servidores no tienen información de RequestDataFormats o SetDataFormats registradas en el registro, una llamada a EnumFormatEtc pasando DATADIR_GET solo enumera los formatos nativos y de metarchivo, independientemente de si admiten estos formatos u otros. Al llamar a EnumFormatEtc pasando DATADIR_SET en estos objetos solo se enumeran los nativos, independientemente de si el objeto admite establecerse con otros formatos.

La estructura FORMATETC devuelta por la enumeración suele indicar un dispositivo de destino NULL (ptd). Esto es adecuado porque, a diferencia de los demás miembros de FORMATETC, el dispositivo de destino no participa en la decisión del objeto sobre si puede aceptar o proporcionar los datos en una llamada a SetData o GetData.

El miembro tymed de FORMATETC suele indicar que es aceptable más de un tipo de medio de almacenamiento. Siempre debe enmascarar y probar para ello mediante un operador OR booleano.

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