Compartilhar via

Função OleCreateEmbeddingHelper (ole2.h)

  • Artigo

Cria um objeto auxiliar de inserção OLE usando código fornecido pelo aplicativo agregado com partes do manipulador de objetos padrão OLE. Esse objeto auxiliar pode ser criado e usado em um contexto e uma função específicos, conforme determinado pelo chamador.

Sintaxe

HRESULT OleCreateEmbeddingHelper(
  [in]  REFCLSID       clsid,
  [in]  LPUNKNOWN      pUnkOuter,
  [in]  DWORD          flags,
  [in]  LPCLASSFACTORY pCF,
  [in]  REFIID         riid,
  [out] LPVOID         *lplpObj
);

Parâmetros

[in] clsid

CLSID da classe a ser ajudada.

[in] pUnkOuter

Se o auxiliar de inserção deve ser agregado, ponteiro para a interface IUnknown controladora do objeto externo. Se não for para ser agregado, embora isso seja raro, o valor deve ser NULL.

[in] flags

DWORD contendo sinalizadores que especificam a função e o contexto de criação para o auxiliar de inserção. Para obter valores legais, consulte a seção Comentários a seguir.

[in] pCF

Ponteiro para a interface IClassFactory no objeto de classe que a função usa para criar o objeto secundário. Em algumas situações, esse valor pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[in] riid

Referência ao identificador da interface desejada pelo chamador.

[out] lplpObj

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 auxiliar de inserção 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
E_OUTOFMEMORY
 Memória insuficiente para a operação.
E_INVALIDARG
Um ou mais parâmetros são inválidos.
E_UNEXPECTED
 Ocorreu um erro inesperado.
E_NOINTERFACE
 O identificador de interface fornecido é inválido.

Comentários

A função OleCreateEmbeddingHelper cria um objeto que dá suporte às mesmas implementações de interface encontradas no manipulador padrão, mas que tem ganchos adicionais que permitem que ele seja usado de forma mais geral do que apenas como um objeto manipulador. As duas chamadas a seguir produzem o mesmo resultado:

OleCreateEmbeddingHelper(clsid, pUnkOuter, EMBDHLP_INPROC_HANDLER | 
    EMBDHLP_CREATENOW, NULL, iid, ppvObj) 
 
OleCreateDefaultHandler(clsid, pUnkOuter, iid, ppvObj)

O auxiliar de inserção é agregável; pUnkOuter é o IUnknown controlador da agregação da qual o auxiliar de inserção deve fazer parte. Ele é usado para criar uma nova instância do manipulador padrão OLE, que pode ser usada para dar suporte a objetos em várias funções. O chamador passa um ponteiro para sua implementação IClassFactory para OleCreateEmbeddingHelper. Esse objeto e o manipulador padrão são agregados para criar o novo objeto auxiliar de inserção.

A função OleCreateEmbeddingHelper geralmente é usada para dar suporte a uma das seguintes implementações:

  • Um aplicativo de objeto EXE que está sendo usado como um contêiner e um servidor e que dá suporte à inserção de objetos em si mesmo. Para esse caso, CreateEmbeddingHelper permite que o objeto dê suporte às interfaces geralmente compatíveis apenas no manipulador. Para fazer isso, o aplicativo deve primeiro registrar seu CLSID para contextos diferentes, fazendo duas chamadas de registro para a função CoRegisterClassObject , em vez de uma, da seguinte maneira:
    CoRegisterClassObject(clsidMe, pUnkCfLocal, CLSCTX_LOCAL_SERVER, 
        REGCLS_MULTI_SEPARATE...) 
 
    CoRegisterClassObject(clsidMe, pUnkCfInProc, CLSCTX_INPROC_SERVER, 
    
        REGCLS_MULTI_SEPARATE...)

    Nessas chamadas, você transmitiria diferentes implementações de fábrica de classes para cada um dos pUnkCfLocal e pUnkCfInProc. A fábrica de classes apontada por pUnkCfLocal seria usada para criar objetos que devem ser inseridos em um processo remoto, que é o caso normal que usa um objeto manipulador associado ao cliente. No entanto, quando um servidor cria um objeto e o insere dentro de si mesmo, pUnkCfInProc aponta para um objeto de classe que pode criar um objeto que dá suporte às interfaces do manipulador. A classe local é usada para criar o objeto e a classe em processo cria o auxiliar de inserção, passando o ponteiro para a fábrica de classes do primeiro objeto no pCF.

  • Um manipulador de objeto em processo personalizado, nesse caso, a DLL cria o auxiliar de inserção passando um ponteiro para uma implementação privada de IClassFactory no pCF.
O parâmetro flags indica como o auxiliar de inserção deve ser usado e como e quando o auxiliar de inserção é inicializado. Os valores para sinalizadores são obtidos por valores or-ing juntos da tabela a seguir.
Valores para o parâmetro flags Finalidade
EMBDHLP_INPROC_HANDLER Cria um auxiliar de inserção que pode ser usado com aplicativos de objeto DLL; especificamente, o auxiliar expõe os recursos de cache do manipulador de objetos padrão.
EMBDHLP_INPROC_SERVER Cria um auxiliar de inserção que deve ser usado como parte de um servidor em processo. pCF não pode ser NULL.
EMBDHLP_CREATENOW Cria o objeto secundário usando pCF imediatamente; se pCF for NULL, o gerenciador de proxy padrão será usado.
EMBDHLP_DELAYCREATE Atrasa a criação do objeto secundário até que ele seja necessário (quando o auxiliar é colocado no estado em execução) para aprimorar o uso de velocidade e memória. pCF não deve ser NULL. O sinalizador EMBDHLP_INPROC_HANDLER não pode ser usado com esse sinalizador.

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

OleCreateDefaultHandler