CoInitializeEx 函式 (combaseapi.h)

  • 發行項

初始化 COM 連結庫以供呼叫線程使用、設定線程的並行模型，並在需要時為線程建立新的 Apartment。

如果您想要使用 Windows 執行階段 API，或想要同時使用 COM 和 Windows 執行階段 元件，您應該呼叫 Windows：：Foundation：：Initialize 來初始化線程，而不是 CoInitializeEx。 Windows：：Foundation：：Initialize 足以用於 COM元件。

語法

HRESULT CoInitializeEx(
  [in, optional] LPVOID pvReserved,
  [in]           DWORD  dwCoInit
);

參數

[in, optional] pvReserved

此參數是保留的，而且必須是 NULL。

[in] dwCoInit

線程的並行模型和初始化選項。 此參數的值取自 COINIT 列舉。 您可以使用 來自 COINIT 的任何值組合，但無法同時設定COINIT_APARTMENTTHREADED和COINIT_MULTITHREADED旗標。 預設值為 COINIT_MULTITHREADED。

傳回值

此函式可以傳回標準傳回值E_INVALIDARG、E_OUTOFMEMORY和E_UNEXPECTED，以及下列值。

傳回碼 描述
S_OK
 COM 連結庫在此線程上已成功初始化。
S_FALSE
 COM 連結庫已在此線程上初始化。
RPC_E_CHANGED_MODE
 先前對 CoInitializeEx 的呼叫會將此線程的並行模型指定為多線程 Apartment (MTA) 。 這也表示已從中性線程 Apartment 變更為單個線程 Apartment。

備註

CoInitializeEx 至少必須呼叫一次，而且通常只會針對使用 COM 連結庫的每個線程呼叫一次。 只要相同線程傳遞相同的並行旗標，就允許 對 CoInitializeEx 進行多個呼叫，但後續的有效呼叫會傳回S_FALSE。 若要在線程上正常關閉 COM 連結庫，每次成功呼叫 CoInitialize 或 CoInitializeEx，包括傳回S_FALSE的任何呼叫，都必須由 對 CoUninitialize 的對應呼叫進行平衡。

您必須先在線程上初始化 COM 連結庫，才能呼叫 CoGetMalloc 以外的任何連結庫函式，以取得標準配置器的指標，以及記憶體配置函式。

否則，COM 函式會傳回CO_E_NOTINITIALIZED。

設定線程的並行模型之後，就無法變更。 在先前初始化為多線程的 Apartment 上 呼叫 CoInitialize 將會失敗，並傳回RPC_E_CHANGED_MODE。

在單個線程 Apartment 中建立的物件 (STA) 只會從其 Apartment 的線程接收方法呼叫，因此呼叫會串行化，而且只有在 呼叫 PeekMessage 或 SendMessage 函式) 時，才會 (到達消息佇列界限。

在多線程 Apartment (MTA) COM 線程上建立的對象，必須能夠隨時接收來自其他線程的方法呼叫。 您通常會使用重要區段、旗號或 Mutex 等同步處理基本類型，在多線程物件的程式代碼中實作某種形式的並行控制，以協助保護對象的數據。

當設定為在中性線程 Apartment 中執行的物件， (NTA) 是由 STA 或 MTA 中的線程呼叫時，該線程會傳送至 NTA。 如果這個線程後續呼叫 CoInitializeEx，呼叫會失敗並傳回RPC_E_CHANGED_MODE。

因為 OLE 技術不是安全線程， 所以 OleInitialize 函式會使用 COINIT_APARTMENTTHREADED 旗標呼叫 CoInitializeEx 。 因此，針對多線程物件並行初始化的 Apartment 無法使用 OleInitialize 所啟用的功能。

因為無法控制載入或卸除同進程伺服器的順序，所以請勿從 DllMain 函式呼叫 CoInitialize、CoInitializeEx 或 CoUninitialize。

規格需求

需求 值
最低支援的用戶端 Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows 2000 Server [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 combaseapi.h (包含 Objbase.h)
程式庫 Ole32.lib
Dll Ole32.dll

另請參閱

進程、線程和 Apartment