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

Artikel
06/10/2023

Eine intelligente COM-Zeigervorlage mit Verweiszählung. com_ptr stellt einen Zeiger auf die Schnittstelle oder den Laufzeitklassenimplementierungstyp dar, der durch den Vorlagenparameter angegeben wird. Die Verweisanzahl für das Ziel wird automatisch über einen privaten Rohzeiger verwaltet.

Syntax

template <typename T>
struct com_ptr

Vorlagenparameter

typename T Die Schnittstelle oder der Laufzeitklassenimplementierungstyp, ein Zeiger, auf den durch die com_ptr dargestellt wird. Dies ist der Typ des Ziels des intelligenten Zeigers.

Requirements (Anforderungen)

Unterstütztes MINDEST-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	Typ
com_ptr::type	Ein Synonym für eine implementierungsdefinierte Darstellung des `typename T` Vorlagenparameters.

Konstruktoren

Konstruktor	BESCHREIBUNG
com_ptr::com_ptr-Konstruktor	Initialisiert eine neue instance der com_ptr-Struktur, optional mit einer Kopie oder Verschiebung 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 an 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 winrt::check_hresult aufgerufen), und erfasst den Schnittstellenzeiger, der von der Funktion oder Methode ausgegeben wird, als `void**`.
com_ptr::copy_from-Funktion	Kopiert aus einem anderen Zeiger. Verringert die Verweisanzahl 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 das bzw. das diese verweist.
com_ptr::copy_to-Funktion	Kopiert aus dem com_ptr-Objekt in einen anderen Zeiger. Erhöht die Verweisanzahl für alle derzeit referenzierten Schnittstellen oder Objekte und kopiert die Speicheradresse dieser Schnittstelle oder des Objekts in den Parameter.
com_ptr::d etach-Funktion	Trennt von der Referenzschnittstelle oder dem Objekt, auf die verwiesen wird, ohne die Verweisanzahl zu verringern, z. B. 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 Rohzeigers zurück. Mit dieser Funktion können Sie Methoden (z. B. COM-Methoden) aufrufen, die Verweise als Out-Parameter über einen Zeiger auf einen Zeiger zurückgeben.
com_ptr::p ut_void-Funktion	Gibt die Adresse des zugrunde liegenden Rohzeigers als Zeiger auf einen Zeiger auf void zurück. Diese Funktion unterstützt Sie beim Aufrufen von Methoden (z. B. COM-Methoden), die Verweise als Out-Parameter über einen Zeiger auf einen Zeiger auf void zurückgeben.
com_ptr::try_as-Funktion	Gibt die angeforderte Schnittstelle zurück, wenn sie unterstützt wird. Gibt `nullptr`zurück, oder `false`, wenn dies nicht der Wert ist.
com_ptr::try_capture-Funktion	Eine Version von com_ptr::capture , die nicht bei einem Fehler ausgelöst wird, sondern stattdessen zurückgegeben wird `true` , wenn erfolgreich oder `false` nicht.

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_ptr zurück, damit Sie ihn an eine Funktion übergeben können, die einen Verweis auf den Zieltyp T erwartet.
com_ptr::operator= (Zuweisungsoperator)	Weist dem com_ptr-Objekt einen Wert zu.
com_ptr::operator-> (Pfeiloperator)	Um Zugriff auf die referenzierte Schnittstelle oder die Methoden des Objekts zu gewähren, gibt den zugrunde liegenden Rohzeiger zurück.

Kostenlose Funktionen

Funktion	BESCHREIBUNG
attach_abi-Funktion	Fügt ein com_ptr -Objekt an einen Unformatierten Zeiger an, der einen Verweis auf das Ziel besitzt; ein zusätzlicher Verweis wird nicht hinzugefügt.
detach_abi-Funktion	Trennt ein com_ptr -Objekt von seiner rohen Schnittstelle, ohne die Verweisanzahl zu verringern, z. B. um es an einen Aufrufer zurückzugeben.
swap-Funktion	Wechselt den Inhalt der beiden com_ptr Parameter, sodass sie auf das Ziel des anderen zeigen.

Kostenlose Operatoren

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 vorkommt als das des zweiten Parameters.
operator<= (kleiner-als-oder-gleich-Operator)	Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters früher im Arbeitsspeicher auftritt als oder am selben Speicherort wie der zweite Parameter.
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 auftritt als das des zweiten Parameters.
operator>= (größer-als-oder-gleich-operator)	Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters später im Arbeitsspeicher oder an der gleichen Stelle wie der zweite Parameter auftritt.

com_ptr::com_ptr-Konstruktor

Initialisiert eine neue instance der com_ptr-Struktur, optional mit einer Kopie oder Verschiebung der Eingabedaten.

Der void* Konstruktor nimmt ein T* an und übernimmt den Besitz. winrt::take_ownership_from_abi_t ist ein Markertyp, der explizit die Verantwortung für die Freigabe dieses Zeigers an die com_ptr. Die Refcount muss nicht genau 1 sein; es heißt nur, dass 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 intelligente Zeiger der Eingabe zeigt.

Parameter

other Ein weiterer com_ptr , der das com_ptr -Objekt initialisiert. Das T des Parameters muss in das T des com_ptr -Objekts konvertiert werden.

com_ptr::as-Funktion

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 Ihren Aufrufer zurückgeben müssen.

Codebeispiele finden Sie im Abschnitt Instanziieren und Zurückgeben von projizierten Typen und Schnittstellen sowie in anderen Abschnitten 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 empfangen soll.

Rückgabewert

com_ptr::attach-Funktion

Fügt 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 zum Zusammenfügen von Verweisen verwenden.

Syntax

void attach(T* value) noexcept;

Parameter

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

com_ptr::capture-Funktion

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

Weitere Informationen finden Sie auch in der Funktionsvorlage 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);

Vorlagenparameter

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

typename O Ein Schnittstellentyp.

typename M Ein Methodentyp.

typename Args Null oder mehr Argumenttypen.

Parameter

function Ein Funktionsobjekt vom Typ F.

p Ein Zeiger auf ein Objekt vom Typ O.

objectWinrt::com_ptr vom Typ O.

method Eine Methode (implementiert von O) vom Typ M.

args Null oder mehr Argumente vom Typ Args.

Hinweise

Die capture(F function, Args&&...args) Überladung ruft das Funktionsobjekt auf.
Die capture(O* p, M method, Args&& ...args) -Überladung ruft die -Methode für den 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 übergeben (an den Aufrufer) alle zusätzlichen Argumente, die Sie angeben. Alle Überladungen übergeben auch die beiden zusätzlichen Argumente, die für solche Aufrufe erforderlich sind– insbesondere eine REFIID (die ID des Ziels des winrt::com_ptr) und eine void** (Die Adresse eines Zeigers auf das Ziel von winrt::com_ptr).

Beispiel

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

com_ptr::copy_from-Funktion

Kopiert aus einem anderen Zeiger. Verringert die Verweisanzahl 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 das bzw. das diese verweist.

Syntax

void copy_from(T* other) noexcept;

Parameter

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

com_ptr::copy_to-Funktion

Kopiert aus dem com_ptr-Objekt in einen anderen Zeiger. Erhöht die Verweisanzahl für alle derzeit 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 aufzurufen.

Syntax

void copy_to(T** other) const noexcept;

Parameter

other Eine unformatierte Zeigeradresse; in den der Zeiger auf das Ziel des com_ptr Objekts kopiert werden soll.

com_ptr::d etach-Funktion

Trennt von der Referenzschnittstelle oder dem Objekt, auf die verwiesen wird, ohne die Verweisanzahl zu verringern, z. B. 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 Rohzeigers zurück. Mit dieser Funktion können Sie Methoden (z. B. COM-Methoden) aufrufen, die Verweise als Out-Parameter über einen Zeiger auf einen Zeiger zurückgeben. Wenn das com_ptr -Objekt bereits über ein Ziel verfügt, weisen Sie nullptr dem com_ptr-Objekt zu, bevor Sie diese Funktion aufrufen. Andernfalls wird die Funktion bestätigt.

Syntax

T** put() noexcept;

Rückgabewert

Die Adresse des zugrunde liegenden Rohzeigers.

com_ptr::p ut_void-Funktion

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

Syntax

void** put_void() noexcept;

Rückgabewert

Die Adresse des zugrunde liegenden Rohzeigers 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 zurück (die auto-rückgabende Überladung) oder false (die bool-returning-Überladung), falls nicht. Diese Funktion ist nützlich, wenn Sie eine Schnittstelle abfragen möchten, die Sie nicht an Ihren Aufrufer zurückgeben 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 empfangen soll.

Rückgabewert

Ein com_ptr , der auf die angeforderte Schnittstelle verweist, oder ein stark typisierter intelligenter 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-rückgabende Überladung) oder false (die bool-rückgabende Überladung).

com_ptr::try_capture-Funktion

Eine Version von com_ptr::capture , die nicht bei einem Fehler ausgelöst wird, sondern stattdessen zurückgegeben wird true , wenn erfolgreich oder false nicht.

Siehe auch die Funktionsvorlage winrt::try_capture.

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 er 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_ptr zurück, damit Sie ihn an eine Funktion übergeben können, die einen Verweis auf den Zieltyp T erwartet.

Syntax

T& operator*() const noexcept;

Rückgabewert

Ein Verweis auf das Ziel des com_ptr.

com_ptr::operator= (Zuweisungsoperator)

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-Parameter muss in den T des com_ptr-Objekts konvertiert werden.

Rückgabewert

Ein Verweis auf das com_ptr-Objekt .

com_ptr::operator-> (Pfeiloperator)

Um Zugriff auf die Schnittstelle oder die Methoden des Objekts zu gewähren, gibt den zugrunde liegenden Rohzeiger zurück. Sie dürfen weder AddRef noch Release für den zurückgegebenen Zeiger aufrufen, aber Sie können QueryInterface aufrufen.

Syntax

auto operator->() const noexcept;

Rückgabewert

Ein Zeiger auf die Schnittstelle oder das Objekt, auf das das com_ptr-Objekt verweist.

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 zum Zusammenfügen von Verweisen verwenden.

Syntax

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

Parameter

object Ein com_ptr Objekt, mit dem ausgeführt werden soll.

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

detach_abi-Funktion

Trennt ein com_ptr-Objekt von seiner unformatierten Schnittstelle, ohne die Verweisanzahl zu verringern, z. B. um es an einen Aufrufer zurückzugeben.

Syntax

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

Parameter

object Ein com_ptr Objekt, mit dem ausgeführt werden soll.

Rückgabewert

Ein Zeiger auf die unformatierte Schnittstelle, auf die das com_ptr-Objekt verweist.

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

leftright Ein com_ptr Wert, dessen Speicheradresse des Ziels mit der 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 vorkommt als das des zweiten Parameters.

Syntax

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

Parameter

leftright Ein com_ptr Wert, dessen Speicheradresse des Ziels mit der des anderen Parameters verglichen werden soll.

Rückgabewert

true , wenn die Speicheradresse des ziels des ersten Parameters kleiner als die des zweiten Parameters 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 oder am selben Speicherort wie 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

leftright Ein com_ptr Wert, dessen Speicheradresse des Ziels mit der des anderen Parameters verglichen werden soll.

Rückgabewert

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

operator== (Gleichheitsoperator)

Gibt einen Wert zurück, der angibt, ob die beiden Parameter auf dieselbe Schnittstelle und/oder dasselbe 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

leftright Ein com_ptr Wert, dessen Speicheradresse des Ziels mit der des anderen Parameters verglichen werden soll.

Rückgabewert

true , wenn die beiden Parameter auf dasselbe Ziel verweisen, 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 das des zweiten Parameters auftritt.

Syntax

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

Parameter

leftright Ein com_ptr Wert, dessen Speicheradresse des Ziels mit der 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>= (größer als-oder-gleich-operator)

Gibt einen Wert zurück, der angibt, ob das Ziel des ersten Parameters später im Arbeitsspeicher oder an der gleichen Stelle 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

leftright Ein com_ptr Wert, dessen Speicheradresse des Ziels mit der des anderen Parameters verglichen werden soll.

Rückgabewert

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

swap-Funktion

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

Syntax

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

Parameter

leftright Ein com_ptr Wert, dessen Zeiger wechselseitig mit dem des anderen Parameters ausgetauscht werden soll.