Función CoCreateInstance (combaseapi.h)

Artículo
08/22/2023

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