CoCreateInstance 函式 (combaseapi.h)

發行項
02/28/2024

建立和預設初始化與指定 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