Modello di struct winrt::com_ptr (C++/WinRT)

Articolo
08/17/2024

Modello di puntatore intelligente COM con conteggio dei riferimenti. com_ptr rappresenta un puntatore al tipo di implementazione dell'interfaccia o della classe di runtime specificato dal parametro del modello. Gestisce automaticamente il conteggio dei riferimenti per la destinazione tramite un puntatore non elaborato privato.

Sintassi

template <typename T>
struct com_ptr

Parametri del modello

typename T Il tipo di implementazione dell'interfaccia o della classe di runtime, un puntatore a cui è rappresentato dall'com_ptr. Questo è il tipo di destinazione del puntatore intelligente.

Fabbisogno

SDK minimo supportato: Windows SDK versione 10.0.17134.0 (Windows 10, versione 1803)

Namespace: winrt

intestazione : %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (incluso per impostazione predefinita)

Alias del tipo di membro

Nome alias	Digitare
com_ptr::type	Sinonimo di una rappresentazione definita dall'implementazione del parametro del modello `typename T`.

Costruttori

Costruttore	Descrizione
del costruttore com_ptr::com_ptr	Inizializza una nuova istanza dello struct com_ptr, facoltativamente con una copia o uno spostamento dei dati di input.

Funzioni membro

Funzione	Descrizione
funzione com_ptr::as	Restituisce l'interfaccia richiesta, se supportata. Genera un'eccezione se non lo è.
funzione com_ptr::attach	Collega a un puntatore non elaborato proprietario di un riferimento alla destinazione; non viene aggiunto un riferimento aggiuntivo.
funzione com_ptr::capture	Chiama una funzione o un metodo specificato (chiamando automaticamente winrt::check_hresult su di esso) e acquisisce il puntatore di interfaccia restituito dalla funzione o dal metodo come `void**`.
com_ptr::copy_from funzione	Copia da un altro puntatore. Decrementa il conteggio dei riferimenti su qualsiasi interfaccia o oggetto a cui si fa riferimento, copia il parametro del puntatore non elaborato e inizia a gestire la durata dell'interfaccia o dell'oggetto a cui punta.
com_ptr::copy_to funzione	Copia in un altro puntatore dall'oggetto com_ptr. Incrementa il conteggio dei riferimenti su qualsiasi interfaccia o oggetto a cui si fa riferimento e copia l'indirizzo di memoria dell'interfaccia o dell'oggetto nel parametro .
com_ptr::d etach	Scollega dall'interfaccia o dall'oggetto a cui si fa riferimento senza decrementare il conteggio dei riferimenti, ad esempio per restituirlo a un chiamante.
com_ptr::get della funzione	Restituisce il puntatore non elaborato sottostante se necessario passarlo a una funzione.
funzione com_ptr::p ut	Restituisce l'indirizzo del puntatore non elaborato sottostante; questa funzione consente di chiamare metodi (ad esempio i metodi COM) che restituiscono riferimenti come parametri out tramite un puntatore a un puntatore.
com_ptr::p ut_void	Restituisce l'indirizzo del puntatore non elaborato sottostante come puntatore a un puntatore a void; questa funzione consente di chiamare metodi (ad esempio i metodi COM) che restituiscono riferimenti come parametri out tramite un puntatore a un puntatore a void.
com_ptr::try_as funzione	Restituisce l'interfaccia richiesta, se supportata. Restituisce `nullptr`o `false`, se non lo è.
com_ptr::try_capture funzione	Una versione di com_ptr::capture che non genera errori, ma restituisce invece `true` se ha esito positivo o `false` in caso contrario.

Operatori membro

Operatore	Descrizione
com_ptr::operator bool	Controlla se il puntatore intelligente fa riferimento a un'interfaccia o a un oggetto.
com_ptr::operator* (operatore di riferimento indiretto)	Restituisce un riferimento alla destinazione del com_ptrin modo che sia possibile passarla a una funzione che prevede un riferimento al tipo di destinazione T.
com_ptr::operator= (operatore di assegnazione)	Assegna un valore all'oggetto com_ptr.
(operatore freccia) com_ptr::operator	Per concedere l'accesso ai metodi dell'interfaccia o dell'oggetto a cui si fa riferimento, restituisce il puntatore non elaborato sottostante.

Funzioni gratuite

Funzione	Descrizione
attach_abi funzione	Collega un oggetto com_ptr a un puntatore non elaborato proprietario di un riferimento alla destinazione; non viene aggiunto un riferimento aggiuntivo.
detach_abi funzione	Scollega un oggetto com_ptr dall'interfaccia non elaborata senza decrementare il conteggio dei riferimenti, ad esempio per restituirlo a un chiamante.
funzione swap	Scambia il contenuto dei due parametri com_ptr in modo che puntino l'uno all'altro.

Operatori gratuiti

Funzione	Descrizione
operator!= (operatore di disuguaglianza)	Restituisce un valore che indica se i due parametri fanno riferimento a destinazioni diverse.
operatore< (operatore minore di)	Restituisce un valore che indica se la destinazione del primo parametro si verifica in precedenza in memoria rispetto a quella del secondo parametro.
operatore<= (operatore minore o uguale a)	Restituisce un valore che indica se la destinazione del primo parametro si verifica prima della memoria o nella stessa posizione del secondo parametro.
operator== (operatore di uguaglianza)	Restituisce un valore che indica se i due parametri fanno riferimento alla stessa interfaccia e/o oggetto.
> dell'operatore (operatore maggiore di)	Restituisce un valore che indica se la destinazione del primo parametro si verifica in un secondo momento in memoria rispetto a quella del secondo parametro.
operatore= (operatore maggiore o uguale a)	Restituisce un valore che indica se la destinazione del primo parametro si verifica in un secondo momento in memoria o nella stessa posizione del secondo parametro.

Costruttore com_ptr::com_ptr

Inizializza una nuova istanza dello struct com_ptr, facoltativamente con una copia o uno spostamento dei dati di input.

Il costruttore void* accetta un valore T*e assume la proprietà. winrt::take_ownership_from_abi_t è un tipo di marcatore che rende esplicito la responsabilità di rilasciare questo puntatore viene ora trasferito al com_ptr. Il refcount non deve essere esattamente 1; sta solo dicendo che la responsabilità viene trasferita.

Sintassi

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;

Parametri del modello

typename U Il tipo di destinazione a cui punta il puntatore intelligente di input.

Parametri

other Un altro com_ptr che inizializza l'oggetto com_ptr. Il T del parametro deve essere convertibile nel Tdell'oggetto com_ptr .

funzione com_ptr::as

Restituisce l'interfaccia richiesta, se supportata. Genera un'eccezione se non lo è. Questa funzione è utile se si vuole eseguire una query per un'interfaccia che non è necessario tornare al chiamante.

Per esempi di codice, vedere la sezione Creazione di istanze e restituzione di interfacce e tipi proiettatie altre sezioni di tale argomento.

Sintassi

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

Parametri del modello

typename To Tipo dell'interfaccia richiesta.

Parametri

to Riferimento a un valore per ricevere l'interfaccia richiesta.

Valore restituito

Un com_ptr che fa riferimento all'interfaccia richiesta o a un puntatore intelligente fortemente tipizzato per l'interfaccia richiesta (dichiarata da C++/WinRT o da terze parti).

funzione com_ptr::attach

Collega a un puntatore non elaborato proprietario di un riferimento alla destinazione; non viene aggiunto un riferimento aggiuntivo. Se necessario, è possibile usare questa funzione per unire i riferimenti.

Sintassi

void attach(T* value) noexcept;

Parametri

value Puntatore non elaborato proprietario di un riferimento alla destinazione.

funzione com_ptr::capture

Chiama una funzione o un metodo specificato (chiamando automaticamente winrt::check_hresult su di esso) e acquisisce il puntatore di interfaccia restituito dalla funzione o dal metodo come void**.

Vedere anche il modello di funzione winrt::capture.

Sintassi

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

Parametri del modello

typename F Tipo di oggetto funzione, ad esempio una funzione libera o std::function.

typename O Tipo di interfaccia.

typename M tipo di metodo A.

typename Args Zero o più tipi di argomento.

Parametri

function Oggetto funzione di tipo F.

p Puntatore a un oggetto di tipo O.

object un winrt::com_ptr di tipo O.

method Metodo A (implementato da O) di tipo M.

args Zero o più argomenti di tipo Args.

Osservazioni

L'overload capture(F function, Args&&...args) richiama l'oggetto funzione.
L'overload capture(O* p, M method, Args&& ...args) richiama il metodo sul puntatore.
L'overload capture(winrt::com_ptr<O> const& object, M method, Args&&...args) richiama il metodo sull'oggetto .

Tutti gli overload passano (all'oggetto invoke) tutti gli argomenti aggiuntivi forniti. Tutti gli overload passano anche i due argomenti aggiuntivi necessari, in particolare un REFIID (ID della destinazione del winrt::com_ptr) e un void** (indirizzo di un puntatore alla destinazione del winrt::com_ptr).

Esempio

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

funzione com_ptr::copy_from

Copia da un altro puntatore. Decrementa il conteggio dei riferimenti su qualsiasi interfaccia o oggetto a cui si fa riferimento, copia il parametro del puntatore non elaborato e inizia a gestire la durata dell'interfaccia o dell'oggetto a cui punta.

Sintassi

void copy_from(T* other) noexcept;

Parametri

other Puntatore non elaborato a una destinazione la cui durata deve essere gestita dall'oggetto com_ptr.

funzione com_ptr::copy_to

Copia in un altro puntatore dall'oggetto com_ptr. Incrementa il conteggio dei riferimenti su qualsiasi interfaccia o oggetto a cui si fa riferimento e copia l'indirizzo di memoria dell'interfaccia o dell'oggetto nel parametro . Questa funzione consente di distribuire un riferimento alla stessa interfaccia senza chiamare QueryInterface.

Sintassi

void copy_to(T** other) const noexcept;

Parametri

other L'indirizzo di un puntatore non elaborato; in cui copiare il puntatore nella destinazione dell'oggetto com_ptr.

funzione com_ptr::d etach

Scollega dall'interfaccia o dall'oggetto a cui si fa riferimento senza decrementare il conteggio dei riferimenti, ad esempio per restituirlo a un chiamante.

Sintassi

T* detach() noexcept;

Valore restituito

Puntatore all'interfaccia o all'oggetto a cui fa riferimento l'oggetto com_ptr.

funzione com_ptr::get

Restituisce il puntatore non elaborato sottostante se necessario passarlo a una funzione. È possibile chiamare AddRef, Releaseo QueryInterface sul puntatore restituito.

Sintassi

T* get() const noexcept;

Valore restituito

Puntatore all'interfaccia o all'oggetto a cui fa riferimento l'oggetto com_ptr.

funzione com_ptr::p ut

Restituisce l'indirizzo del puntatore non elaborato sottostante; questa funzione consente di chiamare metodi (ad esempio i metodi COM) che restituiscono riferimenti come parametri out tramite un puntatore a un puntatore. Se l'oggetto com_ptr ha già una destinazione, assegnare nullptr all'oggetto com_ptr prima di chiamare questa funzione. In caso contrario, la funzione asserisce.

Sintassi

T** put() noexcept;

Valore restituito

Indirizzo del puntatore non elaborato sottostante.

funzione com_ptr::p ut_void

Restituisce l'indirizzo del puntatore non elaborato sottostante come puntatore a un puntatore a void; questa funzione consente di chiamare metodi (ad esempio i metodi COM) che restituiscono riferimenti come parametri out tramite un puntatore a un puntatore a void. Se l'oggetto com_ptr ha già una destinazione, assegnare nullptr all'oggetto com_ptr prima di chiamare questa funzione. In caso contrario, la funzione asserisce.

Sintassi

void** put_void() noexcept;

Valore restituito

Indirizzo del puntatore non elaborato sottostante come puntatore a un puntatore a void.

funzione com_ptr::try_as

Restituisce l'interfaccia richiesta, se supportata. Restituisce nullptr (overload auto-returning) o false (overload bool-returning), in caso contrario. Questa funzione è utile se si vuole eseguire una query per un'interfaccia che non è necessario tornare al chiamante.

Sintassi

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

Parametri del modello

typename To Tipo dell'interfaccia richiesta.

Parametri

to Riferimento a un valore per ricevere l'interfaccia richiesta.

Valore restituito

Un com_ptr che fa riferimento all'interfaccia richiesta o a un puntatore intelligente fortemente tipizzato per l'interfaccia richiesta (dichiarata da C++/WinRT o da terze parti), se l'interfaccia richiesta è supportata, in caso contrario nullptr (overload auto-returning) o false (overload bool-returning).

Funzione com_ptr::try_capture

Una versione di com_ptr::capture che non genera errori, ma restituisce invece true se ha esito positivo o false in caso contrario.

Vedere anche il modello di funzione winrt::try_capture.

com_ptr::operator bool

Controlla se il puntatore intelligente fa riferimento a un'interfaccia o a un oggetto. Se il puntatore intelligente non fa riferimento a un'interfaccia o a un oggetto, è logicamente null; in caso contrario, non è logicamente null.

Sintassi

explicit operator bool() const noexcept;

Valore restituito

true se il puntatore intelligente fa riferimento a un'interfaccia o a un oggetto (logicamente non Null), altrimenti false (logicamente Null).

com_ptr::operator* (operatore di riferimento indiretto)

Restituisce un riferimento alla destinazione del com_ptrin modo che sia possibile passarla a una funzione che prevede un riferimento al tipo di destinazione T.

Sintassi

T& operator*() const noexcept;

Valore restituito

Riferimento alla destinazione del com_ptr.

com_ptr::operator= (operatore di assegnazione)

Assegna un valore all'oggetto com_ptr.

Sintassi

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;

Parametri del modello

typename U Tipo a cui punta il valore assegnato.

Parametri

other Valore com_ptr da assegnare all'oggetto com_ptr. Il T del parametro deve essere convertibile nel Tdell'oggetto com_ptr .

Valore restituito

Riferimento all'oggetto com_ptr.

com_ptr::operator-> (operatore freccia)

Per concedere l'accesso ai metodi dell'interfaccia o dell'oggetto a cui si fa riferimento, restituisce il puntatore non elaborato sottostante. Non è possibile chiamare AddRef né release sul puntatore restituito, ma è possibile chiamare QueryInterface.

Sintassi

auto operator->() const noexcept;

Valore restituito

Puntatore all'interfaccia o all'oggetto a cui fa riferimento l'oggetto com_ptr.

funzione attach_abi

Collega un oggetto com_ptr a un puntatore non elaborato proprietario di un riferimento alla destinazione; non viene aggiunto un riferimento aggiuntivo. Se necessario, è possibile usare questa funzione per unire i riferimenti.

Sintassi

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

Parametri

object Oggetto com_ptr su cui operare.

value Puntatore non elaborato proprietario di un riferimento alla destinazione.

funzione detach_abi

Scollega un oggetto com_ptr dall'interfaccia non elaborata senza decrementare il conteggio dei riferimenti, ad esempio per restituirlo a un chiamante.

Sintassi

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

Parametri

object Oggetto com_ptr su cui operare.

Valore restituito

Puntatore all'interfaccia non elaborata a cui fa riferimento l'oggetto com_ptr.

operator!= (operatore di disuguaglianza)

Restituisce un valore che indica se i due parametri fanno riferimento a destinazioni diverse.

Sintassi

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;

Parametri

left right Valore com_ptr il cui indirizzo di memoria di destinazione deve essere confrontato con quello dell'altro parametro.

Valore restituito

true se i due parametri puntano a destinazioni diverse; in caso contrario, false.

operatore< (operatore minore di)

Restituisce un valore che indica se la destinazione del primo parametro si verifica in precedenza in memoria rispetto a quella del secondo parametro.

Sintassi

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

Parametri

left right Valore com_ptr il cui indirizzo di memoria di destinazione deve essere confrontato con quello dell'altro parametro.

Valore restituito

true se l'indirizzo di memoria della destinazione del primo parametro è minore di quello del secondo parametro; in caso contrario, false.

operator<= (operatore minore o uguale a)

Restituisce un valore che indica se la destinazione del primo parametro si verifica prima della memoria o nella stessa posizione del secondo parametro.

Sintassi

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

Parametri

left right Valore com_ptr il cui indirizzo di memoria di destinazione deve essere confrontato con quello dell'altro parametro.

Valore restituito

true se l'indirizzo di memoria della destinazione del primo parametro è minore o uguale a quello del secondo parametro; in caso contrario, false.

operator== (operatore di uguaglianza)

Restituisce un valore che indica se i due parametri fanno riferimento alla stessa interfaccia e/o oggetto.

Sintassi

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;

Parametri

left right Valore com_ptr il cui indirizzo di memoria di destinazione deve essere confrontato con quello dell'altro parametro.

Valore restituito

true se i due parametri puntano alla stessa destinazione; in caso contrario, false.

operatore> (operatore maggiore di)

Restituisce un valore che indica se la destinazione del primo parametro si verifica in un secondo momento in memoria rispetto a quella del secondo parametro.

Sintassi

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

Parametri

left right Valore com_ptr il cui indirizzo di memoria di destinazione deve essere confrontato con quello dell'altro parametro.

Valore restituito

true se l'indirizzo di memoria della destinazione del primo parametro è maggiore di quello del secondo parametro; in caso contrario, false.

operator>= (operatore maggiore o uguale a)

Restituisce un valore che indica se la destinazione del primo parametro si verifica in un secondo momento in memoria o nella stessa posizione del secondo parametro.

Sintassi

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

Parametri

left right Valore com_ptr il cui indirizzo di memoria di destinazione deve essere confrontato con quello dell'altro parametro.

Valore restituito

true se l'indirizzo di memoria della destinazione del primo parametro è maggiore o uguale a quello del secondo parametro; in caso contrario, false.

funzione swap

Scambia il contenuto dei due parametri com_ptr in modo che puntino l'uno all'altro.

Sintassi

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

Parametri

left right Valore com_ptr il cui puntatore si scambia a vicenda con quello dell'altro parametro.

Vedere anche

spazio dei nomi winrt
Utilizzare API con C++/WinRT

Condividi tramite

Modello di struct winrt::com_ptr (C++/WinRT)

Sintassi

Parametri del modello

Fabbisogno

Alias del tipo di membro

Costruttori

Funzioni membro

Operatori membro

Funzioni gratuite

Operatori gratuiti

Costruttore com_ptr::com_ptr

Sintassi

Parametri del modello

Parametri

funzione com_ptr::as

Sintassi

Parametri del modello

Parametri

Valore restituito

funzione com_ptr::attach

Sintassi

Parametri

funzione com_ptr::capture

Sintassi

Parametri del modello

Parametri

Osservazioni

Esempio

funzione com_ptr::copy_from

Sintassi

Parametri

funzione com_ptr::copy_to

Sintassi

Parametri

funzione com_ptr::d etach

Sintassi

Valore restituito

funzione com_ptr::get

Sintassi

Valore restituito

funzione com_ptr::p ut

Sintassi

Valore restituito

funzione com_ptr::p ut_void

Sintassi

Valore restituito

funzione com_ptr::try_as

Sintassi

Parametri del modello

Parametri

Valore restituito

Funzione com_ptr::try_capture

com_ptr::operator bool

Sintassi

Valore restituito

com_ptr::operator* (operatore di riferimento indiretto)

Sintassi

Valore restituito

com_ptr::operator= (operatore di assegnazione)

Sintassi

Parametri del modello

Parametri

Valore restituito

com_ptr::operator-> (operatore freccia)

Sintassi

Valore restituito

funzione attach_abi

Sintassi

Parametri

funzione detach_abi

Sintassi

Parametri

Valore restituito

operator!= (operatore di disuguaglianza)

Sintassi

Parametri

Valore restituito

operatore< (operatore minore di)

Sintassi