coCreateInstance 函数 (combaseapi.h)

项目
08/22/2023

创建并默认初始化与指定 CLSID 关联的类的单个对象。

如果只想在本地系统上创建一个对象，请调用 CoCreateInstance 。若要在远程系统上创建单个对象，请调用 CoCreateInstanceEx 函数。若要基于单个 CLSID 创建多个对象，请调用 CoGetClassObject 函数。

语法

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

参数

[in] rclsid

与将用于创建对象的数据和代码关联的 CLSID。

[in] pUnkOuter

如果 为 NULL，则指示对象不是作为聚合的一部分创建的。如果不是 NULL，则指向聚合对象的 IUnknown 接口的指针 (控制 IUnknown) 。

[in] dwClsContext

管理新创建对象的代码将在其中运行的上下文。这些值取自枚举 CLSCTX。

[in] riid

对要用于与对象通信的接口标识符的引用。

[out] ppv

接收 riid 中请求的接口指针的指针变量的地址。成功返回后，*ppv 包含请求的接口指针。失败时，*ppv 包含 NULL。

返回值

此函数可以返回以下值。

返回代码	说明
S_OK	已成功创建指定对象类的实例。
REGDB_E_CLASSNOTREG	指定的类未在注册数据库中注册。还可以指示在 CLSCTX 枚举中请求的服务器类型未注册，或者注册表中服务器类型的值已损坏。
CLASS_E_NOAGGREGATION	此类不能作为聚合的一部分创建。
E_NOINTERFACE	指定的类不实现请求的接口，或者控制 IUnknown 不公开请求的接口。
E_POINTER	ppv 参数为 NULL。

注解

CoCreateInstance 函数通过连接到与指定的 CLSID 关联的类对象、创建默认初始化实例以及释放类对象来提供便捷的快捷方式。因此，它封装了以下功能：

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

只需在本地计算机上创建对象的单个实例时，使用 CoCreateInstance 很方便。如果要在远程计算机上创建实例，请调用 CoCreateInstanceEx。创建多个实例时，获取指向类对象的 IClassFactory 接口的指针并根据需要使用其方法会更有效。在后一种情况下，应使用 CoGetClassObject 函数。

在 CLSCTX 枚举中，可以指定用于管理对象的服务器类型。常量可以是CLSCTX_INPROC_SERVER、CLSCTX_INPROC_HANDLER、CLSCTX_LOCAL_SERVER、CLSCTX_REMOTE_SERVER或这些值的任意组合。常量CLSCTX_ALL定义为所有四者的组合。有关使用这些常量之一或组合的详细信息，请参阅 CLSCTX。

UWP 应用程序

尽管 UWP 应用程序可以传递给 CoCreateInstance 的 CLSID 没有限制，但出于安全原因，许多对象会因 E_ACCESSDENIED 而失败，尤其是在它们未在进程内运行时。此外，即使可以成功创建对象，也可能在以后由于 UWP 安全约束、应用模型差异等原因而失败。具体而言，后台任务应限制它们与之通信的对象，以避免由于连接的备用状态而导致挂起或其他复杂情况。

示例

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

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	combaseapi.h (包括 Objbase.h)
Library	Ole32.lib
DLL	Ole32.dll