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

Um modelo de ponteiro inteligente COM contado por referência. com_ptr representa um ponteiro para o tipo de implementação de classe de interface ou runtime especificado pelo parâmetro template. 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 tipo de implementação de classe de tempo de execução, um ponteiro para o qual é representado pelo com_ptr. Esse é o tipo de destino do ponteiro inteligente.

Requisitos

SDK mínimo suportado: 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

Construtores

Funções de membro

Operadores de membro

Funções gratuitas

Operadores gratuitos

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 recebe 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 transferido para o com_ptr. A contagem de refcount não precisa ser exatamente 1; está apenas 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 para o T do objeto com_ptr.

função com_ptr::as

Retorna a interface solicitada, se houver suporte. Joga 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 de retorno

Um com_ptr que faz referência à interface solicitada ou um ponteiro inteligente fortemente tipado para a interface solicitada (declarado pelo C++/WinRT ou por terceiros).

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. 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.

Observações

• 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) quaisquer 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 da interface ou do objeto para o parâmetro. Essa função permite que você distribua uma referência à mesma interface sem chamar QueryInterface.

Sintaxe

void copy_to(T** other) const noexcept;

Parâmetros

other O endereço de um ponteiro bruto; para o 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 de retorno

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

Função com_ptr::get

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

Sintaxe

T* get() const noexcept;

Valor de retorno

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 a ser passado para uma função que preencherá o valor; essa função ajuda você a chamar métodos (como métodos COM) que retornam referências como parâmetros de saída por meio de um ponteiro para um ponteiro.

Sintaxe

T** put() noexcept;

Valor de retorno

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 para passá-lo para uma função (como métodos COM) que retorna referências como parâmetros de saída por meio de um ponteiro para um ponteiro para void.

Sintaxe

void** put_void() noexcept;

Valor de retorno

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 -return), se não for. 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 de retorno

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

Função com_ptr::try_capture

Uma versão do com_ptr::capture que não gera falha, mas retorna retorna true se for bem-sucedida 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, logicamente não será nulo.

Sintaxe

explicit operator bool() const noexcept;

Valor de retorno

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á-la para uma função que espera uma referência ao tipo de destino T.

Sintaxe

T& operator*() const noexcept;

Valor de retorno

Uma referência ao alvo 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 de retorno

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ê não pode chamar AddRef nem Release no ponteiro retornado, mas pode chamar QueryInterface.

Sintaxe

auto operator->() const noexcept;

Valor de retorno

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 para 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 retorná-lo a um chamador.

Sintaxe

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

Parâmetros

object Um objeto com_ptr para operar.

Valor de retorno

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

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

Valor de retorno

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

Operador< (operador menor)

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

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

Valor de retorno

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

operator<= (operador menor 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

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

Valor de retorno

true se o endereço de memória do alvo 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

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

Valor de retorno

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

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

Valor de retorno

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

operator>= (operador maior 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

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

Valor de retorno

true Se o endereço de memória do alvo 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

left right Um valor com_ptr cujo ponteiro deve ser trocado mutuamente com o do outro parâmetro.

Consulte também

• namespace winrt
• consumir APIs com C++/WinRT