Modelo de struct winrt::com_ptr (C++/WinRT)

Artigo
06/10/2023

Um modelo de ponteiro inteligente COM contado por referência. com_ptr representa um ponteiro para o tipo de implementação de interface ou classe de runtime especificado pelo parâmetro de modelo. Ele gerencia automaticamente a contagem de referência para seu destino por meio de um ponteiro bruto privado.

Sintaxe

template <typename T>
struct com_ptr

Parâmetros de modelo

typename T A interface ou o tipo de implementação de classe de runtime, um ponteiro para o qual é representado pelo com_ptr. Esse é o tipo de destino do ponteiro inteligente.

Requisitos

SDK mínimo com suporte: SDK do Windows versão 10.0.17134.0 (Windows 10, versão 1803)

Namespace: winrt

Cabeçalho: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (incluído por padrão)

Aliases de tipo de membro

Nome do alias	Type
com_ptr::type	Um sinônimo de uma representação definida pela implementação do `typename T` parâmetro de modelo.

Construtores

Construtor	Descrição
Construtor com_ptr::com_ptr	Inicializa uma nova instância do struct com_ptr , opcionalmente com uma cópia ou movimentação dos dados de entrada.

Funções de membro

Função	Descrição
função com_ptr::as	Retorna a interface solicitada, se houver suporte. Lança se não estiver.
Função com_ptr::attach	Anexa a um ponteiro bruto que possui uma referência ao seu destino; uma referência adicional não é adicionada.
Função com_ptr::capture	Chama uma função ou método especificado (chamando automaticamente winrt::check_hresult nele) e captura o ponteiro de interface que é gerado da função ou do método como um `void**`.
Função com_ptr::copy_from	Copia de outro ponteiro. Diminui a contagem de referência em qualquer interface ou objeto referenciado no momento, copia o parâmetro de ponteiro bruto e começa a gerenciar o tempo de vida da interface ou objeto apontado por ele.
Função com_ptr::copy_to	Copia para outro ponteiro do objeto com_ptr . Incrementa a contagem de referência em qualquer interface ou objeto referenciado no momento e copia esse endereço de memória da interface ou do objeto para o parâmetro .
Função com_ptr::d etach	Desanexa da interface ou objeto referenciado sem diminuir a contagem de referência, talvez para retorná-la a um chamador.
Função com_ptr::get	Retorna o ponteiro bruto subjacente caso você precise passá-lo para uma função.
Função com_ptr::p ut	Retorna o endereço do ponteiro bruto subjacente; essa função ajuda você a chamar métodos (como métodos COM) que retornam referências como parâmetros out por meio de um ponteiro para um ponteiro.
Função com_ptr::p ut_void	Retorna o endereço do ponteiro bruto subjacente como um ponteiro para um ponteiro para void; essa função ajuda você a chamar métodos (como métodos COM) que retornam referências como parâmetros out por meio de um ponteiro para um ponteiro para void.
Função com_ptr::try_as	Retorna a interface solicitada, se houver suporte. Retornará `nullptr`ou `false`, se não for.
Função com_ptr::try_capture	Uma versão de com_ptr::capture que não é lançada em caso de falha, mas retorna `true` se bem-sucedida ou `false` não.

Operadores membro

Operador	Descrição
com_ptr::operator bool	Verifica se o ponteiro inteligente está ou não fazendo referência a uma interface ou objeto.
com_ptr::operator* (operador de indireção)	Retorna uma referência ao destino do com_ptr para que você possa passá-lo para uma função que espera uma referência ao tipo de destino T.
com_ptr::operator= (operador de atribuição)	Atribui um valor ao objeto com_ptr .
com_ptr::operator-> (operador de seta)	Para permitir o acesso aos métodos de interface ou objeto referenciados, retorna o ponteiro bruto subjacente.

Funções gratuitas

Função	Descrição
função attach_abi	Anexa um objeto com_ptr a um ponteiro bruto que possui uma referência ao seu destino; uma referência adicional não é adicionada.
função detach_abi	Desanexa um objeto com_ptr de sua interface bruta sem diminuir a contagem de referência, talvez para retorná-lo a um chamador.
Função swap	Troca o conteúdo dos dois parâmetros com_ptr para que eles apontem um para o destino do outro.

Operadores gratuitos

Função	Descrição
operator!= (operador de desigualdade)	Retorna um valor que indica se os dois parâmetros se referem a destinos diferentes.
operador< (operador menor que)	Retorna um valor que indica se o destino do primeiro parâmetro ocorre anteriormente na memória do que o do segundo parâmetro.
operator<= (operador less-than-or-equal-to)	Retorna um valor que indica se o destino do primeiro parâmetro ocorre anteriormente na memória ou no mesmo local que o do segundo parâmetro.
operator== (operador de igualdade)	Retorna um valor que indica se os dois parâmetros se referem à mesma interface e/ou objeto.
operador> (operador maior que)	Retorna um valor que indica se o destino do primeiro parâmetro ocorre mais tarde na memória do que o do segundo parâmetro.
operator>= (operador maior que ou igual a)	Retorna um valor que indica se o destino do primeiro parâmetro ocorre mais tarde na memória ou no mesmo local que o do segundo parâmetro.

Construtor com_ptr::com_ptr

Inicializa uma nova instância do struct com_ptr , opcionalmente com uma cópia ou movimentação dos dados de entrada.

O void* construtor usa um T*e assume a propriedade. winrt::take_ownership_from_abi_t é um tipo de marcador que torna explícita a responsabilidade de liberar esse ponteiro agora está sendo transferida para o com_ptr. O refcount não precisa ser exatamente 1; está dizendo que a responsabilidade está sendo transferida.

Sintaxe

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;

Parâmetros de modelo

typename U O tipo de destino apontado pelo ponteiro inteligente de entrada.

Parâmetros

other Outro com_ptr que inicializa o objeto com_ptr . O T do parâmetro deve ser conversível no T do objeto com_ptr.

Função com_ptr::as

Retorna a interface solicitada, se houver suporte. Lança se não for. Essa função será útil se você quiser consultar uma interface que não precisa passar para o chamador.

Para obter exemplos de código, consulte a seção Instanciando e retornando tipos e interfaces projetados e outras seções nesse tópico.

Sintaxe

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

Parâmetros de modelo

typename To O tipo da interface solicitada.

Parâmetros

to Uma referência a um valor para receber a interface solicitada.

Valor retornado

Um com_ptr referenciando a interface solicitada ou um ponteiro inteligente fortemente tipado para a interface solicitada (declarada por C++/WinRT ou por terceiros).

Função com_ptr::attach

Anexa-se a um ponteiro bruto que possui uma referência ao seu destino; uma referência adicional não é adicionada. Se necessário, você pode usar essa função para unir referências.

Sintaxe

void attach(T* value) noexcept;

Parâmetros

value Um ponteiro bruto que possui uma referência ao seu destino.

Função com_ptr::capture

Chama uma função ou método especificado (chamando automaticamente winrt::check_hresult nele) e captura o ponteiro de interface que é a saída da função ou método como um void**.

Consulte também o modelo de função winrt::capture.

Sintaxe

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

Parâmetros de modelo

typename F Um tipo de objeto de função, como uma função livre ou std::function.

typename O Um tipo de interface.

typename M Um tipo de método.

typename Args Zero ou mais tipos de argumento.

Parâmetros

function Um objeto de função do tipo F.

p Um ponteiro para um objeto do tipo O.

object Um winrt::com_ptr do tipo O.

method Um método (implementado por O) do tipo M.

args Zero ou mais argumentos do tipo Args.

Comentários

A capture(F function, Args&&...args) sobrecarga invoca o objeto de função.
A capture(O* p, M method, Args&& ...args) sobrecarga invoca o método no ponteiro.
A capture(winrt::com_ptr<O> const& object, M method, Args&&...args) sobrecarga invoca o método no objeto .

Todas as sobrecargas passam (para a invocação) todos os argumentos adicionais que você fornecer. Todas as sobrecargas também passam os dois argumentos adicionais que essas invocações exigem, especificamente, um REFIID (a ID do destino do winrt::com_ptr) e um void** (o endereço de um ponteiro para o destino do winrt::com_ptr).

Exemplo

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

Função com_ptr::copy_from

Copia de outro ponteiro. Diminui a contagem de referência em qualquer interface ou objeto referenciado no momento, copia o parâmetro de ponteiro bruto e começa a gerenciar o tempo de vida da interface ou objeto apontado por ele.

Sintaxe

void copy_from(T* other) noexcept;

Parâmetros

other Um ponteiro bruto para um destino cujo tempo de vida deve ser gerenciado pelo objeto com_ptr .

Função com_ptr::copy_to

Copia para outro ponteiro do objeto com_ptr . Incrementa a contagem de referência em qualquer interface ou objeto referenciado no momento e copia o endereço de memória dessa interface ou objeto no parâmetro . Essa função permite distribuir uma referência à mesma interface sem chamar QueryInterface.

Sintaxe

void copy_to(T** other) const noexcept;

Parâmetros

other Um endereço de ponteiro bruto; no qual copiar o ponteiro para o destino do objeto com_ptr.

Função com_ptr::d etach

Desanexa da interface ou objeto referenciado sem diminuir a contagem de referência, talvez para devolvê-la a um chamador.

Sintaxe

T* detach() noexcept;

Valor retornado

Um ponteiro para a interface ou objeto referenciado pelo objeto com_ptr .

Função com_ptr::get

Retorna o ponteiro bruto subjacente caso você precise passá-lo para uma função. Você pode chamar AddRef, Release ou QueryInterface no ponteiro retornado.

Sintaxe

T* get() const noexcept;

Valor retornado

Um ponteiro para a interface ou objeto referenciado pelo objeto com_ptr .

Função com_ptr::p ut

Retorna o endereço do ponteiro bruto subjacente; essa função ajuda você a chamar métodos (como métodos COM) que retornam referências como parâmetros out por meio de um ponteiro para um ponteiro. Se o objeto com_ptr já tiver um destino, atribua nullptr ao objeto com_ptr antes de chamar essa função, caso contrário, a função será declarada.

Sintaxe

T** put() noexcept;

Valor retornado

O endereço do ponteiro bruto subjacente.

Função com_ptr::p ut_void

Retorna o endereço do ponteiro bruto subjacente como um ponteiro para um ponteiro para void; essa função ajuda você a chamar métodos (como métodos COM) que retornam referências como parâmetros out por meio de um ponteiro para um ponteiro para void. Se o objeto com_ptr já tiver um destino, atribua nullptr ao objeto com_ptr antes de chamar essa função, caso contrário, a função será declarada.

Sintaxe

void** put_void() noexcept;

Valor retornado

O endereço do ponteiro bruto subjacente como um ponteiro para um ponteiro para void.

Função com_ptr::try_as

Retorna a interface solicitada, se houver suporte. Retorna nullptr (a autosobrecarga -returning) ou false (a boolsobrecarga -returning), se não estiver. Essa função será útil se você quiser consultar uma interface que não precisa passar para o chamador.

Sintaxe

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

Parâmetros de modelo

typename To O tipo da interface solicitada.

Parâmetros

to Uma referência a um valor para receber a interface solicitada.

Valor retornado

Um com_ptr referenciando a interface solicitada ou um ponteiro inteligente fortemente tipado para a interface solicitada (declarada por C++/WinRT ou por terceiros), se a interface solicitada tiver suporte, caso contrário nullptr (a autosobrecarga -retornando) ou false (a boolsobrecarga -retornando).

Função com_ptr::try_capture

Uma versão de com_ptr::capture que não é lançada em caso de falha, mas retorna true se tiver êxito ou false não.

Consulte também o modelo de função winrt::try_capture.

com_ptr::operator bool

Verifica se o ponteiro inteligente está referenciando ou não uma interface ou objeto. Se o ponteiro inteligente não estiver fazendo referência a uma interface ou objeto, ele será logicamente nulo; caso contrário, não será logicamente nulo.

Sintaxe

explicit operator bool() const noexcept;

Valor retornado

true se o ponteiro inteligente estiver fazendo referência a uma interface ou objeto (logicamente não nulo), caso contrário false , (logicamente nulo).

com_ptr::operator* (operador de indireção)

Retorna uma referência ao destino do com_ptr para que você possa passá-lo para uma função que espera uma referência ao tipo de destino T.

Sintaxe

T& operator*() const noexcept;

Valor retornado

Uma referência ao destino do com_ptr.

com_ptr::operator= (operador de atribuição)

Atribui um valor ao objeto com_ptr .

Sintaxe

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;

Parâmetros de modelo

typename U O tipo apontado pelo valor que está sendo atribuído.

Parâmetros

other Um valor com_ptr a ser atribuído ao objeto com_ptr . O T do parâmetro deve ser conversível para o T do objeto com_ptr.

Valor retornado

Uma referência ao objeto com_ptr .

com_ptr::operator-> (operador de seta)

Para permitir o acesso aos métodos de interface ou objeto referenciados, retorna o ponteiro bruto subjacente. Você pode não chamar AddRef nem Release no ponteiro retornado, mas pode chamar QueryInterface.

Sintaxe

auto operator->() const noexcept;

Valor retornado

Um ponteiro para a interface ou objeto referenciado pelo objeto com_ptr .

função attach_abi

Anexa um objeto com_ptr a um ponteiro bruto que possui uma referência ao seu destino; uma referência adicional não é adicionada. Se necessário, você pode usar essa função para unir referências.

Sintaxe

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

Parâmetros

object Um objeto com_ptr no qual operar.

value Um ponteiro bruto que possui uma referência ao seu destino.

função detach_abi

Desanexa um objeto com_ptr de sua interface bruta sem diminuir a contagem de referência, talvez para devolvê-lo a um chamador.

Sintaxe

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

Parâmetros

object Um objeto com_ptr no qual operar.

Valor retornado

Um ponteiro para a interface bruta referenciada pelo objeto com_ptr .

operator!= (operador de desigualdade)

Retorna um valor que indica se os dois parâmetros se referem a destinos diferentes.

Sintaxe

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;

Parâmetros

leftright Um valor com_ptr cujo endereço de memória do destino deve ser comparado com o do outro parâmetro.

Valor retornado

true se os dois parâmetros apontarem para destinos diferentes, caso contrário false, .

operador< (operador menor que)

Retorna um valor que indica se o destino do primeiro parâmetro ocorre anteriormente na memória do que o do segundo parâmetro.

Sintaxe

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

Parâmetros

leftright Um valor com_ptr cujo endereço de memória do destino deve ser comparado com o do outro parâmetro.

Valor retornado

true se o endereço de memória do destino do primeiro parâmetro for menor que o do segundo parâmetro, caso contrário false, .

operator<= (operador menor que ou igual a)

Retorna um valor que indica se o destino do primeiro parâmetro ocorre anteriormente na memória ou no mesmo local que o do segundo parâmetro.

Sintaxe

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

Parâmetros

leftright Um valor com_ptr cujo endereço de memória do destino deve ser comparado com o do outro parâmetro.

Valor retornado

true se o endereço de memória do destino do primeiro parâmetro for menor ou igual ao do segundo parâmetro, caso contrário false, .

operator== (operador de igualdade)

Retorna um valor que indica se os dois parâmetros se referem à mesma interface e/ou objeto.

Sintaxe

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;

Parâmetros

leftright Um valor com_ptr cujo endereço de memória do destino deve ser comparado com o do outro parâmetro.

Valor retornado

true se os dois parâmetros apontarem para o mesmo destino, caso contrário false, .

operador> (operador maior que)

Retorna um valor que indica se o destino do primeiro parâmetro ocorre mais tarde na memória do que o do segundo parâmetro.

Sintaxe

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

Parâmetros

leftright Um valor com_ptr cujo endereço de memória do destino deve ser comparado com o do outro parâmetro.

Valor retornado

true se o endereço de memória do destino do primeiro parâmetro for maior que o do segundo parâmetro, caso contrário false, .

operator>= (operador maior que ou igual a)

Retorna um valor que indica se o destino do primeiro parâmetro ocorre mais tarde na memória ou no mesmo local que o do segundo parâmetro.

Sintaxe

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

Parâmetros

leftright Um valor com_ptr cujo endereço de memória do destino deve ser comparado com o do outro parâmetro.

Valor retornado

true se o endereço de memória do destino do primeiro parâmetro for maior ou igual ao do segundo parâmetro, caso contrário false, .

função swap

Troca o conteúdo dos dois parâmetros com_ptr para que eles apontem para o destino um do outro.

Sintaxe

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

Parâmetros

leftright Um valor com_ptr cujo ponteiro para alternar mutuamente com o do outro parâmetro.