Compartir a través de

Función OleCreateEmbeddingHelper (ole2.h)

  • Artículo

Crea un objeto auxiliar de inserción OLE mediante código proporcionado por la aplicación agregado con partes del controlador de objetos predeterminado OLE. Este objeto auxiliar se puede crear y usar en un contexto y un rol específicos, según lo determinado por el autor de la llamada.

Sintaxis

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 de la clase que se va a ayudar.

[in] pUnkOuter

Si el asistente de inserción se va a agregar, puntero a la interfaz IUnknown del objeto externo. Si no se va a agregar, aunque esto es poco frecuente, el valor debe ser NULL.

[in] flags

DWORD que contiene marcas que especifican el rol y el contexto de creación para el asistente de inserción. Para conocer los valores legales, consulte la siguiente sección Comentarios.

[in] pCF

Puntero a la interfaz IClassFactory en el objeto de clase que usa la función para crear el objeto secundario. En algunas situaciones, este valor puede ser NULL. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in] riid

Referencia al identificador de la interfaz deseada por el autor de la llamada.

[out] lplpObj

Dirección de la variable de puntero que recibe el puntero de interfaz solicitado en riid. Tras la devolución correcta, *ppvObj contiene el puntero de interfaz solicitado en el asistente de inserción recién creado.

Valor devuelto

Esta función devuelve S_OK si se ejecuta correctamente. Otros valores posibles son los siguientes.

Código devuelto Descripción
E_OUTOFMEMORY
 Memoria insuficiente para la operación.
E_INVALIDARG
Uno o varios parámetros no son válidos.
E_UNEXPECTED
 Se produjo un error inesperado.
E_NOINTERFACE
 El identificador de interfaz proporcionado no es válido.

Comentarios

La función OleCreateEmbeddingHelper crea un objeto que admite las mismas implementaciones de interfaz que se encuentran en el controlador predeterminado, pero que tiene enlaces adicionales que permiten su uso más general que simplemente como un objeto de controlador. Las dos llamadas siguientes producen el mismo resultado:

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

El asistente de inserción es aggregatable; pUnkOuter es el IUnknown de control del agregado del que el asistente de inserción debe formar parte. Se usa para crear una nueva instancia del controlador predeterminado OLE, que se puede usar para admitir objetos en varios roles. El llamador pasa un puntero a su implementación de IClassFactory a OleCreateEmbeddingHelper. A continuación, este objeto y el controlador predeterminado se agregan para crear el nuevo objeto auxiliar de inserción.

Normalmente, la función OleCreateEmbeddingHelper se usa para admitir una de las siguientes implementaciones:

  • Aplicación de objeto EXE que se usa como contenedor y servidor, y que admite la inserción de objetos en sí mismo. En este caso, CreateEmbeddingHelper permite que el objeto admita las interfaces que normalmente solo se admiten en el controlador. Para ello, la aplicación primero debe registrar su CLSID para distintos contextos, realizando dos llamadas de registro a la función CoRegisterClassObject , en lugar de una, como se indica a continuación:
    CoRegisterClassObject(clsidMe, pUnkCfLocal, CLSCTX_LOCAL_SERVER, 
        REGCLS_MULTI_SEPARATE...) 
 
    CoRegisterClassObject(clsidMe, pUnkCfInProc, CLSCTX_INPROC_SERVER, 
    
        REGCLS_MULTI_SEPARATE...)

    En estas llamadas, pasaría diferentes implementaciones de generador de clases a cada una de pUnkCfLocal y pUnkCfInProc. El generador de clases al que apunta pUnkCfLocal se usaría para crear objetos que se van a incrustar en un proceso remoto, que es el caso normal que usa un objeto de controlador asociado al cliente. Sin embargo, cuando un servidor crea un objeto e lo inserta dentro de sí mismo, pUnkCfInProc apunta a un objeto de clase que puede crear un objeto que admita las interfaces del controlador. La clase local se usa para crear el objeto y la clase en proceso crea el asistente de inserción, pasando el puntero al generador de clases del primer objeto en pCF.

  • Un controlador de objetos en proceso personalizado, en cuyo caso, el archivo DLL crea el asistente de inserción pasando un puntero a una implementación privada de IClassFactory en pCF.
El parámetro flags indica cómo se va a usar el asistente de inserción y cómo y cuándo se inicializa el asistente de inserción. Los valores de las marcas se obtienen mediante la combinación de valores OR de la tabla siguiente.
Valores para el parámetro flags Propósito
EMBDHLP_INPROC_HANDLER Crea un asistente de inserción que se puede usar con aplicaciones de objetos DLL; específicamente, el asistente expone las características de almacenamiento en caché del controlador de objetos predeterminado.
EMBDHLP_INPROC_SERVER Crea un asistente de inserción que se va a usar como parte de un servidor en proceso. pCF no puede ser NULL.
EMBDHLP_CREATENOW Crea el objeto secundario utilizando pCF inmediatamente; Si pCF es NULL, se usa el administrador de proxy estándar.
EMBDHLP_DELAYCREATE Retrasa la creación del objeto secundario hasta que sea necesario (cuando el asistente se coloca en el estado en ejecución) para mejorar la velocidad y el uso de memoria. pCF no debe ser NULL. La marca EMBDHLP_INPROC_HANDLER no se puede usar con esta marca.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado ole2.h
Library Ole32.lib
Archivo DLL Ole32.dll
Conjunto de API ext-ms-win-com-ole32-l1-1-5 (introducido en Windows 10, versión 10.0.15063)

Consulte también

OleCreateDefaultHandler