winrt::com_ptr struct template (C++/WinRT)

Artikel
08/17/2024

Templat penunjuk pintar COM yang dihitung referensi. com_ptr mewakili penunjuk ke jenis implementasi kelas antarmuka atau runtime yang ditentukan oleh parameter templat. Ini secara otomatis mengelola jumlah referensi untuk targetnya melalui pointer mentah privat.

Sintaksis

template <typename T>
struct com_ptr

Parameter templat

typename T Antarmuka, atau jenis implementasi kelas runtime, pointer yang diwakili oleh com_ptr. Ini adalah jenis target penunjuk pintar.

Persyaratan

SDK minimum yang didukung: Windows SDK versi 10.0.17134.0 (Windows 10, versi 1803)

Namespace: winrt

Header : %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (disertakan secara default)

Alias jenis anggota

Nama alias	Jenis
com_ptr::type	Sinonim untuk representasi yang ditentukan implementasi dari parameter templat `typename T`.

Konstruktor

Pembangun	Deskripsi
com_ptr::com_ptr konstruktor	Menginisialisasi instans baru struct com_ptr, secara opsional dengan salinan atau pemindahan data input.

Fungsi anggota

Fungsi	Deskripsi
com_ptr::as fungsi	Mengembalikan antarmuka yang diminta, jika didukung. Melempar jika tidak.
com_ptr::melampirkan fungsi	Melampirkan ke pointer mentah yang memiliki referensi ke targetnya; referensi tambahan tidak ditambahkan.
com_ptr::menangkap fungsi	Memanggil fungsi atau metode tertentu (secara otomatis memanggil winrt::check_hresult di atasnya), dan menangkap pointer antarmuka yang keluaran dari fungsi atau metode sebagai `void**`.
com_ptr::copy_from fungsi	Menyalin dari pointer lain. Mengurangi jumlah referensi pada antarmuka atau objek yang saat ini direferensikan, menyalin parameter pointer mentah, dan mulai mengelola masa pakai antarmuka atau objek yang ditunjukkan olehnya.
fungsi com_ptr::copy_to	Menyalin ke pointer lain dari objek com_ptr. Menaikkan jumlah referensi pada antarmuka atau objek yang saat ini direferensikan, dan menyalin antarmuka atau alamat memori objek tersebut ke dalam parameter .
fungsi com_ptr::d etach	Melepaskan dari antarmuka atau objek yang direferensikan tanpa mengurangi jumlah referensi, mungkin untuk mengembalikannya ke pemanggil.
com_ptr::get fungsi	Mengembalikan penunjuk mentah yang mendasar jika Anda perlu meneruskannya ke fungsi.
fungsi com_ptr::p ut	Mengembalikan alamat penunjuk mentah yang mendasar; fungsi ini membantu Anda memanggil metode (seperti metode COM) yang mengembalikan referensi sebagai parameter keluar melalui penunjuk ke penunjuk.
fungsi com_ptr::p ut_void	Mengembalikan alamat penunjuk mentah yang mendasar sebagai penunjuk ke penunjuk untuk kekosongan ; fungsi ini membantu Anda memanggil metode (seperti metode COM) yang mengembalikan referensi sebagai parameter keluar melalui penunjuk ke penunjuk untuk kekosongan .
fungsi com_ptr::try_as	Mengembalikan antarmuka yang diminta, jika didukung. Mengembalikan `nullptr`, atau `false`, jika tidak.
fungsi com_ptr::try_capture	Versi com_ptr::capture yang tidak gagal tetapi mengembalikan `true` jika berhasil atau `false` jika tidak.

Operator anggota

Operator	Deskripsi
com_ptr:: bool operator	Memeriksa apakah penunjuk pintar mereferensikan antarmuka atau objek atau tidak.
com_ptr::operator* (operator tidak langsung)	Mengembalikan referensi ke target com_ptrsehingga Anda dapat meneruskannya ke fungsi yang mengharapkan referensi ke jenis target T.
com_ptr::operator= (operator penugasan)	Menetapkan nilai ke objek com_ptr.
com_ptr::operator-> (operator panah)	Untuk membeli akses ke antarmuka yang dirujuk atau metode objek, mengembalikan pointer mentah yang mendasar.

Fungsi gratis

Fungsi	Deskripsi
fungsi attach_abi	Melampirkan objek com_ptr ke pointer mentah yang memiliki referensi ke targetnya; referensi tambahan tidak ditambahkan.
fungsi detach_abi	Melepaskan objek com_ptr dari antarmuka mentahnya tanpa mengurangi jumlah referensi, mungkin untuk mengembalikannya ke pemanggil.
fungsi pertukaran	Tukar isi dua parameter com_ptr sehingga menunjuk target satu sama lain.

Operator gratis

Fungsi	Deskripsi
operator!= (operator ketidaksamaan)	Mengembalikan nilai yang menunjukkan apakah kedua parameter merujuk ke target yang berbeda.
< operator (operator kurang dari)	Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi lebih awal dalam memori daripada parameter kedua.
<operator = (operator kurang dari atau sama dengan)	Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi lebih awal dalam memori daripada, atau di lokasi yang sama dengan, parameter kedua.
operator== (operator kesetaraan)	Mengembalikan nilai yang menunjukkan apakah kedua parameter merujuk ke antarmuka dan/atau objek yang sama.
operator (lebih besar dari operator)	Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi nanti dalam memori daripada parameter kedua.
operator>= (operator yang lebih besar dari atau sama dengan operator)	Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi nanti dalam memori daripada, atau di lokasi yang sama dengan, parameter kedua.

konstruktor com_ptr::com_ptr

Menginisialisasi instans baru struct com_ptr, secara opsional dengan salinan atau pemindahan data input.

Konstruktor void* mengambil T*, dan mengasumsikan kepemilikan. winrt::take_ownership_from_abi_t adalah jenis penanda yang membuat eksplisit tanggung jawab untuk merilis pointer ini sekarang sedang ditransfer ke com_ptr. Refcount tidak harus tepat 1; Itu hanya mengatakan bahwa tanggung jawab sedang ditransfer.

Sintaksis

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;

Parameter templat

typename U Jenis target yang ditunjukkan oleh penunjuk pintar input.

Parameter

other com_ptr lain yang menginisialisasi objek com_ptr. T parameter harus dapat dikonversi keobjek com_ptr .

fungsi com_ptr::as

Mengembalikan antarmuka yang diminta, jika didukung. Melempar jika tidak. Fungsi ini berguna jika Anda ingin mengkueri antarmuka yang tidak perlu Anda teruskan kembali ke pemanggil Anda.

Untuk contoh kode, lihat bagian Membuat instans dan mengembalikan jenis dan antarmuka yang diproyeksikan, dan bagian lain dalam topik tersebut.

Sintaksis

template <typename To> auto as() const;
template <typename To> void as(To& to) const;

Parameter templat

typename To Jenis antarmuka yang diminta.

Parameter

to Referensi ke nilai untuk menerima antarmuka yang diminta.

Mengembalikan nilai

com_ptr mereferensikan antarmuka yang diminta, atau penunjuk cerdas yang diketik dengan kuat untuk antarmuka yang diminta (baik dideklarasikan oleh C++/WinRT atau oleh pihak ketiga).

com_ptr::lampirkan fungsi

Melampirkan ke pointer mentah yang memiliki referensi ke targetnya; referensi tambahan tidak ditambahkan. Jika diperlukan, Anda dapat menggunakan fungsi ini untuk menyaring referensi.

Sintaksis

void attach(T* value) noexcept;

Parameter

value Pointer mentah yang memiliki referensi ke targetnya.

fungsi com_ptr::capture

Memanggil fungsi atau metode tertentu (secara otomatis memanggil winrt::check_hresult di atasnya), dan menangkap pointer antarmuka yang keluaran dari fungsi atau metode sebagai void**.

Lihat juga templat fungsi winrt::capture.

Sintaksis

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

Parameter templat

typename F Jenis objek fungsi, seperti fungsi bebas, atau std::function.

typename O Jenis antarmuka.

typename M Jenis metode.

typename Args Jenis argumen nol atau lebih.

Parameter

function Objek fungsi jenis F.

p Penunjuk ke objek jenis O.

object A winrt::com_ptr jenis O.

method Metode A (diimplementasikan oleh O) jenis M.

args Nol atau lebih argumen jenis Args.

Komentar

Kelebihan capture(F function, Args&&...args) memanggil objek fungsi.
Kelebihan capture(O* p, M method, Args&& ...args) memanggil metode pada pointer.
Kelebihan capture(winrt::com_ptr<O> const& object, M method, Args&&...args) memanggil metode pada objek.

Semua kelebihan beban melewati (ke pemanggilan) argumen tambahan apa pun yang Anda berikan. Semua kelebihan beban juga meneruskan dua argumen tambahan yang diperlukan pemanggilan tersebut—khususnya, REFIID (ID target winrt ::com_ptr), dan void** (Alamat pointer ke target winrt ::com_ptr).

Contoh

winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);

fungsi com_ptr::copy_from

Menyalin dari pointer lain. Mengurangi jumlah referensi pada antarmuka atau objek yang saat ini direferensikan, menyalin parameter pointer mentah, dan mulai mengelola masa pakai antarmuka atau objek yang ditunjukkan olehnya.

Sintaksis

void copy_from(T* other) noexcept;

Parameter

other Pointer mentah ke target yang masa pakainya harus dikelola oleh objek com_ptr.

fungsi com_ptr::copy_to

Menyalin ke pointer lain dari objek com_ptr. Menaikkan jumlah referensi pada antarmuka atau objek yang saat ini direferensikan, dan menyalin antarmuka atau alamat memori objek tersebut ke dalam parameter . Fungsi ini memungkinkan Anda membagikan referensi ke antarmuka yang sama tanpa memanggil QueryInterface.

Sintaksis

void copy_to(T** other) const noexcept;

Parameter

other Alamat penunjuk mentah; untuk menyalin penunjuk ke target objek com_ptr.

fungsi com_ptr::d etach

Melepaskan dari antarmuka atau objek yang direferensikan tanpa mengurangi jumlah referensi, mungkin untuk mengembalikannya ke pemanggil.

Sintaksis

T* detach() noexcept;

Mengembalikan nilai

Penunjuk ke antarmuka atau objek yang dirujuk oleh objek com_ptr.

com_ptr::get function

Mengembalikan penunjuk mentah yang mendasar jika Anda perlu meneruskannya ke fungsi. Anda dapat memanggil AddRef, Release, atau QueryInterface pada pointer yang dikembalikan.

Sintaksis

T* get() const noexcept;

Mengembalikan nilai

Penunjuk ke antarmuka atau objek yang dirujuk oleh objek com_ptr.

fungsi com_ptr::p ut

Mengembalikan alamat penunjuk mentah yang mendasar; fungsi ini membantu Anda memanggil metode (seperti metode COM) yang mengembalikan referensi sebagai parameter keluar melalui penunjuk ke penunjuk. Jika objek com_ptr sudah memiliki target, maka tetapkan nullptr ke objek com_ptr sebelum memanggil fungsi ini, jika tidak, fungsi akan menegaskan.

Sintaksis

T** put() noexcept;

Mengembalikan nilai

Alamat penunjuk mentah yang mendasar.

fungsi com_ptr::p ut_void

Mengembalikan alamat penunjuk mentah yang mendasar sebagai penunjuk ke penunjuk untuk kekosongan ; fungsi ini membantu Anda memanggil metode (seperti metode COM) yang mengembalikan referensi sebagai parameter keluar melalui penunjuk ke penunjuk untuk kekosongan . Jika objek com_ptr sudah memiliki target, maka tetapkan nullptr ke objek com_ptr sebelum memanggil fungsi ini, jika tidak, fungsi akan menegaskan.

Sintaksis

void** put_void() noexcept;

Mengembalikan nilai

Alamat penunjuk mentah yang mendasar sebagai penunjuk ke penunjuk untuk batal.

fungsi com_ptr::try_as

Mengembalikan antarmuka yang diminta, jika didukung. Mengembalikan nullptr (auto-returning overload), atau false (bool-returning overload), jika tidak. Fungsi ini berguna jika Anda ingin mengkueri antarmuka yang tidak perlu Anda teruskan kembali ke pemanggil Anda.

Sintaksis

template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;

Parameter templat

typename To Jenis antarmuka yang diminta.

Parameter

to Referensi ke nilai untuk menerima antarmuka yang diminta.

Mengembalikan nilai

com_ptr mereferensikan antarmuka yang diminta, atau penunjuk cerdas yang diketik dengan kuat untuk antarmuka yang diminta (baik dinyatakan oleh C++/WinRT atau oleh pihak ketiga), jika antarmuka yang diminta didukung, jika tidak, nullptr (auto-mengembalikan kelebihan beban), atau false (bool-mengembalikan kelebihan beban).

fungsi com_ptr::try_capture

Versi com_ptr::capture yang tidak gagal tetapi mengembalikan true jika berhasil atau false jika tidak.

Lihat juga templat fungsi winrt::try_capture.

com_ptr::operator bool

Memeriksa apakah penunjuk pintar mereferensikan antarmuka atau objek atau tidak. Jika penunjuk pintar tidak mereferensikan antarmuka atau objek, maka secara logis null; jika tidak, secara logis tidak null.

Sintaksis

explicit operator bool() const noexcept;

Mengembalikan nilai

true jika penunjuk pintar mereferensikan antarmuka atau objek (secara logis tidak null), jika tidak, false (secara logis null).

com_ptr::operator* (operator tidak langsung)

Mengembalikan referensi ke target com_ptrsehingga Anda dapat meneruskannya ke fungsi yang mengharapkan referensi ke jenis target T.

Sintaksis

T& operator*() const noexcept;

Mengembalikan nilai

Referensi ke target com_ptr.

com_ptr::operator= (operator penugasan)

Menetapkan nilai ke objek com_ptr.

Sintaksis

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;

Parameter templat

typename U Jenis yang ditunjukkan oleh nilai yang ditetapkan.

Parameter

other Nilai com_ptr untuk ditetapkan ke objek com_ptr. T parameter harus dapat dikonversi keobjek com_ptr .

Mengembalikan nilai

Referensi ke objek com_ptr.

com_ptr::operator-> (operator panah)

Untuk membeli akses ke antarmuka yang dirujuk atau metode objek, mengembalikan pointer mentah yang mendasar. Anda tidak boleh memanggil AddRef atau Release pada pointer yang dikembalikan, tetapi Anda dapat memanggil QueryInterface.

Sintaksis

auto operator->() const noexcept;

Mengembalikan nilai

Penunjuk ke antarmuka atau objek yang dirujuk oleh objek com_ptr.

fungsi attach_abi

Melampirkan objek com_ptr ke pointer mentah yang memiliki referensi ke targetnya; referensi tambahan tidak ditambahkan. Jika diperlukan, Anda dapat menggunakan fungsi ini untuk menyaring referensi.

Sintaksis

void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;

Parameter

object objek com_ptr untuk dioperasikan.

value Pointer mentah yang memiliki referensi ke targetnya.

fungsi detach_abi

Melepaskan objek com_ptr dari antarmuka mentahnya tanpa mengurangi jumlah referensi, mungkin untuk mengembalikannya ke pemanggil.

Sintaksis

auto detach_abi(winrt::com_ptr<T>& object) noexcept;

Parameter

object objek com_ptr untuk dioperasikan.

Mengembalikan nilai

Penunjuk ke antarmuka mentah yang dirujuk oleh objek com_ptr.

operator!= (operator ketidaksamaan)

Mengembalikan nilai yang menunjukkan apakah kedua parameter merujuk ke target yang berbeda.

Sintaksis

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;

Parameter

left right Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.

Mengembalikan nilai

true jika dua parameter menunjuk ke target yang berbeda, jika tidak, false.

operator< (operator kurang dari)

Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi lebih awal dalam memori daripada parameter kedua.

Sintaksis

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

Parameter

left right Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.

Mengembalikan nilai

true jika alamat memori target parameter pertama kurang dari parameter kedua, jika tidak, false.

operator<= (operator kurang dari atau sama dengan)

Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi lebih awal dalam memori daripada, atau di lokasi yang sama dengan, parameter kedua.

Sintaksis

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

Parameter

left right Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.

Mengembalikan nilai

true jika alamat memori target parameter pertama kurang dari atau sama dengan parameter kedua, jika tidak, false.

operator== (operator kesetaraan)

Mengembalikan nilai yang menunjukkan apakah kedua parameter merujuk ke antarmuka dan/atau objek yang sama.

Sintaksis

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;

Parameter

left right Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.

Mengembalikan nilai

true jika dua parameter menunjuk ke target yang sama, jika tidak, false.

operator> (operator yang lebih besar dari)

Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi nanti dalam memori daripada parameter kedua.

Sintaksis

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

Parameter

left right Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.

Mengembalikan nilai

true jika alamat memori target parameter pertama lebih besar dari parameter kedua, jika tidak, false.

operator>= (operator yang lebih besar dari atau sama dengan)

Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi nanti dalam memori daripada, atau di lokasi yang sama dengan, parameter kedua.

Sintaksis

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

Parameter

left right Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.

Mengembalikan nilai

true jika alamat memori target parameter pertama lebih besar dari atau sama dengan parameter kedua, jika tidak, false.

fungsi pertukaran

Tukar isi dua parameter com_ptr sehingga menunjuk target satu sama lain.

Sintaksis

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

Parameter

left right Nilai com_ptr yang penunjuknya saling bertukar dengan parameter lainnya.

Lihat juga

namespace winrt
Menggunakan API dengan C++/WinRT

Bagikan melalui

winrt::com_ptr struct template (C++/WinRT)

Sintaksis

Parameter templat

Persyaratan

Alias jenis anggota

Konstruktor

Fungsi anggota

Operator anggota

Fungsi gratis

Operator gratis

konstruktor com_ptr::com_ptr

Sintaksis

Parameter templat

Parameter

fungsi com_ptr::as

Sintaksis

Parameter templat

Parameter

Mengembalikan nilai

com_ptr::lampirkan fungsi

Sintaksis

Parameter

fungsi com_ptr::capture

Sintaksis

Parameter templat

Parameter

Komentar

Contoh

fungsi com_ptr::copy_from

Sintaksis

Parameter

fungsi com_ptr::copy_to

Sintaksis

Parameter

fungsi com_ptr::d etach

Sintaksis

Mengembalikan nilai

com_ptr::get function

Sintaksis

Mengembalikan nilai

fungsi com_ptr::p ut

Sintaksis

Mengembalikan nilai

fungsi com_ptr::p ut_void

Sintaksis

Mengembalikan nilai

fungsi com_ptr::try_as

Sintaksis

Parameter templat

Parameter

Mengembalikan nilai

fungsi com_ptr::try_capture

com_ptr::operator bool

Sintaksis

Mengembalikan nilai

com_ptr::operator* (operator tidak langsung)

Sintaksis

Mengembalikan nilai

com_ptr::operator= (operator penugasan)

Sintaksis

Parameter templat

Parameter

Mengembalikan nilai

com_ptr::operator-> (operator panah)

Sintaksis

Mengembalikan nilai

fungsi attach_abi

Sintaksis

Parameter

fungsi detach_abi

Sintaksis

Parameter

Mengembalikan nilai

operator!= (operator ketidaksamaan)

Sintaksis

Parameter

Mengembalikan nilai

operator< (operator kurang dari)

Sintaksis