Função OleCreateLinkFromDataEx (ole2.h)

Artigo
03/15/2023

Estende a funcionalidade OleCreateLinkFromData dando suporte à instanciação mais eficiente de objetos em contêineres que exigem o cache de vários formatos de apresentações ou dados, em vez do formato único com suporte de OleCreateLinkFromData.

Sintaxe

HRESULT OleCreateLinkFromDataEx(
  [in]      LPDATAOBJECT    pSrcDataObj,
  [in]      REFIID          riid,
  [in]      DWORD           dwFlags,
  [in]      DWORD           renderopt,
  [in]      ULONG           cFormats,
  [in]      DWORD           *rgAdvf,
  [in]      LPFORMATETC     rgFormatEtc,
  [in]      IAdviseSink     *lpAdviseSink,
  [in, out] DWORD           *rgdwConnection,
  [in]      LPOLECLIENTSITE pClientSite,
  [in]      LPSTORAGE       pStg,
  [out]     LPVOID          *ppvObj
);

Parâmetros

[in] pSrcDataObj

Ponteiro para o objeto de dados do qual criar um objeto de link.

[in] riid

Referência ao identificador da interface do objeto a ser retornado.

[in] dwFlags

Esse parâmetro pode ser 0 ou OLECREATE_LEAVERUNNING (0x00000001).

[in] renderopt

Valor obtido da enumeração OLERENDER .

[in] cFormats

Quando renderopt é OLERENDER_FORMAT, indica o número de estruturas FORMATETC na matriz rgFormatEtc , que deve ser pelo menos uma. Em todos os outros casos, esse parâmetro deve ser zero.

[in] rgAdvf

Quando renderopt é OLERENDER_FORMAT, aponta para uma matriz de elementos DWORD , cada um deles é uma combinação de valores da enumeração ADVF . Cada elemento dessa matriz é passado como o parâmetro advf para uma chamada para IOleCache::Cache ou IDataObject::D Advise, dependendo se pAdviseSink é NULL ou não NULL (veja abaixo). Em todos os outros casos, esse parâmetro deve ser NULL.

[in] rgFormatEtc

Quando renderopt é OLERENDER_FORMAT, aponta para uma matriz de estruturas FORMATETC . Quando pAdviseSink é NULL, cada elemento dessa matriz é passado como o parâmetro pFormatEtc para uma chamada para iOleCache::Cache do objeto. Isso popula os dados e o cache de apresentação gerenciados pelo manipulador de objetos em processo (normalmente o manipulador padrão) com apresentação ou outros dados armazenáveis em cache. Quando pAdviseSink não é NULL, cada elemento dessa matriz é passado como o parâmetro pFormatEtc para uma chamada para IDataObject::D Advise. Isso permite que o chamador (normalmente um contêiner OLE) faça seu próprio cache ou processamento de dados recebidos do objeto .

[in] lpAdviseSink

Quando renderopt é OLERENDER_FORMAT, pode ser um ponteiro IAdviseSink válido, indicando o cache personalizado ou o processamento de avisos de dados ou NULL, indicando o cache padrão de formatos de dados.

[in, out] rgdwConnection

Local para retornar a matriz de valores dwConnection retornados quando a interface pAdviseSink é registrada para cada conexão de consultoria usando IDataObject::D Advise ou NULL se as conexões de consultoria retornadas não forem necessárias. Esse parâmetro deverá ser NULL se pAdviseSink for NULL.

[in] pClientSite

Ponteiro para a interface primária pela qual o objeto solicitará serviços de seu contêiner. Esse parâmetro pode ser NULL; nesse caso, é responsabilidade do chamador estabelecer o site do cliente assim que possível usando IOleObject::SetClientSite.

[in] pStg

Ponteiro para o armazenamento a ser usado para o objeto e quaisquer dados padrão ou cache de apresentação estabelecidos para ele.

[out] ppvObj

Endereço da variável de ponteiro de saída 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.

Valor retornado

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

Código de retorno	Descrição
E_NOINTERFACE	O identificador de interface fornecido é inválido.
E_INVALIDARG	Um ou mais parâmetros são inválidos.

Comentários

A seguinte chamada para OleCreateLinkFromData:

OleCreateLinkFromData(pSrcDataObj, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

é equivalente à seguinte chamada para OleCreateLinkFromDataEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateLinkFromDataEx(pSrcDataObj, riid, renderopt, 1, &amp;advf, pFormatEtc, NULL, NULL, pClientSite, pStg, ppvObj);

As funções de instanciação existentes (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile e OleCreateLinkFromData), criam apenas uma única apresentação ou cache de formato de dados no local de cache padrão (dentro dos fluxos '\001OlePresXXX' do IStorage passado) durante a instanciação. Além disso, esses caches devem ser criados quando o objeto entrar no estado em execução. Como a maioria dos aplicativos exige o cache de pelo menos duas apresentações (tela e impressora) e pode exigir o cache de dados em um formato ou local diferente do manipulador, os aplicativos normalmente devem iniciar e desligar o servidor de objetos várias vezes para preparar seus caches de dados durante a criação do objeto, ou seja, Inserir Objeto, Inserir Objeto do Arquivo e Colar Objeto.

Versões estendidas dessas funções de criação resolvem esse problema. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx e OleCreateLinkFromDataEx contêm os seguintes novos parâmetros: dwFlags para indicar opções adicionais, cFormats para indicar quantos formatos armazenar em cache, rgAdvf, da enumeração ADVF , para especificar os sinalizadores de aviso para cada formato a ser armazenado em cache, pAdviseSink para indicar se o cache de apresentação (manipulador padrão) ou de dados (não manipulador padrão) é necessário, rgdwConnection para retornar cookies IDataObject::D Advise e rgFormatEtc, uma matriz de formatos em vez de um único formato.

Contêineres que exigem que várias apresentações sejam armazenadas em cache em seu nome pelo manipulador do objeto podem simplesmente chamar essas funções e especificar o número de formatos em cFormats, os sinalizadores ADVF para cada formato em rgAdvf e o conjunto de formatos em rgFormatEtc. Esses contêineres passam NULL para pAdviseSink.

Os contêineres que executam todos os seus próprios dados ou cache de apresentação executam essas mesmas etapas, mas passam um pAdviseSink não NULL. Eles executam seu próprio cache ou manipulação do objeto ou dos dados durante IAdviseSink::OnDataChange. Normalmente, esses contêineres nunca estabelecem as conexões de consultoria com ADVF_NODATA, embora não sejam impedidos de fazê-lo.

Essas novas funções são para documentos compostos OLE. Usando essas funções, os aplicativos podem evitar as etapas de inicialização e inicialização repetidas exigidas pelas funções atuais. Eles são direcionados a aplicativos de contêiner de Documento Composto OLE que usam dados padrão e cache de apresentação e também em aplicativos que fornecem seu próprio cache e transferência de dados do suporte subjacente a IDataObject::D Advise .

Requisitos


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