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 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 combaseapi.h (包含 Objbase.h)
程式庫 Ole32.lib
Dll Ole32.dll

另請參閱

CoCreateInstanceEx

CoGetClassObject

IClassFactory::CreateInstance

實例建立協助程式函式