coCreateInstance 函数 (combaseapi.h)

创建并默认初始化与指定 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

另请参阅

CoCreateInstanceEx

CoGetClassObject

IClassFactory::CreateInstance

实例创建帮助程序函数