Freigeben über

winrt::com_ptr Strukturvorlage (C++/WinRT)

  • Artikel

Eine smarte COM-Zeigervorlage mit Verweiszählung. com_ptr stellt einen Zeiger auf den vom Vorlagenparameter angegebenen Typ der Schnittstellen- oder Laufzeitklassenimplementierung dar. Die Referenzanzahl für das Ziel wird automatisch über einen privaten unformatierten Zeiger verwaltet.

Syntax

template <typename T>
struct com_ptr

Vorlagenparameter

typename T Der Schnittstellen- oder Laufzeitklassenimplementierungstyp, auf den der Zeiger durch die com_ptrdargestellt wird. Dies ist der Typ des Ziels des intelligenten Zeigers.

Anforderungen

Mindestens unterstützte SDK: Windows SDK, Version 10.0.17134.0 (Windows 10, Version 1803)

Namespace: winrt

Header: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (standardmäßig enthalten)

Membertypaliasen

Aliasname Art
com_ptr::type Ein Synonym für eine implementierungsdefinierte Darstellung des typename T Vorlagenparameters.

Erbauer

Konstruktor Beschreibung
com_ptr::com_ptr-Konstruktor Initialisiert eine neue Instanz der com_ptr Struktur, optional mit einer Kopie oder einem Verschieben der Eingabedaten.

Memberfunktionen

Funktion Beschreibung
com_ptr::as-Funktion Gibt die angeforderte Schnittstelle zurück, wenn sie unterstützt wird. Löst aus, wenn dies nicht der Fehler ist.
com_ptr::Attach-Funktion Fügt einen unformatierten Zeiger an, der einen Verweis auf sein Ziel besitzt; Ein zusätzlicher Verweis wird nicht hinzugefügt.
com_ptr::Capture-Funktion Ruft eine angegebene Funktion oder Methode auf (automatisch aufrufen winrt::check_hresult darauf), und erfasst den Schnittstellenzeiger, der von der Funktion oder Methode als void**ausgegeben wird.
com_ptr::copy_from Funktion Kopien von einem anderen Zeiger. Erhöht die Referenzanzahl für alle derzeit referenzierten Schnittstellen oder Objekte, kopiert den unformatierten Zeigerparameter und beginnt mit der Verwaltung der Lebensdauer der Schnittstelle oder des Objekts, auf die bzw. das darauf verweist.
com_ptr::copy_to Funktion Kopiert in einen anderen Zeiger aus dem com_ptr-Objekt. Erhöht die Referenzanzahl für alle aktuell referenzierten Schnittstellen oder Objekte und kopiert die Speicheradresse dieser Schnittstelle oder des Objekts in den Parameter.
com_ptr::d etach-Funktion Trennt von der referenzierten Schnittstelle oder dem Objekt, ohne die Referenzanzahl zu erhöhen, vielleicht um sie an einen Aufrufer zurückzugeben.
com_ptr::get-Funktion Gibt den zugrunde liegenden unformatierten Zeiger zurück, wenn Sie ihn an eine Funktion übergeben müssen.
com_ptr::p ut-Funktion Gibt die Adresse des zugrunde liegenden unformatierten Zeigers zurück. Diese Funktion unterstützt Sie beim Aufrufen von Methoden (z. B. COM-Methoden), die Verweise als Ausgabeparameter über einen Zeiger auf einen Zeiger zurückgeben.
com_ptr::p ut_void function Gibt die Adresse des zugrunde liegenden unformatierten Zeigers als Zeiger auf einen Zeiger auf voidzurück; Diese Funktion hilft Ihnen beim Aufrufen von Methoden (z. B. COM-Methoden), die Verweise als Ausgabeparameter über einen Zeiger auf einen Zeiger auf voidzurückgeben.
com_ptr::try_as Funktion Gibt die angeforderte Schnittstelle zurück, wenn sie unterstützt wird. Gibt nullptroder falsezurück, wenn dies nicht der Fehler ist.
com_ptr::try_capture Funktion Eine Version von com_ptr::capture, die beim Fehler nicht ausgelöst wird, sondern gibt stattdessen true zurück, wenn dies erfolgreich ist oder false.

Memberoperatoren

Operator Beschreibung
com_ptr::operator bool Überprüft, ob der intelligente Zeiger auf eine Schnittstelle oder ein Objekt verweist.
com_ptr::operator* (Dereferenzierungsoperator) Gibt einen Verweis auf das Ziel des com_ptrzurück, sodass Sie ihn an eine Funktion übergeben können, die einen Verweis auf den Zieltyp erwartet, T.
com_ptr::operator= (Zuordnungsoperator) Weist dem com_ptr -Objekt einen Wert zu.
com_ptr::operator-> (Pfeiloperator) Gibt den zugrunde liegenden unformatierten Zeiger zurück, um zugriff auf die Methoden der referenzierten Schnittstelle oder des Objekts zu gewähren.

Kostenlose Funktionen

Funktion Beschreibung
attach_abi-Funktion Fügt ein com_ptr -Objekt an einen unformatierten Zeiger an, der einen Verweis auf sein Ziel besitzt; Ein zusätzlicher Verweis wird nicht hinzugefügt.
detach_abi Funktion Trennt ein com_ptr -Objekt von der unformatierten Schnittstelle, ohne die Verweisanzahl zu erhöhen, vielleicht um es an einen Aufrufer zurückzugeben.
Swap-Funktion Tauscht den Inhalt der beiden com_ptr Parameter so, dass sie auf das Ziel eines anderen zeigen.

Kostenlose Betreiber

Funktion Beschreibung
Operator!= (Ungleichheitsoperator) Gibt einen Wert zurück, der angibt, ob die beiden Parameter auf unterschiedliche Ziele verweisen.
Operator< (kleiner als Operator) Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters früher im Arbeitsspeicher als der des zweiten Parameters auftritt.
Operator<= (kleiner-als-oder-gleich-operator) Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters früher im Arbeitsspeicher als oder an derselben Position wie der zweite Parameter auftritt.
Operator== (Gleichheitsoperator) Gibt einen Wert zurück, der angibt, ob die beiden Parameter auf dieselbe Schnittstelle und/oder ein Objekt verweisen.
Operator> (Größer-als-Operator) Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters später im Arbeitsspeicher als der des zweiten Parameters auftritt.
Operator>= (größer-oder-gleich-operator) Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters später im Arbeitsspeicher auftritt als oder an derselben Position wie die des zweiten Parameters.

com_ptr::com_ptr-Konstruktor

Initialisiert eine neue Instanz der com_ptr Struktur, optional mit einer Kopie oder einem Verschieben der Eingabedaten.

Der void*-Konstruktor akzeptiert ein T*, und übernimmt den Besitz. winrt::take_ownership_from_abi_t ist ein Markertyp, der explizit die Verantwortung, diesen Zeiger freizugeben, jetzt auf die com_ptrübertragen wird. Der Refcount muss nicht genau 1 sein; es sagt einfach, dass die Verantwortung übertragen wird.

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;

Vorlagenparameter

typename U Der Zieltyp, auf den der eingabe intelligente Zeiger verweist.

Parameter

other Eine weitere com_ptr, die das com_ptr-Objekt initialisiert. Der T- des Parameters muss in den T-des com_ptr Objekts konvertierbar sein.

com_ptr::as

Gibt die angeforderte Schnittstelle zurück, wenn sie unterstützt wird. Löst aus, wenn dies nicht der Fehler ist. Diese Funktion ist nützlich, wenn Sie eine Schnittstelle abfragen möchten, die Sie nicht an Den Aufrufer übergeben müssen.

Codebeispiele finden Sie im Abschnitt Instanziieren und Zurückgeben projizierter Typen und Schnittstellenund anderer Abschnitte in diesem Thema.

Syntax

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

Vorlagenparameter

typename To Der Typ der angeforderten Schnittstelle.

Parameter

to Ein Verweis auf einen Wert, der die angeforderte Schnittstelle empfängt.

Rückgabewert

Ein com_ptr auf die angeforderte Schnittstelle oder einen stark typografischen Intelligenten Zeiger für die angeforderte Schnittstelle verweisen (entweder von C++/WinRT oder von einem Drittanbieter deklariert).

com_ptr::Attach-Funktion

Fügt einen unformatierten Zeiger an, der einen Verweis auf sein Ziel besitzt; Ein zusätzlicher Verweis wird nicht hinzugefügt. Bei Bedarf können Sie diese Funktion verwenden, um Bezüge zu klammern.

Syntax

void attach(T* value) noexcept;

Parameter

value Ein unformatierter Zeiger, der einen Verweis auf sein Ziel besitzt.

com_ptr::Capture-Funktion

Ruft eine angegebene Funktion oder Methode auf (automatisch aufrufen winrt::check_hresult darauf), und erfasst den Schnittstellenzeiger, der von der Funktion oder Methode als void**ausgegeben wird.

Siehe auch die winrt::capture-Funktionsvorlage.

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

Vorlagenparameter

typename F Ein Funktionsobjekttyp, z. B. eine freie Funktion, oder std::function.

typename O Ein Schnittstellentyp.

typename M A-Methodentyp.

typename Args Null oder mehr Argumenttypen.

Parameter

function Ein Funktionsobjekt vom Typ F.

p Ein Zeiger auf ein Objekt vom Typ O.

object Ein winrt::com_ptr vom Typ O.

method A-Methode (implementiert durch O) vom Typ M.

args Null oder mehr Argumente vom Typ Args.

Bemerkungen

  • Die capture(F function, Args&&...args)-Überladung ruft das Funktionsobjekt auf.
  • Die capture(O* p, M method, Args&& ...args)-Überladung ruft die Methode auf dem Zeiger auf.
  • Die capture(winrt::com_ptr<O> const& object, M method, Args&&...args)-Überladung ruft die Methode für das Objekt auf.

Alle Überladungen durchlaufen (an den Aufruf) alle zusätzlichen Argumente, die Sie angeben. Alle Überladungen übergeben auch die beiden zusätzlichen Argumente, die solche Aufrufe erfordern , insbesondere eine REFIID- (die ID des Ziels der winrt::com_ptr), und eine void** (Die Adresse eines Zeigers auf das Ziel der winrt::com_ptr).

Beispiel

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

com_ptr::copy_from-Funktion

Kopien von einem anderen Zeiger. Erhöht die Referenzanzahl für alle derzeit referenzierten Schnittstellen oder Objekte, kopiert den unformatierten Zeigerparameter und beginnt mit der Verwaltung der Lebensdauer der Schnittstelle oder des Objekts, auf die bzw. das darauf verweist.

Syntax

void copy_from(T* other) noexcept;

Parameter

other Ein unformatierter Zeiger auf ein Ziel, dessen Lebensdauer vom com_ptr-Objekt verwaltet werden soll.

com_ptr::copy_to-Funktion

Kopiert in einen anderen Zeiger aus dem com_ptr-Objekt. Erhöht die Referenzanzahl für alle aktuell referenzierten Schnittstellen oder Objekte und kopiert die Speicheradresse dieser Schnittstelle oder des Objekts in den Parameter. Mit dieser Funktion können Sie einen Verweis auf dieselbe Schnittstelle verteilen, ohne QueryInterface-aufrufen zu müssen.

Syntax

void copy_to(T** other) const noexcept;

Parameter

other Adresse eines unformatierten Zeigers; in die der Zeiger auf das Ziel des com_ptr Objekts kopiert werden soll.

com_ptr::d trennfunktion

Trennt von der referenzierten Schnittstelle oder dem Objekt, ohne die Referenzanzahl zu erhöhen, vielleicht um sie an einen Aufrufer zurückzugeben.

Syntax

T* detach() noexcept;

Rückgabewert

Ein Zeiger auf die Schnittstelle oder das Objekt, auf die vom com_ptr-Objekt verwiesen wird.

com_ptr::get-Funktion

Gibt den zugrunde liegenden unformatierten Zeiger zurück, wenn Sie ihn an eine Funktion übergeben müssen. Sie können AddRef-, Release-oder QueryInterface- für den zurückgegebenen Zeiger aufrufen.

Syntax

T* get() const noexcept;

Rückgabewert

Ein Zeiger auf die Schnittstelle oder das Objekt, auf die vom com_ptr-Objekt verwiesen wird.

com_ptr::p ut-Funktion

Gibt die Adresse des zugrunde liegenden unformatierten Zeigers zurück. Diese Funktion unterstützt Sie beim Aufrufen von Methoden (z. B. COM-Methoden), die Verweise als Ausgabeparameter über einen Zeiger auf einen Zeiger zurückgeben. Wenn das com_ptr-Objekt bereits über ein Ziel verfügt, weisen Sie dem com_ptr-Objekt nullptr zu, bevor diese Funktion aufgerufen wird, andernfalls wird die Funktion bestätigt.

Syntax

T** put() noexcept;

Rückgabewert

Die Adresse des zugrunde liegenden unformatierten Zeigers.

com_ptr::p ut_void-Funktion

Gibt die Adresse des zugrunde liegenden unformatierten Zeigers als Zeiger auf einen Zeiger auf voidzurück; Diese Funktion hilft Ihnen beim Aufrufen von Methoden (z. B. COM-Methoden), die Verweise als Ausgabeparameter über einen Zeiger auf einen Zeiger auf voidzurückgeben. Wenn das com_ptr-Objekt bereits über ein Ziel verfügt, weisen Sie dem com_ptr-Objekt nullptr zu, bevor diese Funktion aufgerufen wird, andernfalls wird die Funktion bestätigt.

Syntax

void** put_void() noexcept;

Rückgabewert

Die Adresse des zugrunde liegenden unformatierten Zeigers als Zeiger auf einen Zeiger auf void.

com_ptr::try_as-Funktion

Gibt die angeforderte Schnittstelle zurück, wenn sie unterstützt wird. Gibt nullptr (die auto-returning overload) oder false (die bool-returning overload) zurück, wenn dies nicht der Grund ist. Diese Funktion ist nützlich, wenn Sie eine Schnittstelle abfragen möchten, die Sie nicht an Den Aufrufer übergeben müssen.

Syntax

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

Vorlagenparameter

typename To Der Typ der angeforderten Schnittstelle.

Parameter

to Ein Verweis auf einen Wert, der die angeforderte Schnittstelle empfängt.

Rückgabewert

Eine com_ptr, die auf die angeforderte Schnittstelle verweist, oder einen stark typierten intelligenten Zeiger für die angeforderte Schnittstelle (entweder von C++/WinRT oder von einem Drittanbieter deklariert), wenn die angeforderte Schnittstelle unterstützt wird, andernfalls nullptr (die auto-returning overload) oder false (die bool-returning overload).

com_ptr::try_capture-Funktion

Eine Version von com_ptr::capture, die beim Fehler nicht ausgelöst wird, sondern gibt stattdessen true zurück, wenn dies erfolgreich ist oder false.

Siehe auch die winrt::try_capture Funktionsvorlage.

com_ptr::operator bool

Überprüft, ob der intelligente Zeiger auf eine Schnittstelle oder ein Objekt verweist. Wenn der intelligente Zeiger nicht auf eine Schnittstelle oder ein Objekt verweist, ist er logisch NULL; andernfalls ist sie logisch nicht NULL.

Syntax

explicit operator bool() const noexcept;

Rückgabewert

true, wenn der intelligente Zeiger auf eine Schnittstelle oder ein Objekt verweist (logisch nicht null), andernfalls false (logisch Null).

com_ptr::operator* (Dereferenzierungsoperator)

Gibt einen Verweis auf das Ziel des com_ptrzurück, sodass Sie ihn an eine Funktion übergeben können, die einen Verweis auf den Zieltyp erwartet, T.

Syntax

T& operator*() const noexcept;

Rückgabewert

Ein Verweis auf das Ziel des com_ptr.

com_ptr::operator= (Zuordnungsoperator)

Weist dem com_ptr -Objekt einen Wert zu.

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;

Vorlagenparameter

typename U Der Typ, auf den der zugewiesene Wert verweist.

Parameter

other Ein com_ptr Wert, der dem com_ptr-Objekt zugewiesen werden soll. Der T- des Parameters muss in den T-des com_ptr Objekts konvertierbar sein.

Rückgabewert

Ein Verweis auf das com_ptr-Objekt.

com_ptr::operator-> (Pfeiloperator)

Gibt den zugrunde liegenden unformatierten Zeiger zurück, um zugriff auf die Methoden der referenzierten Schnittstelle oder des Objekts zu gewähren. Sie dürfen weder AddRef noch Release für den zurückgegebenen Zeiger aufrufen, sie können jedoch QueryInterface-aufrufen.

Syntax

auto operator->() const noexcept;

Rückgabewert

Ein Zeiger auf die Schnittstelle oder das Objekt, auf die vom com_ptr-Objekt verwiesen wird.

attach_abi-Funktion

Fügt ein com_ptr -Objekt an einen unformatierten Zeiger an, der einen Verweis auf sein Ziel besitzt; Ein zusätzlicher Verweis wird nicht hinzugefügt. Bei Bedarf können Sie diese Funktion verwenden, um Bezüge zu klammern.

Syntax

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

Parameter

object Ein com_ptr objekt, das ausgeführt werden soll.

value Ein unformatierter Zeiger, der einen Verweis auf sein Ziel besitzt.

detach_abi-Funktion

Trennt ein com_ptr -Objekt von der unformatierten Schnittstelle, ohne die Verweisanzahl zu erhöhen, vielleicht um es an einen Aufrufer zurückzugeben.

Syntax

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

Parameter

object Ein com_ptr objekt, das ausgeführt werden soll.

Rückgabewert

Ein Zeiger auf die unformatierte Schnittstelle, auf die vom com_ptr-Objekt verwiesen wird.

operator!= (Ungleichheitsoperator)

Gibt einen Wert zurück, der angibt, ob die beiden Parameter auf unterschiedliche Ziele verweisen.

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;

Parameter

left right Einen com_ptr Wert, dessen Speicheradresse mit dem des anderen Parameters verglichen werden soll.

Rückgabewert

true, wenn die beiden Parameter auf unterschiedliche Ziele verweisen, andernfalls false.

Operator< (Kleiner-als-Operator)

Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters früher im Arbeitsspeicher als der des zweiten Parameters auftritt.

Syntax

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

Parameter

left right Einen com_ptr Wert, dessen Speicheradresse mit dem des anderen Parameters verglichen werden soll.

Rückgabewert

true, wenn die Speicheradresse des ersten Parameters kleiner als der zweite Parameter ist, andernfalls false.

operator<= (kleiner-als-oder-gleich-operator)

Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters früher im Arbeitsspeicher als oder an derselben Position wie der zweite Parameter auftritt.

Syntax

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

Parameter

left right Einen com_ptr Wert, dessen Speicheradresse mit dem des anderen Parameters verglichen werden soll.

Rückgabewert

true, wenn die Speicheradresse des ersten Parameters kleiner oder gleich dem des zweiten Parameters ist, andernfalls false.

operator== (Gleichheitsoperator)

Gibt einen Wert zurück, der angibt, ob die beiden Parameter auf dieselbe Schnittstelle und/oder ein Objekt verweisen.

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;

Parameter

left right Einen com_ptr Wert, dessen Speicheradresse mit dem des anderen Parameters verglichen werden soll.

Rückgabewert

true, wenn die beiden Parameter auf dasselbe Ziel zeigen, andernfalls false.

operator> (größer-als-Operator)

Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters später im Arbeitsspeicher als der des zweiten Parameters auftritt.

Syntax

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

Parameter

left right Einen com_ptr Wert, dessen Speicheradresse mit dem des anderen Parameters verglichen werden soll.

Rückgabewert

true, wenn die Speicheradresse des ersten Parameters größer als die des zweiten Parameters ist, andernfalls false.

Operator>= (operator größer als oder gleich)

Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters später im Arbeitsspeicher auftritt als oder an derselben Position wie die des zweiten Parameters.

Syntax

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

Parameter

left right Einen com_ptr Wert, dessen Speicheradresse mit dem des anderen Parameters verglichen werden soll.

Rückgabewert

true, wenn die Speicheradresse des ersten Parameters größer oder gleich dem des zweiten Parameters ist, andernfalls false.

Swap-Funktion

Tauscht den Inhalt der beiden com_ptr Parameter so, dass sie auf das Ziel eines anderen zeigen.

Syntax

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

Parameter

left right Ein com_ptr Wert, dessen Zeiger sich gegenseitig mit dem des anderen Parameters austauschen.

Siehe auch