Função OleCreateEx (ole2.h)
Estende a funcionalidade OleCreate dando suporte à instanciação mais eficiente de objetos em contêineres que exigem cache de vários formatos ou dados de apresentação, em vez do formato único com suporte do OleCreate.
Sintaxe
HRESULT OleCreateEx(
[in] REFCLSID rclsid,
[in] REFIID riid,
[in] DWORD dwFlags,
[in] DWORD renderopt,
[in] ULONG cFormats,
[in] DWORD *rgAdvf,
[in] LPFORMATETC rgFormatEtc,
[in] IAdviseSink *lpAdviseSink,
[out] DWORD *rgdwConnection,
[in] LPOLECLIENTSITE pClientSite,
[in] LPSTORAGE pStg,
[out] LPVOID *ppvObj
);
Parâmetros
[in] rclsid
Identifica a classe do objeto a ser criado.
[in] riid
Referência ao identificador da interface do objeto a ser retornado.
[in] dwFlags
Esse valor 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 cFormats, 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 cFormats 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 . Em todos os outros casos, esse parâmetro deve ser NULL.
[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. Em todos os outros casos, esse parâmetro deve ser NULL.
[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. Deve 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. Esse parâmetro pode não ser NULL.
[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.
Retornar valor
Essa função retorna S_OK em caso de êxito. Outros valores possíveis incluem o seguinte.
| Código de retorno | Descrição |
|---|---|
|
O identificador de interface fornecido é inválido. |
Comentários
A seguinte chamada para OleCreate:
OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);
é equivalente à seguinte chamada para OleCreateEx:
DWORD advf = ADVF_PRIMEFIRST;
OleCreateEx(rclsid, riid, renderopt, 1, &advf, pFormatEtc, 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 pFormatEtc, 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 pFormatEtc. 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
| 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 |