winrt::com_ptr struct template (C++/WinRT)
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.
template <typename T>
struct com_ptr
typename T
Antarmuka, atau jenis implementasi kelas runtime, pointer yang diwakili oleh com_ptr. Ini adalah jenis target penunjuk pintar.
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)
Nama alias | Jenis |
---|---|
com_ptr::type | Sinonim untuk representasi yang ditentukan implementasi dari parameter templat typename T . |
Pembangun | Deskripsi |
---|---|
com_ptr::com_ptr konstruktor | Menginisialisasi instans baru struct com_ptr, secara opsional dengan salinan atau pemindahan data input. |
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 |
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 |
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 |
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 |
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 |
Mengembalikan antarmuka yang diminta, jika didukung. Mengembalikan nullptr , atau false , jika tidak. |
fungsi |
Versi com_ptr::capture yang tidak gagal tetapi mengembalikan true jika berhasil atau false jika tidak. |
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 | Deskripsi |
---|---|
fungsi |
Melampirkan objek com_ptr ke pointer mentah yang memiliki referensi ke targetnya; referensi tambahan tidak ditambahkan. |
fungsi |
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. |
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. |
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. |
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.
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
Jenis target yang ditunjukkan oleh penunjuk pintar input.
other
com_ptr lain yang menginisialisasi objek com_ptr. T
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.
template <typename To> auto as() const;
template <typename To> void as(To& to) const;
typename To
Jenis antarmuka yang diminta.
to
Referensi ke nilai untuk menerima antarmuka yang diminta.
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).
Melampirkan ke pointer mentah yang memiliki referensi ke targetnya; referensi tambahan tidak ditambahkan. Jika diperlukan, Anda dapat menggunakan fungsi ini untuk menyaring referensi.
void attach(T* value) noexcept;
value
Pointer mentah yang memiliki referensi ke targetnya.
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.
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
Jenis objek fungsi, seperti fungsi bebas, atau std::function.
typename O
Jenis antarmuka.
typename M
Jenis metode.
typename Args
Jenis argumen nol atau lebih.
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
.
- 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
winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);
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.
void copy_from(T* other) noexcept;
other
Pointer mentah ke target yang masa pakainya harus dikelola oleh objek com_ptr.
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.
void copy_to(T** other) const noexcept;
other
Alamat penunjuk mentah; untuk menyalin penunjuk ke target objek com_ptr.
Melepaskan dari antarmuka atau objek yang direferensikan tanpa mengurangi jumlah referensi, mungkin untuk mengembalikannya ke pemanggil.
T* detach() noexcept;
Penunjuk ke antarmuka atau objek yang dirujuk oleh objek com_ptr.
Mengembalikan penunjuk mentah yang mendasar jika Anda perlu meneruskannya ke fungsi. Anda dapat memanggil AddRef, Release, atau QueryInterface pada pointer yang dikembalikan.
T* get() const noexcept;
Penunjuk ke antarmuka atau objek yang dirujuk oleh objek com_ptr.
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.
T** put() noexcept;
Alamat penunjuk mentah yang mendasar.
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.
void** put_void() noexcept;
Alamat penunjuk mentah yang mendasar sebagai penunjuk ke penunjuk untuk batal.
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.
template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;
typename To
Jenis antarmuka yang diminta.
to
Referensi ke nilai untuk menerima antarmuka yang diminta.
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).
Versi com_ptr::capture yang tidak gagal tetapi mengembalikan true
jika berhasil atau false
jika tidak.
Lihat juga templat fungsi winrt::try_capture.
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.
explicit operator bool() const noexcept;
true
jika penunjuk pintar mereferensikan antarmuka atau objek (secara logis tidak null), jika tidak, false
(secara logis null).
Mengembalikan referensi ke target com_ptrsehingga Anda dapat meneruskannya ke fungsi yang mengharapkan referensi ke jenis target T.
T& operator*() const noexcept;
Referensi ke target com_ptr.
Menetapkan nilai ke objek 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
Jenis yang ditunjukkan oleh nilai yang ditetapkan.
other
Nilai com_ptr untuk ditetapkan ke objek com_ptr. T
Referensi ke objek com_ptr.
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.
auto operator->() const noexcept;
Penunjuk ke antarmuka atau objek yang dirujuk oleh objek com_ptr.
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.
void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;
object
objek com_ptr untuk dioperasikan.
value
Pointer mentah yang memiliki referensi ke targetnya.
Melepaskan objek com_ptr dari antarmuka mentahnya tanpa mengurangi jumlah referensi, mungkin untuk mengembalikannya ke pemanggil.
auto detach_abi(winrt::com_ptr<T>& object) noexcept;
object
objek com_ptr untuk dioperasikan.
Penunjuk ke antarmuka mentah yang dirujuk oleh objek com_ptr.
Mengembalikan nilai yang menunjukkan apakah kedua parameter merujuk ke target yang berbeda.
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
Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.
true
jika dua parameter menunjuk ke target yang berbeda, jika tidak, false
.
Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi lebih awal dalam memori daripada parameter kedua.
template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
left
right
Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.
true
jika alamat memori target parameter pertama kurang dari parameter kedua, jika tidak, false
.
Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi lebih awal dalam memori daripada, atau di lokasi yang sama dengan, parameter kedua.
template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
left
right
Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.
true
jika alamat memori target parameter pertama kurang dari atau sama dengan parameter kedua, jika tidak, false
.
Mengembalikan nilai yang menunjukkan apakah kedua parameter merujuk ke antarmuka dan/atau objek yang sama.
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
Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.
true
jika dua parameter menunjuk ke target yang sama, jika tidak, false
.
Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi nanti dalam memori daripada parameter kedua.
template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
left
right
Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.
true
jika alamat memori target parameter pertama lebih besar dari parameter kedua, jika tidak, false
.
Mengembalikan nilai yang menunjukkan apakah target parameter pertama terjadi nanti dalam memori daripada, atau di lokasi yang sama dengan, parameter kedua.
template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
left
right
Nilai com_ptr yang alamat memori targetnya dibandingkan dengan parameter lainnya.
true
jika alamat memori target parameter pertama lebih besar dari atau sama dengan parameter kedua, jika tidak, false
.
Tukar isi dua parameter com_ptr sehingga menunjuk target satu sama lain.
void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;
left
right
Nilai com_ptr yang penunjuknya saling bertukar dengan parameter lainnya.
- namespace
winrt - Menggunakan API dengan C++/WinRT