RoGetAgileReference 函式 (combaseapi.h)

為指定介面所指定的物件建立敏捷式參考。

語法

HRESULT RoGetAgileReference(
  [in]  AgileReferenceOptions options,
  [in]  REFIID                riid,
  [in]  IUnknown              *pUnk,
  [out] IAgileReference       **ppAgileReference
);

參數

[in] options

註冊選項。

[in] riid

取得敏捷式參考之 物件的介面標識符。

[in] pUnk

要封裝在敏捷式參考中的介面指標。 它必須是與 riid相同的類型。 它可以是進程內物件的指標，或是物件的 Proxy 指標。

[out] ppAgileReference

物件的敏捷式參考。 呼叫 Resolve 方法，將對象當地語系化為呼叫 Resolve 的 Apartment。

傳回值

此函式可以傳回其中一個值。

傳回值	描述
S_OK	語言函式已順利完成。
E_INVALIDARG	選項 參數無效 。
E_OUTOFMEMORY	因為記憶體不足的狀況，所以無法建構敏捷式參考。
E_NOINTERFACE	pUnk 參數不支援 riid 參數指定的介面識別碼。
CO_E_NOT_SUPPORTED	對象會實作 INoMarshal 介面。

備註

在現有物件上呼叫 RoGetAgileReference 函式，以要求物件的敏捷式參考。 物件可能或可能不是敏捷式，但傳回的 IAgileReference 是敏捷式的。 敏捷式參考可以傳遞至相同進程中的另一個 Apartment，其中原始物件是使用 IAgileReference 介面擷取。

這在概念上類似於現有的全域介面數據表 (GIT) 。 取得 IAgileReference 並用來直接擷取物件，而不是與 GIT 互動。 就像 GIT 僅依進程一樣，敏捷式參考是個別進程，而且無法封送處理。

敏捷式參考功能可改善 GIT 的效能。 敏捷式參考預設會執行積極式封送處理，這會在物件從與敏捷式參考建立位置不同的 Apartment 中擷取對象的情況下，儲存跨 Apartment 呼叫。 為了提升效能， RoGetAgileReference 函式的使用者可以使用相同的介面來建立 IAgileReference 並解析原始物件。 這會儲存額外的 QueryInterface 呼叫，以從解析的物件取得所需的介面。

例如，您有名為 CDemoExample 的非敏捷式物件，它會實作 IDemo 和 IExample 介面。 呼叫 RoGetAgileReference 函式，並使用 IID_IDemo 傳遞物件。 您會回到 IAgileReference 介面指標，這是敏捷式的，因此您可以將它傳遞至不同的 Apartment。 在其他 Apartment 中，使用 IID_IExample 呼叫 Resolve 方法。 您會返回可在此 Apartment 中使用的 IExample 指標。 這個IExample指標是連接到原始 CDemoExample 物件的 IExample Proxy。 敏捷式參考會處理作業的複雜性，例如手動封送處理至數據流，並在 Apartment 界限的另一端解除封送處理。

規格需求

需求	值
最低支援的用戶端	Windows 8.1 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器	Windows Server 2012 R2 [傳統型應用程式 |UWP 應用程式]
目標平台	Windows
標頭	combaseapi.h
程式庫	Ole32.lib
Dll	Ole32.dll

另請參閱

AgileReferenceOptions

IAgileReference