Função OleGetClipboard (ole2.h)

  • Artigo

Recupera um objeto de dados que você pode usar para acessar o conteúdo da área de transferência.

Sintaxe

HRESULT OleGetClipboard(
  [out] LPDATAOBJECT *ppDataObj
);

Parâmetros

[out] ppDataObj

Endereço da variável de ponteiro IDataObject que recebe o ponteiro de interface para o objeto de dados da área de transferência.

Retornar valor

Essa função retorna S_OK com êxito. Outros valores possíveis incluem o seguinte.

Código de retorno Descrição
CLIPBRD_E_CANT_OPEN
 Falha na função OpenClipboard usada no OleFlushClipboard .
CLIPBRD_E_CANT_CLOSE
 Falha na função CloseClipboard usada no OleFlushClipboard .

Comentários

Cuidado Os dados da área de transferência não são confiáveis. Analise os dados cuidadosamente antes de usá-los em seu aplicativo.
 
Se você estiver escrevendo um aplicativo que pode aceitar dados da área de transferência, chame a função OleGetClipboard para obter um ponteiro para a interface IDataObject que você pode usar para recuperar o conteúdo da área de transferência.

O oleGetClipboard manipula três casos:

  • O aplicativo que colocou dados na área de transferência com a função OleSetClipboard ainda está em execução.
  • O aplicativo que colocou dados na área de transferência com a função OleSetClipboard posteriormente chamou a função OleFlushClipboard .
  • Há dados de um aplicativo não OLE na área de transferência.
No primeiro caso, o objeto de dados da área de transferência retornado por OleGetClipboard pode encaminhar chamadas conforme necessário para o objeto de dados original colocado na área de transferência e, portanto, pode potencialmente fazer chamadas RPC.

No segundo caso, o OLE cria um objeto de dados padrão e o retorna ao usuário. Como os dados na área de transferência se originaram de uma chamada OleSetClipboard , o objeto de dados fornecido por OLE contém informações mais precisas sobre o tipo de dados na área de transferência. Em particular, o meio original (TYMED) no qual os dados foram oferecidos é conhecido. Portanto, se um aplicativo de fonte de dados oferecer um formato de área de transferência específico, por exemplo cfFOO, em um objeto de armazenamento e chamar a função OleFlushClipboard , o objeto de armazenamento será copiado na memória e o identificador de memória hglobal será colocado na área de transferência. Em seguida, quando a função OleGetClipboard cria seu objeto de dados padrão, o hglobal da área de transferência novamente se torna um objeto IStorage . Além disso, o enumerador FORMATETC e o método IDataObject::QueryGetData indicam corretamente que o cfFOO (formato de área de transferência original) está novamente disponível em um TYMED_ISTORAGE.

No terceiro caso, o OLE ainda cria um objeto de dados padrão, mas não há informações especiais sobre os dados nos formatos da área de transferência (especialmente para formatos de Área de Transferência definidos pelo aplicativo). Portanto, se um meio de armazenamento baseado em hGlobal fosse colocado na área de transferência diretamente por uma chamada para a função SetClipboardData , o enumerador FORMATETC e o método IDataObject::QueryGetData não indicariam que os dados estavam disponíveis em um meio de armazenamento. No entanto, uma chamada para o método IDataObject::GetData para TYMED_ISTORAGE teria êxito. Devido a essas limitações, é altamente recomendável que os aplicativos com reconhecimento de OLE interajam com a área de transferência usando as funções de área de transferência OLE.

O objeto de dados da área de transferência criado pela função OleGetClipboard tem uma implementação IDataObject bastante extensa. O objeto de dados fornecido por OLE pode converter dados de formato de área de transferência OLE 1 na representação esperada por um chamador OLE 2. Além disso, todos os dados estruturados estão disponíveis em qualquer meio estruturado ou simples e todos os dados simples estão disponíveis em qualquer meio simples. No entanto, os objetos GDI (como metarquivos e bitmaps) só estão disponíveis em seus respectivos meios.

Observe que o membro tymed da estrutura FORMATETC usada no enumerador FORMATETC contém a união de meios com suporte. Os aplicativos que procuram informações específicas (como se CF_TEXT está disponível em TYMED_HGLOBAL) devem fazer a máscara de bits apropriada ao verificar esse valor.

Se você chamar a função OleGetClipboard , só deverá manter o IDataObject retornado por um tempo muito curto. Ele consome recursos no aplicativo que o ofereceu.

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 ole2.h
Biblioteca Ole32.lib
DLL Ole32.dll
Conjunto de APIs ext-ms-win-com-ole32-l1-1-5 (introduzido em Windows 10, versão 10.0.15063)

Confira também

OleSetClipboard