winrt::com_ptr 構造体テンプレート (C++/WinRT)
参照カウントされた COM スマート ポインター テンプレート。 com_ptr は、テンプレート パラメーターで指定されたインターフェイスまたはランタイム クラス実装型へのポインターを表します。 プライベート生ポインターを使用して、ターゲットの参照カウントを自動的に管理します。
構文
template <typename T>
struct com_ptr
テンプレート パラメーター
typename T インターフェイス(ランタイム クラス実装型)、 com_ptrによって表される へのポインター。 これは、スマート ポインターのターゲットの型です。
必要条件
サポートされている最小 SDK:Windows SDK バージョン 10.0.17134.0 (Windows 10 バージョン 1803)
名前空間: winrt
ヘッダー: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (既定で含まれます)
メンバー型のエイリアス
| エイリアス名 | Type |
|---|---|
| com_ptr::type | テンプレート パラメーターの実装定義表現の typename T シノニム。 |
コンストラクター
| コンストラクター | 説明 |
|---|---|
| com_ptr::com_ptr コンストラクター | 必要に応じて、入力データのコピーまたは移動を使用して、 com_ptr 構造体の新しいインスタンスを初期化します。 |
メンバー関数
| 機能 | 説明 |
|---|---|
| com_ptr::as 関数 | 要求されたインターフェイスがサポートされている場合は、それを返します。 そうでない場合は をスローします。 |
| com_ptr::attach 関数 | ターゲットへの参照を所有する生ポインターにアタッチします。追加の参照は追加されません。 |
| com_ptr::capture 関数 | 指定した関数またはメソッドを呼び出し (自動的に winrt::check_hresult を呼び出します)、関数またはメソッドから出力されるインターフェイス ポインターを void**としてキャプチャします。 |
| com_ptr::copy_from 関数 | 別のポインターからコピーします。 現在参照されている任意のインターフェイスまたはオブジェクトの参照カウントをデクリメントし、生ポインター パラメーターをコピーし、そのパラメーターが指すインターフェイスまたはオブジェクトの有効期間の管理を開始します。 |
| com_ptr::copy_to 関数 | com_ptr オブジェクトから別のポインターにコピーします。 現在参照されているインターフェイスまたはオブジェクトの参照カウントをインクリメントし、そのインターフェイスまたはオブジェクトのメモリ アドレスを パラメーターにコピーします。 |
| com_ptr::d etach 関数 | 参照カウントをデクリメントせずに、参照インターフェイスまたはオブジェクトからデタッチします。呼び出し元に返す可能性があります。 |
| com_ptr::get 関数 | 関数に渡す必要がある場合は、基になる生ポインターを返します。 |
| com_ptr::p ut 関数 | 基になる生ポインターのアドレスを返します。この関数は、ポインターへのポインターを介して out パラメーターとして参照を返すメソッド (COM メソッドなど) を呼び出すのに役立ちます。 |
| com_ptr::p ut_void 関数 | 基になる生ポインターのアドレスを void へのポインターへのポインターとして返します。この関数は、 void へのポインターを介して out パラメーターとして参照を返すメソッド (COM メソッドなど) を呼び出すのに役立ちます。 |
| com_ptr::try_as 関数 | 要求されたインターフェイスがサポートされている場合は、それを返します。 nullptrでない場合は、、または falseを返します。 |
| com_ptr::try_capture 関数 | com_ptr::capture のバージョン。失敗してもスローされませんが、成功した場合、またはfalse失敗した場合は を返しますtrue。 |
メンバー演算子
| 演算子 | 説明 |
|---|---|
| com_ptr::operator bool | スマート ポインターがインターフェイスまたはオブジェクトを参照しているかどうかを確認します。 |
| com_ptr::operator* (間接演算子) | ターゲットの型 T への参照を予期する関数に渡すことができるように、com_ptrのターゲットへの参照を返します。 |
| com_ptr::operator= (代入演算子) | com_ptr オブジェクトに値を割り当てます。 |
| com_ptr::operator-> (矢印演算子) | 参照先のインターフェイスまたはオブジェクトのメソッドにアクセスできるようにするには、基になる生ポインターを返します。 |
無料の関数
| 機能 | 説明 |
|---|---|
| attach_abi 関数 | ターゲットへの参照を所有する生ポインターに com_ptr オブジェクトをアタッチします。追加の参照は追加されません。 |
| detach_abi 関数 | 参照カウントをデクリメントせずに、 com_ptr オブジェクトを生のインターフェイスからデタッチします。呼び出し元に返す場合があります。 |
| swap 関数 | 2 つの com_ptr パラメーターの内容を入れ替えて、相互のターゲットを指します。 |
Free 演算子
| 機能 | 説明 |
|---|---|
| operator!= (等しくない演算子) | 2 つのパラメーターが異なるターゲットを参照しているかどうかを示す値を返します。 |
| 演算子< (より小さい演算子) | 最初のパラメーターのターゲットが 2 番目のパラメーターのターゲットよりもメモリ内で発生するかどうかを示す値を返します。 |
| operator<= (より小さい演算子または等しい演算子) | 1 つ目のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも前のメモリ内で発生するか、同じ場所にあるかを示す値を返します。 |
| operator== (等値演算子) | 2 つのパラメーターが同じインターフェイスまたはオブジェクトを参照しているかどうかを示す値を返します。 |
| 演算子> (より大きい演算子) | 最初のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも後でメモリ内で発生するかどうかを示す値を返します。 |
| operator>= (より大きい演算子または等しい演算子) | 最初のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも後で発生するか、同じ場所にあるかを示す値を返します。 |
com_ptr::com_ptr コンストラクター
必要に応じて、入力データのコピーまたは移動を使用して、 com_ptr 構造体の新しいインスタンスを初期化します。
コンストラクターは void* T* を受け取り、所有権を前提としています。 winrt::take_ownership_from_abi_t は、 このポインターを解放する責任を明示的にcom_ptrに転送するマーカー型です。 refcount は正確に 1 である必要はありません。それは責任が移転されていると言っているだけです。
構文
com_ptr(winrt::com_ptr const& other) noexcept;
com_ptr(std::nullptr_t = nullptr) noexcept;
com_ptr(void* ptr, winrt::take_ownership_from_abi_t) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U> const& other) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U>&& other) noexcept;
テンプレート パラメーター
typename U 入力スマート ポインターによって指されるターゲット型。
パラメーター
othercom_ptr オブジェクトを初期化する別のcom_ptr。 パラメーターの T は、 com_ptr オブジェクトの T に変換できる必要があります。
com_ptr::as 関数
要求されたインターフェイスがサポートされている場合は、それを返します。 そうでない場合は をスローします。 この関数は、呼び出し元に渡す必要のないインターフェイスを照会する場合に便利です。
コード例については、そのトピックの「 投影型とインターフェイスのインスタンス化と返し」セクション、およびその他のセクションを参照してください。
構文
template <typename To> auto as() const;
template <typename To> void as(To& to) const;
テンプレート パラメーター
typename To 要求されたインターフェイスの型。
パラメーター
to 要求されたインターフェイスを受け取る値への参照。
戻り値
要求されたインターフェイスを参照する com_ptr 、または要求されたインターフェイスの厳密に型指定されたスマート ポインター (C++/WinRT またはサード パーティによって宣言されます)。
com_ptr::attach 関数
ターゲットへの参照を所有する生ポインターにアタッチします。追加の参照は追加されません。 必要に応じて、この関数を使用して参照を結合できます。
構文
void attach(T* value) noexcept;
パラメーター
value ターゲットへの参照を所有する生ポインター。
com_ptr::capture 関数
指定した関数またはメソッドを呼び出し (自動的に winrt::check_hresult を呼び出します)、関数またはメソッドから出力されるインターフェイス ポインターを void**としてキャプチャします。
winrt::capture 関数テンプレートも参照してください。
構文
template <typename F, typename...Args>
void capture(F function, Args&&...args);
template <typename O, typename M, typename...Args>
void capture(O* p, M method, Args&& ...args);
template <typename O, typename M, typename...Args>
void capture(winrt::com_ptr<O> const& object, M method, Args&&...args);
テンプレート パラメーター
typename F free 関数や std::function などの関数オブジェクト型。
typename O インターフェイスの種類。
typename M メソッドの型。
typename Args 0 個以上の引数型。
パラメーター
function 型 Fの関数オブジェクト。
p 型 Oの オブジェクトへのポインター。
objectwinrt::com_ptr 型O。
method型Mの メソッド (によってO実装されます)。
args 型 Argsの 0 個以上の引数。
解説
- オーバーロードは
capture(F function, Args&&...args)関数オブジェクトを呼び出します。 - オーバーロードは
capture(O* p, M method, Args&& ...args)、ポインターで メソッドを呼び出します。 - オーバーロードは
capture(winrt::com_ptr<O> const& object, M method, Args&&...args)、 オブジェクトに対して メソッドを呼び出します。
すべてのオーバーロードは、指定した追加の引数を (呼び出し元に) 渡します。 また、すべてのオーバーロードは、このような呼び出しで必要な 2 つの追加引数 (具体的には、 REFIID ( winrt::com_ptrのターゲットの ID)、 void** ( winrt::com_ptr のターゲットへのポインターのアドレス) も渡します。
例
winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);
com_ptr::copy_from 関数
別のポインターからコピーします。 現在参照されている任意のインターフェイスまたはオブジェクトの参照カウントをデクリメントし、生ポインター パラメーターをコピーし、そのパラメーターが指すインターフェイスまたはオブジェクトの有効期間の管理を開始します。
構文
void copy_from(T* other) noexcept;
パラメーター
othercom_ptr オブジェクトによって有効期間を管理する必要があるターゲットへの生ポインター。
com_ptr::copy_to 関数
com_ptr オブジェクトから別のポインターにコピーします。 現在参照されているインターフェイスまたはオブジェクトの参照カウントをインクリメントし、そのインターフェイスまたはオブジェクトのメモリ アドレスを パラメーターにコピーします。 この関数を使用すると、 QueryInterface を呼び出さずに、同じインターフェイスへの参照を渡すことができます。
構文
void copy_to(T** other) const noexcept;
パラメーター
other 生ポインターのアドレス。com_ptr オブジェクトの ターゲットへのポインターのコピー先。
com_ptr::d etach 関数
参照カウントをデクリメントせずに、参照インターフェイスまたはオブジェクトからデタッチします。呼び出し元に返す可能性があります。
構文
T* detach() noexcept;
戻り値
com_ptr オブジェクトによって参照されるインターフェイスまたはオブジェクトへのポインター。
com_ptr::get 関数
関数に渡す必要がある場合は、基になる生ポインターを返します。 返されたポインターで AddRef、 Release、または QueryInterface を呼び出す場合があります。
構文
T* get() const noexcept;
戻り値
com_ptr オブジェクトによって参照されるインターフェイスまたはオブジェクトへのポインター。
com_ptr::p ut 関数
基になる生ポインターのアドレスを返します。この関数は、ポインターへのポインターを介して out パラメーターとして参照を返すメソッド (COM メソッドなど) を呼び出すのに役立ちます。 com_ptr オブジェクトに既にターゲットがある場合は、この関数を呼び出す前に com_ptr オブジェクトに割り当てますnullptr。それ以外の場合、関数はアサートします。
構文
T** put() noexcept;
戻り値
基になる生ポインターのアドレス。
com_ptr::p ut_void 関数
基になる生ポインターのアドレスを void へのポインターへのポインターとして返します。この関数は、 void へのポインターを介して out パラメーターとして参照を返すメソッド (COM メソッドなど) を呼び出すのに役立ちます。 com_ptr オブジェクトに既にターゲットがある場合は、この関数を呼び出す前に com_ptr オブジェクトに割り当てますnullptr。それ以外の場合、関数はアサートします。
構文
void** put_void() noexcept;
戻り値
void へのポインターへのポインターとしての、基になる生ポインターのアドレス。
com_ptr::try_as 関数
要求されたインターフェイスがサポートされている場合は、それを返します。 nullptrauto(-returning オーバーロード) を返しますfalse。そうでない場合は (bool-returning オーバーロード) を返します。 この関数は、呼び出し元に渡す必要のないインターフェイスを照会する場合に便利です。
構文
template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;
テンプレート パラメーター
typename To 要求されたインターフェイスの型。
パラメーター
to 要求されたインターフェイスを受け取る値への参照。
戻り値
要求されたインターフェイスを参照する com_ptr 、または要求されたインターフェイスの厳密に型指定されたスマート ポインター (C++/WinRT またはサード パーティによって宣言されます)、要求されたインターフェイスがサポートされている場合は 、それ以外の場合 nullptr は ( auto-returning オーバーロード)、または false ( bool-returning オーバーロード)。
com_ptr::try_capture 関数
com_ptr::capture のバージョン。失敗してもスローされませんが、成功した場合、またはfalse失敗した場合は を返しますtrue。
winrt::try_capture 関数テンプレートも参照してください。
com_ptr::operator bool
スマート ポインターがインターフェイスまたはオブジェクトを参照しているかどうかを確認します。 スマート ポインターがインターフェイスまたはオブジェクトを参照していない場合は、論理的に null になります。それ以外の場合は、論理的には null ではありません。
構文
explicit operator bool() const noexcept;
戻り値
true スマート ポインターがインターフェイスまたはオブジェクトを参照している場合 (論理的には null ではない)、それ以外の場合 false は (論理的に null)。
com_ptr::operator* (間接演算子)
ターゲットの型 T への参照を予期する関数に渡すことができるように、com_ptrのターゲットへの参照を返します。
構文
T& operator*() const noexcept;
戻り値
com_ptrのターゲットへの参照。
com_ptr::operator= (代入演算子)
com_ptr オブジェクトに値を割り当てます。
構文
winrt::com_ptr& operator=(winrt::com_ptr const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U> const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U>&& other) noexcept;
テンプレート パラメーター
typename U 割り当てられている値によって指される型。
パラメーター
othercom_ptr オブジェクトに割り当てるcom_ptr値。 パラメーターの T は、 com_ptr オブジェクトの T に変換できる必要があります。
戻り値
com_ptr オブジェクトへの参照。
com_ptr::operator-> (矢印演算子)
参照先のインターフェイスまたはオブジェクトのメソッドにアクセスできるようにするには、基になる生ポインターを返します。 返されたポインターで AddRef や Release を呼び出すわけではありませんが、 QueryInterface を呼び出してもかまいません。
構文
auto operator->() const noexcept;
戻り値
com_ptr オブジェクトによって参照されるインターフェイスまたはオブジェクトへのポインター。
attach_abi 関数
ターゲットへの参照を所有する生ポインターに com_ptr オブジェクトをアタッチします。追加の参照は追加されません。 必要に応じて、この関数を使用して参照を結合できます。
構文
void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;
パラメーター
object 操作 するcom_ptr オブジェクト。
value ターゲットへの参照を所有する生ポインター。
detach_abi 関数
参照カウントをデクリメントせずに、 com_ptr オブジェクトを生のインターフェイスからデタッチします。呼び出し元に返す場合があります。
構文
auto detach_abi(winrt::com_ptr<T>& object) noexcept;
パラメーター
object 操作 するcom_ptr オブジェクト。
戻り値
com_ptr オブジェクトによって参照される生インターフェイスへのポインター。
operator!= (等しくない演算子)
2 つのパラメーターが異なるターゲットを参照しているかどうかを示す値を返します。
構文
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator!=(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
パラメーター
leftright ターゲット のメモリ アドレスを他のパラメーターのメモリ アドレスと比較するcom_ptr値。
戻り値
true 2 つのパラメーターが異なるターゲットを指す場合は 。それ以外の場合 falseは 。
operator< (less-than 演算子)
最初のパラメーターのターゲットが 2 番目のパラメーターよりもメモリ内で発生するかどうかを示す値を返します。
構文
template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
パラメーター
leftright ターゲット のメモリ アドレスを他のパラメーターのメモリ アドレスと比較するcom_ptr値。
戻り値
true 最初のパラメーターのターゲットのメモリ アドレスが 2 番目のパラメーターのメモリ アドレスより小さい場合は 。それ以外の場合 falseは 。
operator<= (以下の演算子)
1 つ目のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも前のメモリ内で発生するか、または 2 番目のパラメーターのターゲットと同じ場所にあるかを示す値を返します。
構文
template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
パラメーター
leftright ターゲット のメモリ アドレスを他のパラメーターのメモリ アドレスと比較するcom_ptr値。
戻り値
true 最初のパラメーターのターゲットのメモリ アドレスが 2 番目のパラメーターのメモリ アドレス以下の場合は 。それ以外の場合 falseは 。
operator== (等値演算子)
2 つのパラメーターが同じインターフェイスまたはオブジェクトを参照しているかどうかを示す値を返します。
構文
template <typename T> bool operator==(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator==(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
パラメーター
leftright ターゲット のメモリ アドレスを他のパラメーターのメモリ アドレスと比較するcom_ptr値。
戻り値
true 2 つのパラメーターが同じターゲットを指す場合は 。それ以外の場合 falseは 。
operator> (greater-than 演算子)
最初のパラメーターのターゲットが 2 番目のパラメーターのターゲットよりも後でメモリ内で発生するかどうかを示す値を返します。
構文
template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
パラメーター
leftright ターゲット のメモリ アドレスを他のパラメーターのメモリ アドレスと比較するcom_ptr値。
戻り値
true 最初のパラメーターのターゲットのメモリ アドレスが 2 番目のパラメーターのメモリ アドレスより大きい場合は 。それ以外の場合 falseは 。
operator>= (より大きい演算子または等しい演算子)
最初のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも後でメモリ内で発生するか、または 2 番目のパラメーターと同じ場所にあるかを示す値を返します。
構文
template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
パラメーター
leftright ターゲット のメモリ アドレスを他のパラメーターのメモリ アドレスと比較するcom_ptr値。
戻り値
true 最初のパラメーターのターゲットのメモリ アドレスが 2 番目のパラメーターのメモリ アドレス以上の場合は 。それ以外の場合 falseは 。
swap 関数
2 つの com_ptr パラメーターの内容を入れ替えて、相互のターゲットを指します。
構文
void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;
パラメーター
leftright他のパラメーターのポインターと相互にスワップするポインターを持つcom_ptr値。
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示