Partilhar via

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

Um modelo de ponteiro inteligente COM com contagem de referência. com_ptr representa um ponteiro para a interface ou o tipo de implementação da classe de tempo de execução 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 do 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. Este é o tipo de alvo do ponteiro inteligente.

Requerimentos

SDK mínimo suportado: Windows SDK versão 10.0.17134.0 (Windows 10, versão 1803)

Espaço de nomes: winrt

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

Aliases de tipo de membro

Nome alternativo Tipo
com_ptr::type Um sinônimo para uma representação definida pela implementação do typename T parâmetro template.

Construtores

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

Funções de membro

Função Descrição
com_ptr::como função Retorna a interface solicitada, se ela for suportada. Lança se não for.
com_ptr::função anexar Anexa-se a um ponteiro bruto que possui uma referência ao seu destino; não é adicionada uma referência adicional.
com_ptr::função de captura Chama uma função ou método especificado (chamando automaticamente winrt::check_hresult nele) e captura o ponteiro da interface que é saída da função ou método como um void**arquivo .
com_ptr::copy_from função Cópias de outro ponteiro. Diminui a contagem de referência em qualquer interface ou objeto atualmente referenciado, copia o parâmetro de ponteiro bruto e começa a gerenciar o tempo de vida da interface ou objeto apontado por ele.
com_ptr::copy_to função Copia para outro ponteiro do objeto com_ptr . Incrementa a contagem de referência em qualquer interface ou objeto atualmente referenciado e copia o endereço de memória dessa interface ou objeto para o parâmetro.
com_ptr:função :d etach Desanexa da interface ou objeto referenciado sem diminuir a contagem de referências, talvez para devolvê-la a um chamador.
com_ptr::função 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 de saída por meio de um ponteiro para um ponteiro.
com_ptr:função :p ut_void Retorna o endereço do ponteiro bruto subjacente como um ponteiro para um ponteiro para anular; 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 para anular.
com_ptr::try_as função Retorna a interface solicitada, se ela for suportada. Devolve nullptr, ou false, se não for.
com_ptr::try_capture função Uma versão do com_ptr::capture que não lança falhas, mas retorna true retorna se for bem-sucedida ou false não.

Operadores membros

Operador Descrição
com_ptr::operador bool Verifica se o ponteiro inteligente está ou não fazendo referência a uma interface ou objeto.
com_ptr::operador* (operador indirecional) 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::operador-> (operador de seta) Para permitir acesso à interface referenciada ou aos métodos do objeto, 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; não é adicionada uma referência adicional.
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 swap Troca o conteúdo dos dois parâmetros com_ptr para que eles apontem um para o alvo do outro.

Operadores livres

Função Descrição
operador!= (operador de desigualdade) Retorna um valor que indica se os dois parâmetros se referem a destinos diferentes.
operador< (menos que operador) Retorna um valor que indica se o destino do primeiro parâmetro ocorre mais cedo na memória do que o do segundo parâmetro.
operador<= (operador menor que ou igual a) Retorna um valor que indica se o destino do primeiro parâmetro ocorre mais cedo na memória do que o do segundo parâmetro ou no mesmo local que o do segundo parâmetro.
operador== (operador de igualdade) Retorna um valor que indica se os dois parâmetros se referem à mesma interface e/ou objeto.
operador> (maior que operador) 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>= (maior que ou igual a operador) 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 ou no mesmo local que o do segundo parâmetro.

com_ptr::com_ptr construtor

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

O void* construtor pega 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; é apenas dizer 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 do 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 em T do objeto com_ptr.

com_ptr::como função

Retorna a interface solicitada, se ela for suportada. Lança se não for. Esta função é útil se você quiser consultar uma interface que você não precisa passar de volta para o seu 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 do 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 fazendo referência à interface solicitada ou um ponteiro inteligente fortemente tipado para a interface solicitada (declarado por C++/WinRT ou por terceiros).

com_ptr::função anexar

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

Sintaxe

void attach(T* value) noexcept;

Parâmetros

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

com_ptr::função de captura

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

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 do 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) por quaisquer argumentos adicionais fornecidos. Todas as sobrecargas também passam os dois argumentos adicionais que tais invocações exigem — especificamente, um REFIID (o 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);

com_ptr::copy_from função

Cópias de outro ponteiro. Diminui a contagem de referência em qualquer interface ou objeto atualmente referenciado, 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 .

com_ptr::copy_to função

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

Sintaxe

void copy_to(T** other) const noexcept;

Parâmetros

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

com_ptr:função :d etach

Desanexa da interface ou objeto referenciado sem diminuir a contagem de referências, 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 .

com_ptr::função 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 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.

com_ptr:função :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 retornam referências como parâmetros de saída através 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 anular.

com_ptr::try_as função

Retorna a interface solicitada, se ela for suportada. Retorna nullptr (a autosobrecarga -return), ou false (a boolsobrecarga -return), se não for. Esta função é útil se você quiser consultar uma interface que você não precisa passar de volta para o seu chamador.

Sintaxe

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

Parâmetros do 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 fazendo referência à interface solicitada ou um ponteiro inteligente fortemente tipado para a interface solicitada (declarado por C++/WinRT ou por terceiros), se a interface solicitada for suportada, caso contrário nullptr (a autosobrecarga -return) ou false (a boolsobrecarga -return).

com_ptr::try_capture função

Uma versão do com_ptr::capture que não lança falhas, mas retorna true retorna se for bem-sucedida ou false não.

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

com_ptr::operador bool

Verifica se o ponteiro inteligente está ou não fazendo referência a 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 é 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::operador* (operador indirecional)

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

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

Parâmetros

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

Valor de retorno

Uma referência ao objeto com_ptr .

com_ptr::operador-> (operador de seta)

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

Sintaxe

auto operator->() const noexcept;

Valor de retorno

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

attach_abi função

Anexa um objeto com_ptr a um ponteiro bruto que possui uma referência ao seu destino; não é adicionada uma referência adicional. Se necessário, você pode usar essa função para aglutinar 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.

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.

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 .

operador!= (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 de 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< (menos que operador)

Retorna um valor que indica se o destino do primeiro parâmetro ocorre mais cedo 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 de 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 do 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 mais cedo na memória do que o do segundo parâmetro 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 de 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.

operador== (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 de destino deve ser comparado com o do outro parâmetro.

Valor de retorno

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

operador> (maior que operador)

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

operador>= (maior que ou igual a operador)

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 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 de 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 um para o alvo do outro.

Sintaxe

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

Parâmetros

left right Um valor com_ptr cujo ponteiro para trocar mutuamente com o do outro parâmetro.

Ver também

  • Last updated on