Compartir a través de


Función CoCreateInstance (combaseapi.h)

Crea y inicializa de forma predeterminada un único objeto de la clase asociada a un CLSID especificado.

Llame a CoCreateInstance cuando desee crear solo un objeto en el sistema local. Para crear un único objeto en un sistema remoto, llame a la función CoCreateInstanceEx . Para crear varios objetos basados en un único CLSID, llame a la función CoGetClassObject .

Sintaxis

HRESULT CoCreateInstance(
  [in]  REFCLSID  rclsid,
  [in]  LPUNKNOWN pUnkOuter,
  [in]  DWORD     dwClsContext,
  [in]  REFIID    riid,
  [out] LPVOID    *ppv
);

Parámetros

[in] rclsid

CLSID asociado a los datos y el código que se usarán para crear el objeto.

[in] pUnkOuter

Si es NULL, indica que el objeto no se está creando como parte de un agregado. Si no es NULL, puntero a la interfaz IUnknown del objeto agregado (el control IUnknown).

[in] dwClsContext

Contexto en el que se ejecutará el código que administra el objeto recién creado. Los valores se toman de la enumeración CLSCTX.

[in] riid

Referencia al identificador de la interfaz que se va a usar para comunicarse con el objeto .

[out] ppv

Dirección de la variable de puntero que recibe el puntero de interfaz solicitado en riid. Tras la devolución correcta, *ppv contiene el puntero de interfaz solicitado. Tras un error, *ppv contiene NULL.

Valor devuelto

Esta función puede devolver los siguientes valores.

Código devuelto Descripción
S_OK
Se creó correctamente una instancia de la clase de objeto especificada.
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.
E_NOINTERFACE
La clase especificada no implementa la interfaz solicitada o el control IUnknown no expone la interfaz solicitada.
E_POINTER
El parámetro ppv es NULL.

Comentarios

La función CoCreateInstance proporciona un método abreviado práctico al conectarse al objeto de clase asociado al CLSID especificado, crear una instancia inicializada de forma predeterminada y liberar el objeto de clase. Por lo tanto, encapsula la siguiente funcionalidad:

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj);
pCF->Release(); 

Es conveniente usar CoCreateInstance cuando necesite crear solo una instancia de un objeto en el equipo local. Si va a crear una instancia en un equipo remoto, llame a CoCreateInstanceEx. Al crear varias instancias, es más eficaz obtener un puntero a la interfaz IClassFactory del objeto de clase y usar sus métodos según sea necesario. En este último caso, debe usar la función CoGetClassObject .

En la enumeración CLSCTX , puede especificar el tipo de servidor que se usa para administrar el objeto. Las constantes pueden ser CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER o cualquier combinación de estos valores. La constante CLSCTX_ALL se define como la combinación de los cuatro. Para obtener más información sobre el uso de una o una combinación de estas constantes, vea CLSCTX.

Aplicaciones para UWP

Aunque no hay restricciones en las que CLSIDs una aplicación para UWP puede pasar a CoCreateInstance, muchos objetos producirán un error E_ACCESSDENIED por motivos de seguridad, especialmente si no se ejecutan en proceso. Además, incluso si puedes crear correctamente un objeto, es posible que se produzca un error más adelante debido a restricciones de seguridad de UWP, diferencias en el modelo de aplicación, etc. En concreto, las tareas en segundo plano deben limitar los objetos con los que se comunican para evitar bloqueos u otras complicaciones debido a un bloqueo conectado.

Ejemplos

// Create WIC factory
hr = CoCreateInstance(
    CLSID_WICImagingFactory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&m_pIWICFactory)
    );

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

CoCreateInstanceEx

CoGetClassObject

IClassFactory::CreateInstance

Funciones auxiliares de creación de instancias