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) を

Namespace: winrt

ヘッダー: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (既定で含まれます)

メンバー型のエイリアス

エイリアス名 種類
com_ptr::type typename T テンプレート パラメーターの実装定義表現のシノニム。

コンス トラクター

コンストラクタ 形容
com_ptr::com_ptr コンストラクターの 必要に応じて、入力データのコピーまたは移動を使用して、com_ptr 構造体の新しいインスタンスを初期化します。

メンバー関数

機能 形容
com_ptr::as 関数 サポートされている場合は、要求されたインターフェイスを返します。 そうでない場合はスローします。
com_ptr::attach 関数の ターゲットへの参照を所有する生ポインターにアタッチします。追加の参照は追加されません。
com_ptr::capture 関数の 指定した関数またはメソッド (winrt::check_hresult 自動的に呼び出す) を呼び出し、関数またはメソッドから出力されたインターフェイス ポインターを としてキャプチャします。
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 のバージョン。失敗してもスローされず、成功した場合は true が返されるか、そうでない場合は false が返されます。

メンバー演算子

演算子 形容
com_ptr::operator bool スマート ポインターがインターフェイスまたはオブジェクトを参照しているかどうかを確認します。
com_ptr::operator* (間接演算子) com_ptrのターゲットへの参照を返し、ターゲット型への参照を受け取る関数に T渡すことができます。
com_ptr::operator= (代入演算子) com_ptr オブジェクトに値を割り当てます。
com_ptr::operator-> (矢印演算子) 参照先のインターフェイスまたはオブジェクトのメソッドにアクセスできるようにするには、基になる生ポインターを返します。

無料の関数

機能 形容
attach_abi 関数の ターゲットへの参照を所有する生ポインターに com_ptr オブジェクトをアタッチします。追加の参照は追加されません。
関数 detach_abi 参照カウントを減らさずに、com_ptr オブジェクトを生のインターフェイスからデタッチします。呼び出し元に返す場合があります。
スワップ関数 を する 2 つの com_ptr パラメーターの内容を入れ替えて、互いにターゲットをポイントします。

Free 演算子

機能 形容
演算子!= (等しくない演算子) 2 つのパラメーターが異なるターゲットを参照しているかどうかを示す値を返します。
演算子 < (演算子より小さい) 最初のパラメーターのターゲットが 2 番目のパラメーターのターゲットよりもメモリ内で前に発生するかどうかを示す値を返します。
演算子<= (以下の演算子) 1 つ目のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも前のメモリ内で発生するか、または 2 番目のパラメーターと同じ場所にあるかを示す値を返します。
operator== (等値演算子) 2 つのパラメーターが同じインターフェイスまたはオブジェクトを参照しているかどうかを示す値を返します。
演算子> (より大きい演算子) 1 番目のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも後でメモリ内で発生するかどうかを示す値を返します。
演算子>= (以上の演算子) 1 番目のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも後で発生するか、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 入力スマート ポインターによって指されるターゲット型。

パラメーター

com_ptr オブジェクトを初期化する別の com_ptr を other します。 パラメーターの 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 自動的に呼び出す) を呼び出し、関数またはメソッドから出力されたインターフェイス ポインターを としてキャプチャします。

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);

テンプレート パラメーター

free 関数や std::functionなどの関数オブジェクト型です。

typename O インターフェイスの種類。

typename M A メソッド型。

typename Args 0 個以上の引数の型です。

パラメーター

function F型の関数オブジェクトです。

p O型のオブジェクトへのポインター。

object O型の winrt::com_ptr です。

method M型のメソッド (Oによって実装されます)。

Args型の 0 個以上の引数を args します。

備考

  • capture(F function, Args&&...args) オーバーロードは、関数オブジェクトを呼び出します。
  • capture(O* p, M method, Args&& ...args) オーバーロードは、ポインターに対してメソッドを呼び出します。
  • capture(winrt::com_ptr<O> const& object, M method, Args&&...args) オーバーロードは、オブジェクトに対してメソッドを呼び出します。

すべてのオーバーロードは、指定した追加の引数を (呼び出し側に) 渡します。 また、すべてのオーバーロードは、このような呼び出しで必要となる 2 つの追加引数 (具体的には、winrt:: com_ptrのターゲットの ID) と void** (winrt::com_ptrのターゲットへのポインターのアドレス) を必要とする 2 つの追加引数を渡します。

例

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;

パラメーター

other com_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 関数

関数に渡す必要がある場合は、基になる生ポインターを返します。 返されたポインター 、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 関数

サポートされている場合は、要求されたインターフェイスを返します。 nullptr (auto-returning オーバーロード) または false (boolを返すオーバーロード) を返します (そうでない場合)。 この関数は、呼び出し元に戻す必要のないインターフェイスを照会する場合に便利です。

構文

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 のバージョン。失敗してもスローされず、成功した場合は true が返されるか、そうでない場合は false が返されます。

winrt::try_capture 関数テンプレートのも参照してください。

com_ptr::operator bool

スマート ポインターがインターフェイスまたはオブジェクトを参照しているかどうかを確認します。 スマート ポインターがインターフェイスまたはオブジェクトを参照していない場合は、論理的に null になります。それ以外の場合は、論理的に null ではありません。

構文

explicit operator bool() const noexcept;

戻り値

スマート ポインターがインターフェイスまたはオブジェクト (論理的に null ではない) を参照している場合は true、それ以外の場合は false (論理的に null)。

com_ptr::operator* (間接演算子)

com_ptrのターゲットへの参照を返し、ターゲット型への参照を受け取る関数に T渡すことができます。

構文

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 割り当てられている値が指す型。

パラメーター

com_ptr オブジェクトに割り当てる com_ptr 値を other します。 パラメーターの 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;

パラメーター

left right ターゲットのメモリ アドレスが他のパラメーターのメモリ アドレスと比較される com_ptr 値です。

戻り値

2 つのパラメーターが異なるターゲットを指している場合は true。それ以外の場合は false。

operator< (less-than 演算子)

最初のパラメーターのターゲットが 2 番目のパラメーターのターゲットよりもメモリ内で前に発生するかどうかを示す値を返します。

構文

template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

パラメーター

left right ターゲットのメモリ アドレスが他のパラメーターのメモリ アドレスと比較される com_ptr 値です。

戻り値

最初のパラメーターのターゲットのメモリ アドレスが 2 番目のパラメーターのメモリ アドレスより小さい場合は true。それ以外の場合は false。

operator<= (less-than-or-equal-to 演算子)

1 つ目のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも前のメモリ内で発生するか、または 2 番目のパラメーターと同じ場所にあるかを示す値を返します。

構文

template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

パラメーター

left right ターゲットのメモリ アドレスが他のパラメーターのメモリ アドレスと比較される com_ptr 値です。

戻り値

最初のパラメーターのターゲットのメモリ アドレスが 2 番目のパラメーターのメモリ アドレス以下の場合は true。それ以外の場合は 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;

パラメーター

left right ターゲットのメモリ アドレスが他のパラメーターのメモリ アドレスと比較される com_ptr 値です。

戻り値

2 つのパラメーターが同じターゲットを指している場合は true。それ以外の場合は false。

演算子> (より大きい演算子)

1 番目のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも後でメモリ内で発生するかどうかを示す値を返します。

構文

template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

パラメーター

left right ターゲットのメモリ アドレスが他のパラメーターのメモリ アドレスと比較される com_ptr 値です。

戻り値

最初のパラメーターのターゲットのメモリ アドレスが 2 番目のパラメーターのメモリ アドレスより大きい場合は true。それ以外の場合は false。

operator>= (より大きい演算子または等しい演算子)

1 番目のパラメーターのターゲットが、2 番目のパラメーターのターゲットよりも後で発生するか、2 番目のパラメーターと同じ場所に配置されるかを示す値を返します。

構文

template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

パラメーター

left right ターゲットのメモリ アドレスが他のパラメーターのメモリ アドレスと比較される com_ptr 値です。

戻り値

最初のパラメーターのターゲットのメモリ アドレスが 2 番目のパラメーターのメモリ アドレス以上の場合は true。それ以外の場合は false。

swap 関数

2 つの com_ptr パラメーターの内容を入れ替えて、互いにターゲットをポイントします。

構文

void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;

パラメーター

left right 他のパラメーターと相互にスワップするポインターを持つ com_ptr 値です。

関連項目

  • winrt 名前空間 を する
  • C++/WinRT で API を使用する