szablon struktury winrt::com_ptr (C++/WinRT)

2025-05-08

Szablon inteligentnego wskaźnika COM zliczany przez odwołania. com_ptr reprezentuje wskaźnik do typu implementacji interfejsu lub klasy środowiska uruchomieniowego określonego przez parametr szablonu. Automatycznie zarządza liczbą odwołań dla swojego obiektu docelowego za pomocą prywatnego nieprzetworzonego wskaźnika.

Składnia

template <typename T>
struct com_ptr

Parametry szablonu

typename T Interfejs lub typ implementacji klasy środowiska uruchomieniowego, do którego wskaźnik jest reprezentowany przez com_ptr. Jest to typ celu inteligentnego wskaźnika.

Wymagania

Minimalny obsługiwany zestaw SDK: Windows SDK w wersji 10.0.17134.0 (Windows 10, wersja 1803)

Przestrzeń nazw: winrt

Nagłówek: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (dołączone domyślnie)

Aliasy typów składowych

Nazwa aliasu	Typ
com_ptr::type	Synonim zdefiniowanej przez implementację reprezentacji parametru szablonu `typename T` .

Konstruktory

Konstruktor	Opis
Konstruktor com_ptr::com_ptr	Inicjuje nowe wystąpienie struktury com_ptr , opcjonalnie z kopią lub przeniesieniem danych wejściowych.

Funkcje składowe

Funkcja	Opis
com_ptr::as funkcja	Zwraca żądany interfejs, jeśli jest obsługiwany. Zgłasza jeśli tak nie jest.
com_ptr::funkcja dołączania	Dołącza do nieprzetworzonego wskaźnika, który posiada odwołanie do swojego celu; Dodatkowe odniesienie nie jest dodawane.
com_ptr::funkcja przechwytywania	Wywołuje określoną funkcję lub metodę (automatycznie wywołując na niej winrt::check_hresult ) i przechwytuje wskaźnik interfejsu, który jest wyprowadzany z funkcji lub metody jako `void**`.
com_ptr::copy_from funkcja	Kopie z innego wskaźnika. Zmniejsza liczbę odwołań w dowolnym aktualnie przywoływanym interfejsie lub obiekcie, kopiuje nieprzetworzony parametr wskaźnika i rozpoczyna zarządzanie okresem istnienia interfejsu lub obiektu wskazywanego przez niego.
com_ptr::copy_to funkcja	Kopiuje do innego wskaźnika z obiektu com_ptr . Zwiększa liczbę odwołań dla dowolnego aktualnie przywoływanego interfejsu lub obiektu, a następnie kopiuje adres pamięci tego interfejsu lub obiektu do parametru.
com_ptr::d etach funkcja	Odłącza się od interfejsu lub obiektu, do którego odwołuje się odwołanie, bez zmniejszania liczby odwołań, na przykład w celu zwrócenia go do obiektu wywołującego.
com_ptr::get funkcja	Zwraca podstawowy nieprzetworzony wskaźnik, jeśli trzeba go przekazać do funkcji.
com_ptr::p ut, funkcja	Zwraca adres bazowego wskaźnika nieprzetworzonego; Ta funkcja ułatwia wywoływanie metod (takich jak metody COM), które zwracają odwołania jako parametry out za pośrednictwem wskaźnika do wskaźnika.
com_ptr::p ut_void, funkcja	Zwraca adres bazowego nieprzetworzonego wskaźnika jako wskaźnik do wskaźnika do void; Ta funkcja ułatwia wywoływanie metod (takich jak metody COM), które zwracają odwołania jako parametry wyjściowe za pośrednictwem wskaźnika do void.
com_ptr::try_as funkcja	Zwraca żądany interfejs, jeśli jest obsługiwany. Zwraca `nullptr`wartość , lub `false`, jeśli tak nie jest.
com_ptr::try_capture funkcja	Wersja com_ptr::capture , która nie zgłasza niepowodzenia, ale zamiast tego zwraca zwroty `true` , jeśli się powiodły lub `false` jeśli nie.

Operatorzy członkowscy

Obsługujący	Opis
com_ptr::operator bool	Sprawdza, czy inteligentny wskaźnik odwołuje się do interfejsu lub obiektu.
com_ptr::operator* (operator pośredni)	Zwraca odwołanie do obiektu docelowego com_ptr, dzięki czemu można je przekazać do funkcji, która oczekuje odwołania do typu docelowego T.
com_ptr::operator= (operator przypisania)	Przypisuje wartość do obiektu com_ptr .
com_ptr::operator-> (operator strzałki)	Aby umożliwić dostęp do przywoływanego interfejsu lub metod obiektu, zwraca bazowy nieprzetworzony wskaźnik.

Darmowe funkcje

Funkcja	Opis
attach_abi funkcja	Dołącza obiekt com_ptr do nieprzetworzonego wskaźnika, który posiada odwołanie do swojego celu; Dodatkowe odniesienie nie jest dodawane.
detach_abi funkcja	Odłącza obiekt com_ptr od jego nieprzetworzonego interfejsu bez zmniejszania liczby odwołań, na przykład w celu zwrócenia go do obiektu wywołującego.
Funkcja zamiany	Zamiana zawartości dwóch parametrów com_ptr tak, aby wskazywały nawzajem na swój cel.

Wolni operatorzy

Funkcja	Opis
operator!= (operator nierówności)	Zwraca wartość wskazującą, czy te dwa parametry odwołują się do różnych obiektów docelowych.
operator< (operator mniejszy niż)	Zwraca wartość wskazującą, czy element docelowy pierwszego parametru występuje wcześniej w pamięci niż drugi parametr.
operator<= (operator mniejszy lub równy)	Zwraca wartość wskazującą, czy element docelowy pierwszego parametru występuje wcześniej w pamięci niż drugi parametr lub w tym samym miejscu, co drugi parametr.
operator== (operator równości)	Zwraca wartość wskazującą, czy dwa parametry odwołują się do tego samego interfejsu i/lub obiektu.
operator> (operator większy niż maksymalny)	Zwraca wartość wskazującą, czy element docelowy pierwszego parametru występuje później w pamięci niż drugi parametr.
operator>= (operator większy lub równy do)	Zwraca wartość wskazującą, czy element docelowy pierwszego parametru występuje później w pamięci niż drugi parametr lub w tym samym miejscu, co drugi parametr.

Konstruktor com_ptr::com_ptr

Inicjuje nowe wystąpienie struktury com_ptr , opcjonalnie z kopią lub przeniesieniem danych wejściowych.

Konstruktor void* przyjmuje T* i przyjmuje własność. winrt::take_ownership_from_abi_t jest typem znacznika, który wyraźnie zaznacza, że odpowiedzialność za zwolnienie tego wskaźnika jest teraz przenoszona na com_ptr. Liczba refów nie musi wynosić dokładnie 1; To po prostu mówi, że odpowiedzialność jest przenoszona.

Składnia

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;

Parametry szablonu

typename U Typ docelowy wskazywany przez wejściowy wskaźnik inteligentny.

Parametry

other Kolejny com_ptr , który inicjuje obiekt com_ptr . T parametru musi być konwertowany na T obiektu com_ptr.

com_ptr::as funkcja

Zwraca żądany interfejs, jeśli jest obsługiwany. Zgłasza jeśli tak nie jest. Ta funkcja jest przydatna, jeśli chcesz wykonać zapytanie dotyczące interfejsu, którego nie musisz przekazywać z powrotem do obiektu wywołującego.

Aby zapoznać się z przykładami kodu, zobacz sekcję Tworzenie i zwracanie projektowanych typów i interfejsów oraz inne sekcje w tym temacie.

Składnia

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

Parametry szablonu

typename To Typ żądanego interfejsu.

Parametry

to Odwołanie do wartości, która ma otrzymać żądany interfejs.

Wartość zwracana

com_ptr odwołujący się do żądanego interfejsu lub silnie typizowany inteligentny wskaźnik dla żądanego interfejsu (zadeklarowany przez język C++/WinRT lub przez inną firmę).

com_ptr::funkcja dołączania

Dołącza do nieprzetworzonego wskaźnika, który posiada odwołanie do swojego celu; Dodatkowe odniesienie nie jest dodawane. W razie potrzeby można użyć tej funkcji do łączenia odwołań.

Składnia

void attach(T* value) noexcept;

Parametry

value Nieprzetworzony wskaźnik, który posiada odwołanie do swojego elementu docelowego.

com_ptr::funkcja przechwytywania

Wywołuje określoną funkcję lub metodę (automatycznie wywołując na niej winrt::check_hresult ) i przechwytuje wskaźnik interfejsu, który jest wyprowadzany z funkcji lub metody jako void**.

Zobacz także szablon funkcji winrt::capture.

Składnia

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

Parametry szablonu

typename F Typ obiektu funkcji, taki jak funkcja free lub std::function.

typename O Typ interfejsu.

typename M Typ metody.

typename Args Zero lub więcej typów argumentów.

Parametry

function Obiekt funkcyjny typu F.

p Wskaźnik do obiektu typu O.

object Winrt::com_ptr typu O.

method Metoda (zaimplementowana przez O) typu M.

args Zero lub więcej argumentów typu Args.

Uwagi

Przeciążenie capture(F function, Args&&...args) wywołuje obiekt funkcji.
Przeciążenie capture(O* p, M method, Args&& ...args) wywołuje metodę na wskaźniku.
Przeciążenie capture(winrt::com_ptr<O> const& object, M method, Args&&...args) wywołuje metodę w obiekcie.

Wszystkie przeciążenia przechodzą przez (do invokee) wszelkie dodatkowe argumenty, które podasz. Wszystkie przeciążenia przekazują również dwa dodatkowe argumenty, które są wymagane przez takie wywołania — w szczególności REFIID (identyfikator obiektu docelowego winrt::com_ptr) i void** (adres wskaźnika do celu winrt::com_ptr).

Przykład

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

com_ptr::copy_from funkcja

Kopie z innego wskaźnika. Zmniejsza liczbę odwołań w dowolnym aktualnie przywoływanym interfejsie lub obiekcie, kopiuje nieprzetworzony parametr wskaźnika i rozpoczyna zarządzanie okresem istnienia interfejsu lub obiektu wskazywanego przez niego.

Składnia

void copy_from(T* other) noexcept;

Parametry

other Nieprzetworzony wskaźnik do elementu docelowego, którego okres istnienia powinien być zarządzany przez obiekt com_ptr .

com_ptr::copy_to funkcja

Kopiuje do innego wskaźnika z obiektu com_ptr . Zwiększa liczbę odwołań dla dowolnego aktualnie przywoływanego interfejsu lub obiektu, a następnie kopiuje adres pamięci tego interfejsu lub obiektu do parametru. Ta funkcja umożliwia przekazanie odwołania do tego samego interfejsu bez wywoływania metody QueryInterface.

Składnia

void copy_to(T** other) const noexcept;

Parametry

other Surowy adres wskaźnika; do którego skopiować wskaźnik do obiektu docelowego com_ptr .

com_ptr::d etach funkcja

Odłącza się od interfejsu lub obiektu, do którego odwołuje się odwołanie, bez zmniejszania liczby odwołań, na przykład w celu zwrócenia go do obiektu wywołującego.

Składnia

T* detach() noexcept;

Wartość zwracana

Wskaźnik do interfejsu lub obiektu, do którego odwołuje się obiekt com_ptr .

com_ptr::get funkcja

Zwraca podstawowy nieprzetworzony wskaźnik, jeśli trzeba go przekazać do funkcji. Możesz wywołać AddRef, Release lub QueryInterface w zwróconym wskaźniku.

Składnia

T* get() const noexcept;

Wartość zwracana

Wskaźnik do interfejsu lub obiektu, do którego odwołuje się obiekt com_ptr .

com_ptr::p ut, funkcja

Zwraca adres bazowego nieprzetworzonego wskaźnika, który ma zostać przekazany do funkcji, która wypełni wartość; Ta funkcja ułatwia wywoływanie metod (takich jak metody COM), które zwracają odwołania jako parametry out za pośrednictwem wskaźnika do wskaźnika.

Składnia

T** put() noexcept;

Wartość zwracana

Adres bazowego nieprzetworzonego wskaźnika.

com_ptr::p ut_void, funkcja

Zwraca adres bazowego nieprzetworzonego wskaźnika jako wskaźnik do wskaźnika do void , aby przekazać go do funkcji (takiej jak metody COM), która zwraca odwołania jako parametry wyjściowe za pośrednictwem wskaźnika do void.

Składnia

void** put_void() noexcept;

Wartość zwracana

Adres bazowego nieprzetworzonego wskaźnika jako wskaźnik do wskaźnika do void.

com_ptr::try_as funkcja

Zwraca żądany interfejs, jeśli jest obsługiwany. Zwraca nullptr (-zwracające przeciążenie auto) lub false (-zwracające przeciążenie bool), jeśli tak nie jest. Ta funkcja jest przydatna, jeśli chcesz wykonać zapytanie dotyczące interfejsu, którego nie musisz przekazywać z powrotem do obiektu wywołującego.

Składnia

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

Parametry szablonu

typename To Typ żądanego interfejsu.

Parametry

to Odwołanie do wartości, która ma otrzymać żądany interfejs.

Wartość zwracana

com_ptr odwołujący się do żądanego interfejsu lub silnie typizowany inteligentny wskaźnik dla żądanego interfejsu (zadeklarowany przez język C++/WinRT lub przez inną firmę), jeśli żądany interfejs jest obsługiwany, w przeciwnym razie nullptr (-zwracane przeciążenieauto) lub false (bool-return przeciążenie).

com_ptr::try_capture funkcja

Wersja com_ptr::capture , która nie zgłasza niepowodzenia, ale zamiast tego zwraca zwroty true , jeśli się powiodły lub false jeśli nie.

Zobacz również szablon funkcji winrt::try_capture.

com_ptr::operator bool

Sprawdza, czy inteligentny wskaźnik odwołuje się do interfejsu lub obiektu. Jeśli inteligentny wskaźnik nie odwołuje się do interfejsu lub obiektu, to logicznie jest pusty; w przeciwnym razie logicznie nie jest pusty.

Składnia

explicit operator bool() const noexcept;

Wartość zwracana

true Jeśli wskaźnik Smart odwołuje się do interfejsu lub obiektu (logicznie nie ma wartości null), w przeciwnym razie false (logicznie ma wartość null).

com_ptr::operator* (operator pośredni)

Zwraca odwołanie do obiektu docelowego com_ptr, dzięki czemu można je przekazać do funkcji, która oczekuje odwołania do typu docelowego T.

Składnia

T& operator*() const noexcept;

Wartość zwracana

Odniesienie do celu com_ptr.

com_ptr::operator= (operator przypisania)

Przypisuje wartość do obiektu com_ptr .

Składnia

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;

Parametry szablonu

typename U Typ wskazywany przez przypisywaną wartość.

Parametry

other Wartość com_ptr , która ma zostać przypisana do obiektu com_ptr . T parametru musi być konwertowany na T obiektu com_ptr.

Wartość zwracana

Odwołanie do obiektu com_ptr .

com_ptr::operator-> (operator strzałki)

Aby umożliwić dostęp do przywoływanego interfejsu lub metod obiektu, zwraca bazowy nieprzetworzony wskaźnik. Nie można wywołać metody AddRef ani Release zwróconego wskaźnika, ale można wywołać metodę QueryInterface.

Składnia

auto operator->() const noexcept;

Wartość zwracana

Wskaźnik do interfejsu lub obiektu, do którego odwołuje się obiekt com_ptr .

funkcja attach_abi

Dołącza obiekt com_ptr do nieprzetworzonego wskaźnika, który posiada odwołanie do swojego celu; Dodatkowe odniesienie nie jest dodawane. W razie potrzeby można użyć tej funkcji do łączenia odwołań.

Składnia

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

Parametry

object Obiekt com_ptr do operacji.

value Nieprzetworzony wskaźnik, który posiada odwołanie do swojego elementu docelowego.

funkcja detach_abi

Odłącza obiekt com_ptr od jego nieprzetworzonego interfejsu bez zmniejszania liczby odwołań, na przykład w celu zwrócenia go do obiektu wywołującego.

Składnia

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

Parametry

object Obiekt com_ptr do operacji.

Wartość zwracana

Wskaźnik do nieprzetworzonego interfejsu, do którego odwołuje się obiekt com_ptr .

operator!= (operator nierówności)

Zwraca wartość wskazującą, czy te dwa parametry odwołują się do różnych obiektów docelowych.

Składnia

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;

Parametry

left right Wartość com_ptr , której adres pamięci docelowej ma być porównywany z adresem pamięci innego parametru.

Wartość zwracana

true Jeśli te dwa parametry wskazują różne cele, w przeciwnym razie false.

operator< (operator mniejszy niż)

Zwraca wartość wskazującą, czy element docelowy pierwszego parametru występuje wcześniej w pamięci niż drugi parametr.

Składnia

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

Parametry

left right Wartość com_ptr , której adres pamięci docelowej ma być porównywany z adresem pamięci innego parametru.

Wartość zwracana

true Jeśli adres pamięci docelowej pierwszego parametru jest mniejszy niż adres pamięci drugiego parametru, w przeciwnym razie false.

operator<= (operator mniejszy lub równy)

Zwraca wartość wskazującą, czy element docelowy pierwszego parametru występuje wcześniej w pamięci niż drugi parametr lub w tym samym miejscu, co drugi parametr.

Składnia

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

Parametry

left right Wartość com_ptr , której adres pamięci docelowej ma być porównywany z adresem pamięci innego parametru.

Wartość zwracana

true Jeśli adres pamięci docelowej pierwszego parametru jest mniejszy lub równy adresowi pamięci drugiego parametru, w przeciwnym razie false.

operator== (operator równości)

Zwraca wartość wskazującą, czy dwa parametry odwołują się do tego samego interfejsu i/lub obiektu.

Składnia

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;

Parametry

left right Wartość com_ptr , której adres pamięci docelowej ma być porównywany z adresem pamięci innego parametru.

Wartość zwracana

true Jeśli dwa parametry wskazują na ten sam cel, w przeciwnym razie false.

operator> (operator większy niż maksymalny)

Zwraca wartość wskazującą, czy element docelowy pierwszego parametru występuje później w pamięci niż drugi parametr.

Składnia

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

Parametry

left right Wartość com_ptr , której adres pamięci docelowej ma być porównywany z adresem pamięci innego parametru.

Wartość zwracana

true Jeśli adres pamięci docelowej pierwszego parametru jest większy niż adres pamięci drugiego parametru, w przeciwnym razie false.

operator>= (operator większy lub równy do)

Zwraca wartość wskazującą, czy element docelowy pierwszego parametru występuje później w pamięci niż drugi parametr lub w tym samym miejscu, co drugi parametr.

Składnia

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

Parametry

left right Wartość com_ptr , której adres pamięci docelowej ma być porównywany z adresem pamięci innego parametru.

Wartość zwracana

true Jeśli adres pamięci celu pierwszego parametru jest większy lub równy adresowi pamięci drugiego parametru, w przeciwnym razie false.

funkcja swap

Zamiana zawartości dwóch parametrów com_ptr tak, aby wskazywały nawzajem na swój cel.

Składnia

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

Parametry

left right Wartość com_ptr , której wskaźnik jest wzajemnie zamieniany ze wskaźnikiem innego parametru.

Udostępnij za pośrednictwem

szablon struktury winrt::com_ptr (C++/WinRT)

Składnia

Parametry szablonu

Wymagania

Aliasy typów składowych

Konstruktory

Funkcje składowe

Operatorzy członkowscy

Darmowe funkcje

Wolni operatorzy

Konstruktor com_ptr::com_ptr

Składnia

Parametry szablonu

Parametry

com_ptr::as funkcja

Składnia

Parametry szablonu

Parametry

Wartość zwracana

com_ptr::funkcja dołączania

Składnia

Parametry

com_ptr::funkcja przechwytywania

Składnia

Parametry szablonu

Parametry

Uwagi

Przykład

com_ptr::copy_from funkcja

Składnia

Parametry

com_ptr::copy_to funkcja

Składnia

Parametry

com_ptr::d etach funkcja

Składnia

Wartość zwracana

com_ptr::get funkcja

Składnia

Wartość zwracana

com_ptr::p ut, funkcja

Składnia

Wartość zwracana

com_ptr::p ut_void, funkcja

Składnia

Wartość zwracana

com_ptr::try_as funkcja

Składnia

Parametry szablonu

Parametry

Wartość zwracana

com_ptr::try_capture funkcja

com_ptr::operator bool

Składnia

Wartość zwracana

com_ptr::operator* (operator pośredni)

Składnia

Wartość zwracana

com_ptr::operator= (operator przypisania)

Składnia

Parametry szablonu

Parametry

Wartość zwracana

com_ptr::operator-> (operator strzałki)

Składnia

Wartość zwracana

funkcja attach_abi

Składnia

Parametry

funkcja detach_abi

Składnia

Parametry

Wartość zwracana

operator!= (operator nierówności)

Składnia

Parametry

Wartość zwracana

operator< (operator mniejszy niż)

Składnia