WeakRef クラス

  • [アーティクル]

クラシック COM ではなく、Windows ランタイムでのみ使用できる 弱い参照 を表します。 弱い参照は、アクセスできる場合とできない場合があるオブジェクトを表します。

構文

class WeakRef : public ComPtr<IWeakReference>;

メンバー

パブリック コンストラクター

名前 説明
WeakRef::WeakRef コンストラクター WeakRef クラスの新しいインスタンスを初期化します。
WeakRef::~WeakRef デストラクター WeakRef クラスの現在のインスタンスの初期化を解除します。

パブリック メソッド

名前 説明
WeakRef::As 指定した ComPtr ポインター パラメーターを、指定したインターフェイスを表すように設定します。
WeakRef::AsIID 指定した ComPtr ポインター パラメーターを、指定したインターフェイス ID を表すように設定します。
WeakRef::CopyTo 使用可能なインターフェイスへのポインターがあるなら、指定されたポインター変数にそれを割り当てます。

パブリック演算子

名前 説明
WeakRef::operator& 現在の WeakRef オブジェクトを表す ComPtrRef オブジェクトを返します。

解説

WeakRef オブジェクトを使用すると、"強い参照" が維持されます。これはオブジェクトと関連付けられ、有効な場合と無効な場合があります。 強い参照を取得するには、As() メソッドまたは AsIID() メソッドを呼び出します。 強い参照が有効な場合、関連付けられているオブジェクトにアクセスできます。 強い参照が無効な場合 (nullptr)、関連付けられているオブジェクトにアクセスできません。

通常、WeakRef オブジェクトは、外部スレッドや外部アプリケーションによって存在が制御されるオブジェクトを表すために使用されます。 たとえば、ファイル オブジェクトへの参照から WeakRef オブジェクトを構築します。 ファイルが開いている間、強い参照は有効です。 しかし、ファイルが閉じられた場合、強い参照は無効になります。

Windows SDK では As、AsIID、CopyTo の各メソッドの動作が変更されています。 次のコードのように、以前は、これらのうちのいずれかのメソッドを呼び出した後、強い参照が正常に取得されたかどうかを判別するために nullptr の WeakRef を調べることができました。

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
 

必要条件

ヘッダー: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 が空のベクターに初期化されます。 2 番目のコンストラクターにより、IWeakReference インターフェイスへのポインターから WeakRef オブジェクトが初期化されます。 3 番目のコンストラクターにより、ComPtr<IWeakReference> オブジェクトへの参照から WeakRef オブジェクトが初期化されます。 4 番目と 5 番目のコンストラクターにより、別の WeakRef オブジェクトから WeakRef オブジェクトが初期化されます。

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
インターフェイス ID。

ptr
この操作が完了した場合は、パラメーター U を表すオブジェクト。

戻り値

  • この操作が成功すると S_OK になります。失敗すると HRESULT (操作が失敗した理由を示す) になり、ptr は nullptr に設定されます。

  • この操作が成功すると S_OK になりますが、現在の WeakRef オブジェクトは既に解放されています。 パラメーターを ptr を nullptrに設定します。

  • この操作が成功すると S_OK になりますが、現在の WeakRef オブジェクトはパラメーター U から派生しません。 パラメーターを ptr を nullptrに設定します。

解説

パラメーター U が IWeakReference であるか、IInspectable から派生していない場合は、エラーが発生します。

最初のテンプレートは、コードで使用する必要があるフォームです。 2 番目のテンプレートは、内部ヘルパーの特殊化です。これは、auto 型推論キーワードなどの C++ 言語の機能をサポートします。

Windows 10 SDK 以降、弱い参照を取得できなかった場合、このメソッドを指定しても WeakRef インスタンスは nullptr に設定されません。このため、nullptr の WeakRef を確認するエラー チェック コードは避けてください。 代わりに、ptr の nullptr を確認してください。

WeakRef::AsIID

指定した ComPtr ポインター パラメーターを、指定したインターフェイス ID を表すように設定します。

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

パラメーター

riid
インターフェイス ID。

ptr
この操作の完了時の、パラメーター riidを表すオブジェクト。

戻り値

  • この操作が成功すると S_OK になります。失敗すると HRESULT (操作が失敗した理由を示す) になり、ptr は nullptr に設定されます。

  • この操作が成功すると S_OK になりますが、現在の WeakRef オブジェクトは既に解放されています。 パラメーターを ptr を nullptrに設定します。

  • この操作が成功すると S_OK になりますが、現在の WeakRef オブジェクトはパラメーター riid から派生しません。 パラメーターを ptr を nullptrに設定します。 (詳細については、「解説」を参照してください。)

解説

パラメーター riid が IInspectable から派生していない場合は、エラーが発生します。 このエラーは、戻り値よりも優先されます。

最初のテンプレートは、コードで使用する必要があるフォームです。 2 番目のテンプレート (ここでは示されていないが、ヘッダー ファイルでは宣言されている) は、auto 型推論キーワードなどの C++ 言語の機能をサポートしている内部ヘルパーの特殊化です。

Windows 10 SDK 以降、弱い参照を取得できなかった場合、このメソッドを指定しても WeakRef インスタンスは nullptr に設定されません。このため、nullptr の WeakRef を確認するエラー チェック コードは避けてください。 代わりに、nullptr の ptr を確認してください。

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
インターフェイス ID。 riid が IWeakReference から派生していない場合、エラーが発生します。

ptr
IInspectable または IWeakReference への二重間接ポインター。

戻り値

成功した場合は S_OK、そうでない場合は失敗を示す HRESULT。 詳細については、「解説」をご覧ください。

解説

S_OK の戻り値はこの操作が成功したことを示しますが、弱い参照が強い参照に解決されたかどうかは示していません。 S_OK が返される場合は、そのパラメーター ptr が強力な参照であること、つまりパラメーター ptr が nullptr と等しくないことをテストします。

Windows 10 SDK 以降、弱い参照を取得できなかった場合、このメソッドを指定しても WeakRef インスタンスは nullptr に設定されません。このため、nullptr の WeakRef を確認するエラー チェック コードは避けてください。 代わりに、nullptr の ptr を確認してください。

WeakRef::operator&

現在の WeakRef オブジェクトを表す ComPtrRef オブジェクトを返します。

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

戻り値

現在の WeakRef オブジェクトを表す ComPtrRef オブジェクト。

解説

WeakRef::operator& は、コードでの使用が想定されていない内部ヘルパー演算子です。