WeakRef 類別

代表 弱式參考 僅供 Windows 執行階段使用，而不供傳統 COM 使用。 弱式參考代表不一定可存取的物件。

語法

class WeakRef : public ComPtr<IWeakReference>;

成員

公用建構函式

名稱	描述
WeakRef::WeakRef 構造 函數	初始化 WeakRef 類別的新執行個體。
WeakRef::~WeakRef 析 構 函數	將 類別的 WeakRef 目前實例取消初始化。

公用方法

名稱	描述
WeakRef::As	將指定的 ComPtr 指標參數設定為表示指定的介面。
WeakRef::AsIID	設定指定的 ComPtr 指標參數，表示指定的介面識別碼。
WeakRef::CopyTo	指派介面指標 (如有提供) 給指定的指標變數。

公用運算子

名稱	描述
WeakRef::operator&	傳 ComPtrRef 回代表目前 WeakRef 物件的 物件。

備註

WeakRef物件會維護與 物件相關聯的強式參考 ，而且可能有效或無效。 As()呼叫 或 AsIID() 方法以取得強式參考。 當強式參考為有效時，它可以存取相關聯的物件。 強式參考無效時 (nullptr)，就無法存取相關聯的物件。

WeakRef物件通常用來表示其存在是由外部執行緒或應用程式所控制的物件。 例如，從檔案物件的參考建構 WeakRef 物件。 在檔案開啟時，強式參考是有效的。 但若檔案關閉，強式參考就變成無效的。

Windows SDK 中的 As 、 AsIID 和 CopyTo 方法有行為變更。 之前，呼叫上述任何方法之後，您可以檢查 WeakRefnullptr 是否成功取得強式參考，如下列程式碼所示：

WeakRef wr;
strongComptrRef.AsWeak(&wr);

// Now suppose that the object strongComPtrRef points to no longer exists
// and the following code tries to get a strong ref from the weak ref:
ComPtr<ISomeInterface> strongRef;
HRESULT hr = wr.As(&strongRef);

// This check won't work with the Windows 10 SDK version of the library.
// Check the input pointer instead.
if(wr == nullptr)
{
    wprintf(L"Couldn't get strong ref!");
}

使用 Windows 10 SDK 或更新版本時，上述程式碼無法運作。 請改為檢查 傳入的 nullptr 指標。

if (strongRef == nullptr)
{
    wprintf(L"Couldn't get strong ref!");
}

繼承階層

ComPtr
 └ WeakRef

需求

標頭：client.h

命名空間：Microsoft::WRL

WeakRef::WeakRef 建構函式

初始化 WeakRef 類別的新執行個體。

WeakRef();
WeakRef(
   decltype(__nullptr)
);

WeakRef(
   _In_opt_ IWeakReference* ptr
);

WeakRef(
   const ComPtr<IWeakReference>& ptr
);

WeakRef(
   const WeakRef& ptr
);

WeakRef(
   _Inout_ WeakRef&& ptr
);

參數

ptr
初始化目前 WeakRef 物件之現有物件的指標、參考或右值參考。

備註

第一個建構函式會初始化空 WeakRef 的物件。 第二個 WeakRef 建構函式會從介面的 IWeakReference 指標初始化 物件。 第三個 WeakRef 建構函式會從 物件的參考 ComPtr<IWeakReference> 初始化 物件。 第四個和第五個建構函式會從另一個 WeakRefWeakRef 物件初始化 物件。

WeakRef::~WeakRef 析 構 函數

將 類別的 WeakRef 目前實例取消初始化。

~WeakRef();

WeakRef::As

將指定的 ComPtr 指標參數設定為表示指定的介面。

template<typename U>
HRESULT As(
   _Out_ ComPtr<U>* ptr
);

template<typename U>
HRESULT As(
   _Out_ Details::ComPtrRef<ComPtr<U>> ptr
);

參數

U
介面識別碼。

ptr
當此作業完成時，代表參數 U 的物件。

傳回值

• S_OK 如果此作業成功，則為 ;否則，表示作業失敗原因的 HRESULT，且 ptr 設定為 nullptr 。

• S_OK 如果此作業成功，但目前的 WeakRef 物件已經釋放。 參數 ptr 設定為 nullptr。

• S_OK 如果這項作業成功，但目前的 WeakRef 物件不是衍生自 參數 U ， 參數 ptr 設定為 nullptr。

備註

如果 參數 U 為 IWeakReference ，或不是衍生自 IInspectable ，就會發出錯誤。

第一個範本是程式碼中應該使用的表單。 第二個範本是內部協助程式特製化;它支援 C++ 語言功能，例如 auto 類型推算關鍵字。

從 Windows 10 SDK 開始，如果無法取得弱式參考，這個方法就不會將 實例 nullptr 設定 WeakRef 為 ，因此您應該避免檢查 WeakRef 是否有 nullptr 的錯誤檢查程式碼。 請改為檢查 ptr 。 nullptr

WeakRef::AsIID

設定指定的 ComPtr 指標參數，表示指定的介面識別碼。

HRESULT AsIID(
   REFIID riid,
   _Out_ ComPtr<IInspectable>* ptr
);

參數

riid
介面識別碼。

ptr
這項作業完成時，表示參數 riid的物件。

傳回值

• S_OK 如果此作業成功，則為 ;否則，表示作業失敗原因的 HRESULT，且 ptr 設定為 nullptr 。

• S_OK 如果此作業成功，但目前的 WeakRef 物件已經釋放。 參數 ptr 設定為 nullptr。

• S_OK 如果這項作業成功，但目前的 WeakRef 物件不是衍生自 參數 riid ， 參數 ptr 設定為 nullptr。 (如需詳細資訊，請參閱＜備註＞)。

備註

如果 參數 riid 不是衍生自 IInspectable ，就會發出錯誤。 這個錯誤會取代傳回值。

第一個範本是程式碼中應該使用的表單。 第二個範本（此處未顯示，但在標頭檔中宣告）是內部的協助程式特製化，可支援 C++ 語言功能，例如 auto 類型推算關鍵字。

從 Windows 10 SDK 開始，如果無法取得弱式參考，這個方法就不會將 實例 nullptr 設定 WeakRef 為 ，因此您應該避免檢查 WeakRef 是否有 nullptr 的錯誤檢查程式碼。 請改為檢查 ptrnullptr 。

WeakRef::CopyTo

指派介面指標 (如有提供) 給指定的指標變數。

HRESULT CopyTo(
   REFIID riid,
   _Deref_out_ IInspectable** ptr
);

template<typename U>
HRESULT CopyTo(
   _Deref_out_ U** ptr
);

HRESULT CopyTo(
   _Deref_out_ IWeakReference** ptr
);

參數

U
IInspectable指標介面。 如果 U 不是衍生自 IInspectable ，就會發出錯誤。

riid
介面識別碼。 如果 riid 不是衍生自 IWeakReference ，就會發出錯誤。

ptr
或 IWeakReference 的雙重間接指標 IInspectable 。

傳回值

S_OK 如果成功，則為 ;否則，描述失敗的 HRESULT。 如需詳細資訊，請參閱備註。

備註

的 S_OK 傳回值表示此作業成功，但不會指出弱式參考是否已解析為強式參考。 如果 S_OK 傳回 ，則測試該參數 ptr 是強式參考;也就是說，參數 ptr 不等於 nullptr 。

從 Windows 10 SDK 開始，如果無法取得弱式參考，這個方法就不會將 實例 nullptr 設定 WeakRef 為 ，因此您應該避免錯誤檢查檢查檢查 WeakRef 是否有 nullptr 的程式碼。 請改為檢查 ptrnullptr 。

WeakRef::operator&

傳 ComPtrRef 回代表目前 WeakRef 物件的 物件。

Details::ComPtrRef<WeakRef> operator&() throw()

傳回值

ComPtrRef表示目前 WeakRef 物件的 物件。

備註

WeakRef::operator& 是內部協助程式運算子，不是在您的程式碼中使用。