Dela via

winrt::com_ptr struct-mall (C++/WinRT)

En referensräknad mall för smarta pekare för COM. com_ptr representerar en pekare till gränssnittet eller implementeringstypen för körningsklassen som anges av mallparametern. Den hanterar automatiskt referensantalet för målet via en privat rå pekare.

Syntax

template <typename T>
struct com_ptr

Mallparametrar

typename T Gränssnittet, eller implementeringstypen för körningsklassen, som en pekare som representeras av com_ptr. Det här är typen av mål för den smarta pekaren.

Kravspecifikation

Minsta SDK som stöds: Windows SDK version 10.0.17134.0 (Windows 10 version 1803)

Namnområde: winrt

Rubrik: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (ingår som standard)

Alias för medlemstyp

Aliasnamn Typ
com_ptr::typ En synonym för en implementeringsdefinierad representation av mallparametern typename T .

Konstruktörer

Konstruktor Beskrivning
com_ptr::com_ptr konstruktör Initierar en ny instans av com_ptr struct, eventuellt med en kopia eller flytt av indata.

Medlemsfunktioner

Funktion Beskrivning
Funktionen com_ptr::as Returnerar det begärda gränssnittet, om det stöds. Kastar om det inte är det.
com_ptr::attach funktion Fäster vid en rå pekare som äger en referens till målet. En ytterligare referens läggs inte till.
com_ptr::capture-funktion Anropar en angiven funktion eller metod (anropar automatiskt winrt::check_hresult på den) och samlar in gränssnittspekaren som är utdata från funktionen eller metoden som en void**.
com_ptr::copy_from funktion Kopierar från en annan pekare. Minskar referensantalet för alla gränssnitt eller objekt som för närvarande refereras, kopierar råpekarparametern och börjar hantera livslängden för gränssnittet eller objektet som det pekar på.
Funktionen com_ptr::copy_to Kopierar till en annan pekare från det com_ptr objektet. Ökar referensantalet för alla gränssnitt eller objekt som för närvarande refereras och kopierar gränssnittets eller objektets minnesadress till parametern.
com_ptr::d etach, funktion Kopplar från det refererade gränssnittet eller objektet utan att minska referensantalet, kanske för att returnera det till en anropare.
com_ptr::get-funktion Returnerar den underliggande rådatapekaren om du behöver skicka den till en funktion.
com_ptr::p ut, funktion Returnerar adressen till den underliggande råpekaren. Den här funktionen hjälper dig att anropa metoder (t.ex. COM-metoder) som returnerar referenser som ut-parametrar via en pekare till en pekare.
com_ptr::p ut_void, funktion Returnerar adressen till den underliggande råpekaren som en pekare till en pekare till void. Den här funktionen hjälper dig att anropa metoder (t.ex. COM-metoder) som returnerar referenser som utparametrar via en pekare till en pekare till void.
Funktionen com_ptr::try_as Returnerar det begärda gränssnittet, om det stöds. Returnerar nullptr, eller false, om det inte är det.
Funktionen com_ptr::try_capture En version av com_ptr::capture som inte utlöser fel utan i stället returnerar returnerar om det true lyckas eller false om det inte lyckas.

Medlems operatorer

Operatör Beskrivning
com_ptr::operatör bool Kontrollerar om den smarta pekaren refererar till ett gränssnitt eller objekt.
com_ptr::operator* (indirekt operator) Returnerar en referens till com_ptr mål så att du kan skicka den till en funktion som förväntar sig en referens till måltypen T.
com_ptr::operator= (tilldelningsoperator) Tilldelar ett värde till det com_ptr objektet.
com_ptr::operator-> (piloperator) För att ge åtkomst till det refererade gränssnittet eller objektets metoder returneras den underliggande råpekaren.

Fria funktioner

Funktion Beskrivning
attach_abi funktion Bifogar ett com_ptr objekt till en rå pekare som äger en referens till målet. En ytterligare referens läggs inte till.
detach_abi funktion Kopplar bort ett com_ptr objekt från dess rådatagränssnitt utan att minska referensantalet, kanske för att returnera det till en anropare.
Swap-funktion Byter plats på innehållet i de två com_ptr parametrarna så att de pekar på varandras mål.

Fria operatörer

Funktion Beskrivning
operator!= (olikhetsoperator) Returnerar ett värde som anger om de två parametrarna refererar till olika mål.
operator< (mindre än-operator) Returnerar ett värde som anger om den första parameterns mål inträffar tidigare i minnet än den andra parameterns.
operator<= (operatorn mindre än eller lika med) Returnerar ett värde som anger om den första parameterns mål inträffar tidigare i minnet än, eller på samma plats som, den andra parametern.
operator== (likhetsoperator) Returnerar ett värde som anger om de två parametrarna refererar till samma gränssnitt och/eller objekt.
operator> (större än-operator) Returnerar ett värde som anger om den första parameterns mål inträffar senare i minnet än den andra parameterns.
operator>= (operatorn större än eller lika med) Returnerar ett värde som anger om den första parameterns mål inträffar senare i minnet än, eller på samma plats som, den andra parametern.

com_ptr::com_ptr konstruktör

Initierar en ny instans av com_ptr struct, eventuellt med en kopia eller flytt av indata.

Konstruktorn void* tar ett T* och tar över ägandet. winrt::take_ownership_from_abi_t är en markörtyp som uttryckligen anger att ansvaret att släppa den här pekaren nu överförs till com_ptr. Referensvärdet behöver inte vara exakt 1; Det är bara att säga att ansvaret överförs.

Syntax

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;

Mallparametrar

typename U Den måltyp som den smarta pekaren pekar på.

Parameterar

other En annan com_ptr som initierar det com_ptr objektet. Parameterns T måste kunna konverteras till det com_ptr objektets T.

Funktionen com_ptr::as

Returnerar det begärda gränssnittet, om det stöds. Kastar om det inte är det. Den här funktionen är användbar om du vill fråga efter ett gränssnitt som du inte behöver skicka tillbaka till anroparen.

Kodexempel finns i avsnittet Instansiera och returnera projicerade typer och gränssnitt och andra avsnitt i det avsnittet.

Syntax

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

Mallparametrar

typename To Typen av det begärda gränssnittet.

Parameterar

to En referens till ett värde för att ta emot det begärda gränssnittet.

Returvärde

En com_ptr som refererar till det begärda gränssnittet eller en starkt skriven smart pekare för det begärda gränssnittet (antingen deklarerad av C++/WinRT eller av en tredje part).

com_ptr::attach funktion

Fäster vid en rå pekare som äger en referens till målet. En ytterligare referens läggs inte till. Om det behövs kan du använda den här funktionen för att sammanfoga referenser.

Syntax

void attach(T* value) noexcept;

Parameterar

value En rå pekare som äger en referens till sitt mål.

com_ptr::capture-funktion

Anropar en angiven funktion eller metod (anropar automatiskt winrt::check_hresult på den) och samlar in gränssnittspekaren som är utdata från funktionen eller metoden som en void**.

Se även functionsmallen winrt::capture.

Syntax

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

Mallparametrar

typename F En funktionsobjekttyp, till exempel en fri funktion, eller std::function.

typename O En gränssnittstyp.

typename M En metodtyp.

typename Args Noll eller flera argumenttyper.

Parameterar

function Ett funktionsobjekt av typen F.

p En pekare till ett objekt av typen O.

object En winrt::com_ptr av typen O.

method En metod (implementerad av O) av typen M.

args Noll eller flera argument av typen Args.

Anmärkningar

  • Överlagringen capture(F function, Args&&...args) anropar funktionsobjektet.
  • Överlagringen capture(O* p, M method, Args&& ...args) anropar metoden på pekaren.
  • Överlagringen capture(winrt::com_ptr<O> const& object, M method, Args&&...args) anropar metoden på objektet.

Alla överlagringar passerar (till anropet) eventuella ytterligare argument som du anger. Alla överlagringar skickar också de två ytterligare argument som sådana anrop kräver, särskilt en REFIID (ID:t för målet för winrt::com_ptr) och en void** (adressen till en pekare till målet för winrt::com_ptr).

Exempel

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

com_ptr::copy_from funktion

Kopierar från en annan pekare. Minskar referensantalet för alla gränssnitt eller objekt som för närvarande refereras, kopierar råpekarparametern och börjar hantera livslängden för gränssnittet eller objektet som det pekar på.

Syntax

void copy_from(T* other) noexcept;

Parameterar

other En rå pekare till ett mål vars livslängd ska hanteras av det com_ptr objektet.

Funktionen com_ptr::copy_to

Kopierar till en annan pekare från det com_ptr objektet. Ökar referensantalet för alla gränssnitt eller objekt som för närvarande refereras och kopierar gränssnittets eller objektets minnesadress till parametern. Med den här funktionen kan du skicka ut en referens till samma gränssnitt utan att anropa QueryInterface.

Syntax

void copy_to(T** other) const noexcept;

Parameterar

other En rå pekares adress; som pekaren ska kopieras till till det com_ptr objektets mål.

com_ptr::d etach, funktion

Kopplar från det refererade gränssnittet eller objektet utan att minska referensantalet, kanske för att returnera det till en anropare.

Syntax

T* detach() noexcept;

Returvärde

En pekare till gränssnittet eller objektet som refereras av det com_ptr objektet.

com_ptr::get-funktion

Returnerar den underliggande rådatapekaren om du behöver skicka den till en funktion. Du kan anropa AddRef, Release eller QueryInterface på den returnerade pekaren.

Syntax

T* get() const noexcept;

Returvärde

En pekare till gränssnittet eller objektet som refereras av det com_ptr objektet.

com_ptr::p ut, funktion

Returnerar adressen till den underliggande råpekaren som ska skickas till en funktion som ska fylla i värdet. Den här funktionen hjälper dig att anropa metoder (t.ex. COM-metoder) som returnerar referenser som ut-parametrar via en pekare till en pekare.

Syntax

T** put() noexcept;

Returvärde

Adressen till den underliggande rådatapekaren.

com_ptr::p ut_void, funktion

Returnerar adressen till den underliggande råpekaren som en pekare till en pekare till void för att skicka den till en funktion (t.ex. COM-metoder) som returnerar referenser som utparametrar via en pekare till en pekare till void.

Syntax

void** put_void() noexcept;

Returvärde

Adressen till den underliggande råpekaren som en pekare till en pekare som ska annulleras.

Funktionen com_ptr::try_as

Returnerar det begärda gränssnittet, om det stöds. Returnerar nullptr (- autoreturnerande överlagring) eller false (- boolreturnerande överlagring), om den inte är det. Den här funktionen är användbar om du vill fråga efter ett gränssnitt som du inte behöver skicka tillbaka till anroparen.

Syntax

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

Mallparametrar

typename To Typen av det begärda gränssnittet.

Parameterar

to En referens till ett värde för att ta emot det begärda gränssnittet.

Returvärde

En com_ptr som refererar till det begärda gränssnittet, eller en starkt typifierad smart pekare för det begärda gränssnittet (antingen deklarerad av C++/WinRT eller av en tredje part), om det begärda gränssnittet stöds, annars nullptr (- autoreturnerande överlagring) eller false (- boolreturnerande överlagring).

Funktionen com_ptr::try_capture

En version av com_ptr::capture som inte utlöser fel utan i stället returnerar returnerar om det true lyckas eller false om det inte lyckas.

Se även funktionsmallen winrt::try_capture.

com_ptr::operatör bool

Kontrollerar om den smarta pekaren refererar till ett gränssnitt eller objekt. Om den smarta pekaren inte refererar till ett gränssnitt eller objekt är den logiskt sett null. Annars är det logiskt sett inte null.

Syntax

explicit operator bool() const noexcept;

Returvärde

true om den smarta pekaren refererar till ett gränssnitt eller objekt (logiskt sett inte null), annars false (logiskt null).

com_ptr::operator* (indirekt operator)

Returnerar en referens till com_ptr mål så att du kan skicka den till en funktion som förväntar sig en referens till måltypen T.

Syntax

T& operator*() const noexcept;

Returvärde

En referens till com_ptr mål.

com_ptr::operator= (tilldelningsoperator)

Tilldelar ett värde till det com_ptr objektet.

Syntax

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;

Mallparametrar

typename U Den typ som pekas på av det värde som tilldelas.

Parameterar

other Ett com_ptr värde som ska tilldelas det com_ptr objektet. Parameterns T måste kunna konverteras till det com_ptr objektets T.

Returvärde

En referens till det com_ptr objektet.

com_ptr::operator-> (piloperator)

För att ge åtkomst till det refererade gränssnittet eller objektets metoder returneras den underliggande råpekaren. Du får inte anropa AddRef eller Release på den returnerade pekaren, men du kan anropa QueryInterface.

Syntax

auto operator->() const noexcept;

Returvärde

En pekare till gränssnittet eller objektet som refereras av det com_ptr objektet.

attach_abi-funktionen

Bifogar ett com_ptr objekt till en rå pekare som äger en referens till målet. En ytterligare referens läggs inte till. Om det behövs kan du använda den här funktionen för att sammanfoga referenser.

Syntax

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

Parameterar

object Ett com_ptr objekt att operera på.

value En rå pekare som äger en referens till sitt mål.

detach_abi funktion

Kopplar bort ett com_ptr objekt från dess rådatagränssnitt utan att minska referensantalet, kanske för att returnera det till en anropare.

Syntax

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

Parameterar

object Ett com_ptr objekt att operera på.

Returvärde

En pekare till det rådatagränssnitt som com_ptr-objektet refererar till.

operator!= (olikhetsoperator)

Returnerar ett värde som anger om de två parametrarna refererar till olika mål.

Syntax

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;

Parameterar

left right Ett com_ptr värde vars målminnesadress ska jämföras med den andra parameterns.

Returvärde

true Om de två parametrarna pekar på olika mål, annars false.

operator< (mindre än-operator)

Returnerar ett värde som anger om den första parameterns mål inträffar tidigare i minnet än den andra parameterns.

Syntax

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

Parameterar

left right Ett com_ptr värde vars målminnesadress ska jämföras med den andra parameterns.

Returvärde

true Om den första parameterns målminnesadress är mindre än den för den andra parametern, annars false.

operator<= (operatorn mindre än eller lika med)

Returnerar ett värde som anger om den första parameterns mål inträffar tidigare i minnet än, eller på samma plats som, den andra parametern.

Syntax

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

Parameterar

left right Ett com_ptr värde vars målminnesadress ska jämföras med den andra parameterns.

Returvärde

true Om den första parameterns måladress är mindre än eller lika med den för den andra parametern, annars false.

operator== (likhetsoperator)

Returnerar ett värde som anger om de två parametrarna refererar till samma gränssnitt och/eller objekt.

Syntax

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;

Parameterar

left right Ett com_ptr värde vars målminnesadress ska jämföras med den andra parameterns.

Returvärde

true Om de två parametrarna pekar på samma mål, annars false.

operator> (större än-operator)

Returnerar ett värde som anger om den första parameterns mål inträffar senare i minnet än den andra parameterns.

Syntax

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

Parameterar

left right Ett com_ptr värde vars målminnesadress ska jämföras med den andra parameterns.

Returvärde

true Om den första parameterns målminnesadress är större än den för den andra parametern, annars false.

operator>= (operatorn större än eller lika med)

Returnerar ett värde som anger om den första parameterns mål inträffar senare i minnet än, eller på samma plats som, den andra parametern.

Syntax

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

Parameterar

left right Ett com_ptr värde vars målminnesadress ska jämföras med den andra parameterns.

Returvärde

true Om den första parameterns målminnesadress är större än eller lika med den för den andra parametern, annars false.

växlingsfunktion

Byter plats på innehållet i de två com_ptr parametrarna så att de pekar på varandras mål.

Syntax

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

Parameterar

left right Ett com_ptr värde vars pekare ska växlas med den andra parameterns.

Se även