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

  • Artigo

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 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 Tipo
com_ptr::type Um sinônimo para uma representação definida pela implementação do parâmetro de modelo typename T.

Construtores

Construtor Descrição
do 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
com_ptr::as de função Retorna a interface solicitada, se houver suporte. Joga se não for.
de 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.
de função com_ptr::capture Chama uma função ou método especificado (chamando automaticamente winrt::check_hresult nela) e captura o ponteiro de interface que é saída da função ou método como um void**.
de 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.
de 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.
de 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.
com_ptr::obter de função Retorna o ponteiro bruto subjacente caso seja necessário passá-lo para uma função.
de 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.
de função com_ptr::p ut_void Retorna o endereço do ponteiro bruto subjacente como um ponteiro para um ponteiro para nulo; 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 nulo.
de função com_ptr::try_as Retorna a interface solicitada, se houver suporte. Retornará nullptr, ou false, se não estiver.
de função com_ptr::try_capture Uma versão do com_ptr::capture que não é gerada com falha, mas retorna true se bem-sucedida ou false se não.

Operadores de membro

Operador Descrição
com_ptr::operator bool Verifica se o ponteiro inteligente está referenciando ou não uma interface ou objeto.
com_ptr::operator* (operador de indireção) Retorna uma referência ao destino do com_ptrpara que você possa passá-la 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
attach_abi função Anexa um objeto com_ptr a um ponteiro bruto que possui uma referência ao seu destino; uma referência adicional não é adicionada.
detach_abi função Desanexa um objeto com_ptr de sua interface bruta sem diminuir a contagem de referência, talvez para devolvê-lo a um chamador.
função de troca Troca o conteúdo dos dois parâmetros com_ptr para que eles apontem para o destino um do outro.

Operadores gratuitos

Função Descrição
operador != (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.
operador <= (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.
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.
operador >= (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.

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 construtor void* 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. 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 do parâmetro deve ser conversível para oT 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 retornandode 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 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 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 nela) e captura o ponteiro de interface que é 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 tipo de método A.

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.

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

args Zero ou mais argumentos do tipo Args.

Observações

  • A sobrecarga de capture(F function, Args&&...args) invoca o objeto de função.
  • A sobrecarga de capture(O* p, M method, Args&& ...args) invoca o método no ponteiro.
  • A sobrecarga de capture(winrt::com_ptr<O> const& object, M method, Args&&...args) 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 endereço de um 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 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, de Versão 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; 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 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 nulo; 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 nulo. 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 de retorno

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

Função com_ptr::try_as

Retorna a interface solicitada, se houver suporte. Retorna nullptr (a sobrecarga de retorno de auto) ou false (a sobrecarga bool-retornando), 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 de retorno

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 sobrecarga de retorno de auto) ou false (a sobrecarga de retorno de bool).

Função com_ptr::try_capture

Uma versão do com_ptr::capture que não é gerada com falha, mas retorna true se bem-sucedida ou false se 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_ptrpara 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 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 do parâmetro deve ser conversível para oT 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. Talvez você não chame AddRef nem de Versão 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 devolvê-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 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

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 destino do primeiro parâmetro for menor que o do segundo parâmetro, caso contrário, false.

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

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

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 destino do primeiro parâmetro for maior que o do segundo parâmetro, caso contrário, false.

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

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

left right um valor com_ptr cujo ponteiro será alternado mutuamente com o do outro parâmetro.

Consulte também