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

Artigo
08/25/2023

Cria um objeto para enumerar os formatos compatíveis com um objeto de dados.

Sintaxe

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

Parâmetros

[in] dwDirection

A direção dos dados. Os valores possíveis vêm da enumeração DATADIR .

O valor DATADIR_GET enumera os formatos que podem ser passados para uma chamada para IDataObject::GetData. O valor DATADIR_SET enumera os formatos que podem ser passados para uma chamada para IDataObject::SetData.

[out] ppenumFormatEtc

Um ponteiro para uma variável de ponteiro IEnumFORMATETC que recebe o ponteiro de interface para o novo objeto enumerador.

Retornar valor

Esse método retorna S_OK em caso de êxito. Outros valores possíveis incluem o seguinte.

Código de retorno	Descrição
E_INVALIDARG	O dwDirection fornecido é inválido.
E_OUTOFMEMORY	Memória insuficiente disponível para esta operação.
E_NOTIMPL	Não há suporte para a direção especificada por dwDirection .
OLE_S_USEREG	Solicita que a OLE enumere os formatos do registro.

Comentários

EnumFormatEtc cria um objeto enumerador que pode ser usado para determinar todas as maneiras pelas quais o objeto de dados pode descrever dados em uma estrutura FORMATETC e fornece um ponteiro para sua interface IEnumFORMATETC . Essa é uma das interfaces de enumerador padrão.

Anotações aos Chamadores

Tendo obtido o ponteiro , o chamador pode enumerar as estruturas FORMATETC chamando os métodos de enumeração de IEnumFORMATETC. Como os formatos podem ser alterados ao longo do tempo, não há nenhuma garantia de que um formato enumerado tenha suporte no momento porque os formatos podem ser alterados ao longo do tempo. Assim, os aplicativos devem tratar a enumeração como uma dica dos tipos de formato que podem ser passados. O chamador é responsável por chamar Release quando ele é concluído com o enumerador .

EnumFormatEtc é chamado quando ocorre uma das seguintes ações:

Um aplicativo chama OleSetClipboard. O OLE deve determinar quais dados colocar na área de transferência e se é necessário colocar formatos de compatibilidade OLE 1 na área de transferência.
Os dados estão sendo colados da área de transferência ou descartados. Um aplicativo usa o primeiro formato aceitável.
A caixa de diálogo Colar Especial é exibida. O aplicativo de destino cria a lista de formatos das entradas FORMATETC .

Observações aos implementadores

Os formatos podem ser registrados estaticamente no registro ou dinamicamente durante a inicialização do objeto. Se um objeto tiver uma lista inalterada de formatos e esses formatos forem registrados no registro, o OLE fornecerá uma implementação de um objeto de enumeração FORMATETC que pode enumerar formatos registrados em um CLSID específico no registro. Um ponteiro para sua interface IEnumFORMATETC está disponível por meio de uma chamada para a função auxiliar OleRegEnumFormatEtc. Nessa situação, portanto, você pode implementar o método EnumFormatEtc simplesmente com uma chamada para essa função.

Os aplicativos EXE podem efetivamente fazer a mesma coisa implementando o método para retornar o valor OLE_S_USEREG. Esse valor retornado instrui o manipulador de objetos padrão a chamar OleRegEnumFormatEtc. Os aplicativos de objeto implementados como aplicativos de objeto DLL não podem retornar OLE_S_USEREG, portanto, devem chamar OleRegEnumFormatEtc diretamente.

Formatos privados poderão ser enumerados para objetos OLE 1, se estiverem registrados com as chaves RequestDataFormats ou SetDataFormats no Registro. Além disso, os formatos privados podem ser enumerados para objetos OLE (todas as versões após o OLE 1), se forem registrados com as chaves GetDataFormats ou SetDataFormats.

Para objetos OLE 1 cujos servidores não têm informações requestDataFormats ou SetDataFormats registradas no registro, uma chamada para EnumFormatEtc passando DATADIR_GET enumera apenas os formatos nativo e de meta-arquivo, independentemente de serem compatíveis com esses formatos ou outros. Chamar EnumFormatEtc passando DATADIR_SET nesses objetos enumera apenas nativo, independentemente de o objeto dar suporte a ser definido com outros formatos.

A estrutura FORMATETC retornada pela enumeração geralmente indica um dispositivo de destino NULL (ptd). Isso é apropriado porque, ao contrário dos outros membros do FORMATETC, o dispositivo de destino não participa da decisão do objeto sobre se ele pode aceitar ou fornecer os dados em uma chamada SetData ou GetData.

O membro tymed de FORMATETC geralmente indica que mais de um tipo de mídia de armazenamento é aceitável. Você sempre deve mascarar e testar isso usando um operador OR booliano.

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