クラシック COM ではなく、Windows ランタイムでのみ使用できる 弱い参照 を表します。 弱い参照は、アクセスできる場合とできない場合があるオブジェクトを表します。
構文
class WeakRef : public ComPtr<IWeakReference>;
メンバー
パブリック コンストラクター
| 名前 | 説明 |
|---|---|
WeakRef::WeakRef コンストラクター |
WeakRef クラスの新しいインスタンスを初期化します。 |
WeakRef::~WeakRef デストラクター |
WeakRef クラスの現在のインスタンスの初期化を解除します。 |
パブリック メソッド
| 名前 | 説明 |
|---|---|
WeakRef::As |
指定した ComPtr ポインター パラメーターを、指定したインターフェイスを表すように設定します。 |
WeakRef::AsIID |
指定した ComPtr ポインター パラメーターを、指定したインターフェイス ID を表すように設定します。 |
WeakRef::CopyTo |
使用可能なインターフェイスへのポインターがあるなら、指定されたポインター変数にそれを割り当てます。 |
パブリック演算子
| 名前 | 説明 |
|---|---|
WeakRef::operator& |
現在の ComPtrRef オブジェクトを表す WeakRef オブジェクトを返します。 |
解説
WeakRef オブジェクトを使用すると、"強い参照" が維持されます。これはオブジェクトと関連付けられ、有効な場合と無効な場合があります。 強い参照を取得するには、As() メソッドまたは AsIID() メソッドを呼び出します。 強い参照が有効な場合、関連付けられているオブジェクトにアクセスできます。 強い参照が無効な場合 (nullptr)、関連付けられているオブジェクトにアクセスできません。
通常、WeakRef オブジェクトは、外部スレッドや外部アプリケーションによって存在が制御されるオブジェクトを表すために使用されます。 たとえば、ファイル オブジェクトへの参照から WeakRef オブジェクトを構築します。 ファイルが開いている間、強い参照は有効です。 しかし、ファイルが閉じられた場合、強い参照は無効になります。
Windows SDK では As、AsIID、CopyTo の各メソッドの動作が変更されています。 次のコードのように、以前は、これらのうちのいずれかのメソッドを呼び出した後、強い参照が正常に取得されたかどうかを判別するために WeakRef の nullptr を調べることができました。
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!");
}
継承階層
要件
ヘッダー: 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 番目のコンストラクターにより、WeakRef インターフェイスへのポインターから IWeakReference オブジェクトが初期化されます。 3 番目のコンストラクターにより、WeakRef オブジェクトへの参照から ComPtr<IWeakReference> オブジェクトが初期化されます。 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 に設定されません。このため、WeakRef の nullptr を確認するエラー チェック コードは避けてください。 代わりに、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 に設定されません。このため、WeakRef の nullptr を確認するエラー チェック コードは避けてください。 代わりに、ptr の nullptr を確認してください。
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 に設定されません。このため、WeakRef の nullptr を確認するエラー チェック コードは避けてください。 代わりに、ptr の nullptr を確認してください。
WeakRef::operator&
現在の ComPtrRef オブジェクトを表す WeakRef オブジェクトを返します。
Details::ComPtrRef<WeakRef> operator&() throw()
戻り値
現在の ComPtrRef オブジェクトを表す WeakRef オブジェクト。
解説
WeakRef::operator& は、コードでの使用が想定されていない内部ヘルパー演算子です。