Share via

CoCreateFreeThreadedMarshaler 函式 (combaseapi.h)

  • 發行項

建立能夠進行內容相依封送處理的可匯總物件。

語法

HRESULT CoCreateFreeThreadedMarshaler(
  [in]  LPUNKNOWN punkOuter,
  [out] LPUNKNOWN *ppunkMarshal
);

參數

[in] punkOuter

匯總物件控制 IUnknown 之物件的指標。

[out] ppunkMarshal

接收可匯總封送處理器之介面指標的指標變數位址。

傳回值

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

傳回碼 描述
S_OK
 封送處理器已建立。

備註

CoCreateFreeThreadedMarshaler 函式可讓物件在相同進程中的線程之間有效率地封送處理介面指標。 如果您的物件不支援線程間封送處理，您就不需要呼叫此函式。 它適用於免費線程 DLL 伺服器，這些伺服器必須直接由進程中的所有線程存取，即使是與單個線程 Apartment 相關聯的線程也一樣。 它自定義封送處理將實際記憶體指標封送處理到其他 Apartment 中做為假的「Proxy」，進而提供所有呼叫端的直接存取權，即使它們不是自由線程也一樣。

CoCreateFreeThreadedMarshaler 函式會執行下列工作：

  1. 建立自由線程封送處理器物件。
  2. 將此封送處理器匯總至 punkOuter 參數所指定的物件。 這個物件通常是其介面指標要封送處理的物件。
匯總物件的 IMarshal 實作應該將 查詢Interface 呼叫委派給自由線程封送處理器的 IUnknown IID_IMarshal。 收到呼叫時，自由線程封送處理器會執行下列工作：
  1. 檢查 CoMarshalInterface 函式的 dwDestContext 參數所指定的目的地內容。
  2. 如果目的地內容MSHCTX_INPROC，請將介面指標複製到封送處理數據流。
  3. 如果目的地內容是任何其他值，請尋找或建立 COM 預設 (標準) 封送處理器的實例，並將封送處理委派給它。
dwDestContext 的值來自 MSHCTX 列舉。 MSHCTX_INPROC表示介面指標是在相同進程中的不同線程之間封送處理。 因為這兩個線程都可以存取相同的位址空間，所以用戶端線程可以直接取值指標，而不需要直接呼叫 Proxy。 在其他所有情況下，都需要 Proxy，因此 CoCreateFreeThreadedMarshaler 會將封送處理作業委派給 COM 的預設實作。

請務必使用 CoCreateFreeThreadedMarshaler 函式來練習。 這是因為匯總自由線程封送處理器的物件效能是透過 COM 規則的計算違規來取得，除非物件在特定限制內運作，否則不會定義行為的風險。 最重要的限制包括：

  • 自由線程封送處理器對象無法儲存物件上介面的直接指標，該介面不會將自由線程封送處理器匯總為其狀態的一部分。 如果對像是使用對一般單一線程匯總物件的直接參考，它可能會中斷其單一線程屬性。 如果對像是使用對一般多線程匯總物件的直接參考，這些對象的行為可能會對直接單個線程匯總用戶端的需求沒有敏感度。 例如，這些物件可以微調新的線程，並將參數傳遞至參考一般單一線程匯總對象的線程。
  • 自由線程封送處理器對象無法保存對其他 Apartment 中物件的 Proxy 參考。 Proxy 對線程模型很敏感，而且如果由錯誤的用戶端呼叫，則可以傳回RPC_E_WRONG_THREAD。

規格需求

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

另請參閱

CoGetInterfaceAndReleaseStream

CoMarshalInterThreadInterfaceInStream