Função OleCreateFromData (ole2.h)

Cria um objeto inserido de um objeto de transferência de dados recuperado da área de transferência ou como parte de uma operação de arrastar e soltar OLE. Destina-se a ser usado para implementar uma colagem de uma operação de arrastar e soltar OLE.

Sintaxe

HRESULT OleCreateFromData(
  [in]  LPDATAOBJECT    pSrcDataObj,
  [in]  REFIID          riid,
  [in]  DWORD           renderopt,
  [in]  LPFORMATETC     pFormatEtc,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Parâmetros

[in] pSrcDataObj

Ponteiro para a interface IDataObject no objeto de transferência de dados que contém os dados dos quais o objeto é criado.

[in] riid

Referência ao identificador da interface que o chamador usa posteriormente para se comunicar com o novo objeto (geralmente IID_IOleObject, definido nos cabeçalhos OLE como o identificador de interface para IOleObject).

[in] renderopt

Valor da enumeração OLERENDER que indica os recursos de desenho ou recuperação de dados armazenados em cache localmente que o objeto recém-criado deve ter. Considerações adicionais são descritas na seção Comentários a seguir.

[in] pFormatEtc

Ponteiro para um valor da enumeração OLERENDER que indica os recursos de desenho ou recuperação de dados armazenados em cache localmente que o objeto recém-criado deve ter. O valor OLERENDER escolhido afeta os valores possíveis para o parâmetro pFormatEtc .

[in] pClientSite

Ponteiro para uma instância do IOleClientSite, a interface primária por meio da qual o objeto solicitará serviços de seu contêiner. Este parâmetro pode ser NULL.

[in] pStg

Ponteiro para a interface IStorage no objeto de armazenamento. Esse parâmetro pode não ser NULL.

[out] ppvObj

Endereço da variável de ponteiro que recebe o ponteiro de interface solicitado em riid. Após o retorno bem-sucedido, *ppvObj contém o ponteiro de interface solicitado no objeto recém-criado.

Retornar valor

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

Código de retorno	Descrição
OLE_E_STATIC	Indica que o OLE pode criar apenas um objeto estático.
DV_E_FORMATETC	Nenhum formato aceitável está disponível para criação de objeto.

Comentários

A função OleCreateFromData cria um objeto inserido de um objeto de transferência de dados que dá suporte à interface IDataObject . Nesse caso, o objeto de dados é o tipo recuperado da área de transferência com uma chamada para a função OleGetClipboard ou faz parte de uma operação de arrastar e soltar OLE (o objeto de dados é passado para uma chamada para IDropTarget::D rop).

Se o formato da área de transferência FileName ou FileNameW (CF_FILENAME) estiver presente no objeto de transferência de dados e CF_EMBEDDEDOBJECT ou CF_EMBEDSOURCE não existirem, OleCreateFromData primeiro tentará criar um pacote que contenha o arquivo indicado. Geralmente, ele usa o primeiro formato disponível.

Se OleCreateFromData não puder criar um pacote, ele tentará criar um objeto usando o formato CF_EMBEDDEDOBJECT. Se esse formato não estiver disponível, OleCreateFromData tentará criá-lo com o formato CF_EMBEDSOURCE. Se nenhum desses formatos estiver disponível e o objeto de transferência de dados der suporte à interface IPersistStorage , OleCreateFromDatachamará IPersistStorage::Save do objeto para que o objeto se salve.

Se um objeto vinculado existente estiver selecionado e copiado, ele aparecerá na área de transferência como apenas outro objeto inserível. Consequentemente, uma operação de colagem que invoca OleCreateFromData pode criar um objeto vinculado. Após a operação de colagem, o contêiner deve chamar a função QueryInterface , solicitando IID_IOleLink (definida nos cabeçalhos OLE como o identificador de interface para IOleLink), para determinar se um objeto vinculado foi criado.

Use os parâmetros renderopt e pFormatetc para controlar a funcionalidade de cache do objeto recém-criado. Para obter informações gerais sobre como usar a interação desses parâmetros para determinar o que deve ser armazenado em cache, consulte a enumeração OLERENDER . No entanto, há alguns efeitos específicos adicionais desses parâmetros na maneira como OleCreateFromData inicializa o cache.

Quando OleCreateFromData usa a CF_EMBEDDEDOBJECT ou o formato da área de transferência CF_EMBEDSOURCE para criar o objeto inserido, o main diferença entre os dois é onde os dados de inicialização de cache são armazenados:

• CF_EMBEDDEDOBJECT indica que a origem é um objeto inserido existente. Ele já tem em seu cache os dados apropriados e o OLE usa esses dados para inicializar o cache do novo objeto.
• CF_EMBEDSOURCE indica que o objeto de dados de origem contém as informações de inicialização de cache em formatos diferentes de CF_EMBEDSOURCE. OleCreateFromData os usa para inicializar o cache do objeto recém-inserido.

Os valores renderizados afetam a inicialização do cache da seguinte maneira.

Valor	Descrição
OLERENDER_DRAW & OLERENDER_FORMAT	Se as informações de apresentação a serem armazenadas em cache estiverem atualmente presentes no pool de inicialização de cache apropriado, elas serão usadas. (Os locais apropriados estão no cache do objeto de dados de origem para CF_EMBEDDEDOBJECT e nos outros formatos no objeto de dados de origem para CF_EMBEDSOURCE.) Se as informações não estiverem presentes, o cache estará inicialmente vazio, mas será preenchido na primeira vez que o objeto for executado. Nenhum outro formato é armazenado em cache no objeto recém-criado.
OLERENDER_NONE	Nada deve ser armazenado em cache no objeto recém-criado. Se a origem tiver o formato CF_EMBEDDEDOBJECT, todos os dados armazenados em cache existentes que foram copiados serão removidos.
OLERENDER_ASIS	Se a origem tiver o formato CF_EMBEDDEDOBJECT, o cache do novo objeto conterá os mesmos dados de cache que o objeto de origem. Para CF_EMBEDSOURCE, nada deve ser armazenado em cache no objeto recém-criado. Essa opção deve ser usada por contêineres mais sofisticados. Após essa chamada, esses contêineres chamariam IOleCache::Cache e IOleCache::Uncache para configurar exatamente o que deve ser armazenado em cache. Para CF_EMBEDSOURCE, eles também chamariam IOleCache::InitCache.

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-3 (introduzido no Windows 10, versão 10.0.10240)

Confira também

Idataobject

Olecreate