Función CoCreateInstanceEx (combaseapi.h)

Crea una instancia de una clase específica en un equipo específico.

Sintaxis

HRESULT CoCreateInstanceEx(
  [in]      REFCLSID     Clsid,
  [in]      IUnknown     *punkOuter,
  [in]      DWORD        dwClsCtx,
  [in]      COSERVERINFO *pServerInfo,
  [in]      DWORD        dwCount,
  [in, out] MULTI_QI     *pResults
);

Parámetros

[in] Clsid

El CLSID del objeto que se va a crear.

[in] punkOuter

Si este parámetro no es NULL, indica que la instancia se está creando como parte de un agregado, y punkOuter se va a usar como control de IUnknown de la nueva instancia. Actualmente, la agregación no es compatible entre procesos ni entre equipos. Al crear una instancia de un objeto fuera del proceso, se devolverá CLASS_E_NOAGGREGATION si punkOuter no es NULL.

[in] dwClsCtx

Valor de la enumeración CLSCTX .

[in] pServerInfo

Información sobre el equipo en el que se va a crear una instancia del objeto. Consulte COSERVERINFO. Este parámetro puede ser NULL, en cuyo caso se crea una instancia del objeto en el equipo local o en el equipo especificado en el registro en el valor RemoteServerName de la clase, según la interpretación del parámetro dwClsCtx .

[in] dwCount

Número de estructuras en pResults. Este valor debe ser mayor que 0.

[in, out] pResults

Matriz de estructuras de MULTI_QI . Cada estructura tiene tres miembros: el identificador de una interfaz solicitada (pIID), la ubicación para devolver el puntero de interfaz (pItf) y el valor devuelto de la llamada a QueryInterface (hr).

Valor devuelto

Esta función puede devolver el valor devuelto estándar E_INVALIDARG, así como los siguientes valores.

Código devuelto	Descripción
S_OK	Indica que se completó correctamente.
REGDB_E_CLASSNOTREG	Una clase especificada no está registrada en la base de datos de registro. También puede indicar que el tipo de servidor solicitado en la enumeración CLSCTX no está registrado o los valores de los tipos de servidor del registro están dañados.
CLASS_E_NOAGGREGATION	Esta clase no se puede crear como parte de un agregado.
CO_S_NOTALLINTERFACES	Al menos una, pero no todas las interfaces solicitadas en la matriz pResults se recuperaron correctamente. El miembro hr de cada una de las estructuras de MULTI_QI en pResults indica con S_OK o E_NOINTERFACE si se devolvió la interfaz específica.
E_NOINTERFACE	Ninguna de las interfaces solicitadas en la matriz pResults se recuperó correctamente.

Comentarios

CoCreateInstanceEx crea un único objeto sin inicializar asociado al CLSID especificado en un equipo remoto especificado. Se trata de una extensión de la función CoCreateInstance, que crea un objeto solo en el equipo local. Además, en lugar de solicitar una sola interfaz y obtener un único puntero a esa interfaz, CoCreateInstanceEx permite especificar una matriz de estructuras, cada una que apunta a un identificador de interfaz (IID) en la entrada y, en devolución, que contiene (si está disponible) un puntero a la interfaz solicitada y el valor devuelto de la llamada QueryInterface para esa interfaz. Esto permite menos viajes de ida y vuelta entre equipos.

Esta función encapsula tres llamadas: en primer lugar, a CoGetClassObject para conectarse al objeto de clase asociado al CLSID especificado, especificando la ubicación de la clase; en segundo lugar, en IClassFactory::CreateInstance para crear una instancia sin inicializar y, por último, en IClassFactory::Release, para liberar el objeto de clase.

El objeto que se crea debe inicializarse a través de una llamada a una de las interfaces de inicialización (como IPersistStorage::Load). Dos funciones, CoGetInstanceFromFile y CoGetInstanceFromIStorage encapsulan tanto la creación de la instancia como la inicialización a partir de los orígenes obvios.

La estructura COSERVERINFO que se pasa como parámetro pServerInfo contiene la configuración de seguridad que COM usará al crear una nueva instancia del objeto especificado. Tenga en cuenta que este parámetro no influye en la configuración de seguridad utilizada al realizar llamadas de método en el objeto creado por instancias. Esas opciones de seguridad son configurables, por interfaz, con la función CoSetProxyBlanket . Consulte también IClientSecurity::SetBlanket.

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	combaseapi.h (incluya Objbase.h)
Library	Ole32.lib
Archivo DLL	Ole32.dll

Consulte también

CoGetInstanceFromFile

CoGetInstanceFromIStorage