Classe ComPtr

Cria um tipo de ponteiro inteligente que representa a interface especificada pelo parâmetro de modelo. ComPtr mantém automaticamente uma contagem de referência para o ponteiro de interface subjacente e libera a interface quando a contagem de referência alcança zero.

Sintaxe

template <typename T>
class ComPtr;

template<class U>
friend class ComPtr;

Parâmetros

T
A interface que ComPtr representa.

U
Uma classe para a qual a corrente ComPtr é uma amiga. (O modelo que usa esse parâmetro é protegido.)

Comentários

ComPtr<> declara um tipo que representa o ponteiro da interface subjacente. Use ComPtr<> para declarar uma variável e, em seguida, use o operador de acesso de membro de seta (->) para acessar uma função de membro de interface.

Para obter mais informações sobre ponteiros inteligentes, consulte a subseção "Ponteiros Inteligentes COM" do artigo Práticas de codificação COM.

Membros

Typedefs públicos

Nome	Descrição
InterfaceType	Um sinônimo para o tipo especificado pelo parâmetro de modelo T.

Construtores públicos

Nome	Descrição
ComPtr::ComPtr	Inicializa uma nova instância da classe ComPtr. As sobrecargas fornecem construtores padrão, copiar, mover e conversão.
ComPtr::~ComPtr	Desliga uma instância de ComPtr.

Métodos públicos

Nome	Descrição
ComPtr::As	Retorna um objeto ComPtr que representa a interface identificada pelo parâmetro de modelo especificado.
ComPtr::AsIID	Retorna um objeto ComPtr que representa a interface identificada pela ID de interface especificada.
ComPtr::AsWeak	Recupera uma referência fraca ao objeto atual.
ComPtr::Attach	Associa esse ComPtr ao tipo de interface especificado pelo parâmetro de tipo de modelo atual.
ComPtr::CopyTo	Copia a interface atual ou especificada associada a esse ComPtr para o ponteiro de saída especificado.
ComPtr::Detach	Desassocia esse ComPtr da interface que ele representa.
ComPtr::Get	Recupera um ponteiro para a interface associada a esse ComPtr.
ComPtr::GetAddressOf	Recupera o endereço do membro de dados ptr_, que contém um ponteiro para a interface representada por esse ComPtr.
ComPtr::ReleaseAndGetAddressOf	Libera a interface associada a esse ComPtr e recupera o endereço do membro de dados ptr_, que contém um ponteiro para a interface que foi liberada.
ComPtr::Reset	Libera a interface associada a esse ComPtr e retorna a nova contagem de referência.
ComPtr::Swap	Troca a interface gerenciada pelo ComPtr atual com a interface gerenciada pelo ComPtr especificado.

Métodos protegidos

Nome	Descrição
ComPtr::InternalAddRef	Incrementa a contagem de referência da interface associada a esse ComPtr.
ComPtr::InternalRelease	Executa uma operação de versão COM na interface associada a esse ComPtr.

Operadores públicos

Nome	Descrição
ComPtr::operator&	Recupera o endereço do ComPtr atual.
ComPtr::operator->	Recupera o ponteiro para o tipo especificado pelo parâmetro de modelo atual.
ComPtr::operator=	Atribui um valor ao ComPtr atual.
ComPtr::operator==	Indica se dois objetos ComPtr são iguais.
ComPtr::operator!=	Indica se dois objetos ComPtr não são iguais.
ComPtr::operator Microsoft::WRL::Details::BoolType	Indica se um ComPtr está gerenciando o tempo de vida do objeto de uma interface.

Membros de dados protegidos

Nome	Descrição
ComPtr::ptr_	Contém um ponteiro para a interface associada e gerenciado por esse ComPtr.

Hierarquia de herança

ComPtr

Requisitos

Cabeçalho: client.h

Namespace: Microsoft::WRL

ComPtr::~ComPtr

Desliga uma instância de ComPtr.

WRL_NOTHROW ~ComPtr();

ComPtr::As

Retorna um objeto ComPtr que representa a interface identificada pelo parâmetro de modelo especificado.

template<typename U>
HRESULT As(
   _Out_ ComPtr<U>* p
) const;

template<typename U>
HRESULT As(
   _Out_ Details::ComPtrRef<ComPtr<U>> p
) const;

Parâmetros

U
A interface a ser representada pelo parâmetro p.

p
Um objeto ComPtr que representa a interface especificada pelo parâmetro U. O parâmetro p não deve se referir ao objeto ComPtr atual.

Comentários

O primeiro modelo é o formulário que você deve usar em seu código. O segundo modelo é uma especialização interna e auxiliar. Ele dá suporte a recursos de linguagem C++, como a palavra-chave de dedução de tipo auto.

Valor de retorno

S_OK se for bem-sucedido; caso contrário, um HRESULT que indica o erro.

ComPtr::AsIID

Retorna um objeto ComPtr que representa a interface identificada pela ID de interface especificada.

WRL_NOTHROW HRESULT AsIID(
   REFIID riid,
   _Out_ ComPtr<IUnknown>* p
) const;

Parâmetros

riid
Um ID de interface.

p
Se o objeto tiver uma interface cuja ID é igual a riid, um ponteiro duplamente indireto para a interface especificada pelo parâmetro riid. Caso contrário, um ponteiro para IUnknown.

Valor de retorno

S_OK se for bem-sucedido; caso contrário, um HRESULT que indica o erro.

ComPtr::AsWeak

Recupera uma referência fraca ao objeto atual.

HRESULT AsWeak(
   _Out_ WeakRef* pWeakRef
);

Parâmetros

pWeakRef
Quando essa operação for concluída, um ponteiro para um objeto de referência fraco.

Valor de retorno

S_OK se tiver êxito; caso contrário, um HRESULT que indica o erro.

ComPtr::Attach

Associa esse ComPtr ao tipo de interface especificado pelo parâmetro de tipo de modelo atual.

void Attach(
   _In_opt_ InterfaceType* other
);

Parâmetros

other
Um tipo de Interface

ComPtr::ComPtr

Inicializa uma nova instância da classe ComPtr. As sobrecargas fornecem construtores padrão, copiar, mover e conversão.

WRL_NOTHROW ComPtr();

WRL_NOTHROW ComPtr(
   decltype(__nullptr)
);

template<class U>
WRL_NOTHROW ComPtr(
   _In_opt_ U *other
);

WRL_NOTHROW ComPtr(
   const ComPtr& other
);

template<class U>
WRL_NOTHROW ComPtr(
   const ComPtr<U> &other,
   typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

WRL_NOTHROW ComPtr(
   _Inout_ ComPtr &&other
);

template<class U>
WRL_NOTHROW ComPtr(
   _Inout_ ComPtr<U>&& other, typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

Parâmetros

U
O tipo do parâmetro other.

other
Um objeto do tipo U.

Valor de retorno

Comentários

O primeiro construtor é o construtor padrão, que cria implicitamente um objeto vazio. O segundo construtor especifica __nullptr, que cria explicitamente um objeto vazio.

O terceiro construtor cria um objeto do objeto especificado por um ponteiro. Agora, o ComPtr possui a memória apontada e mantém uma contagem de referência para ela.

O quarto e o quinto construtores são construtores de cópia. O quinto construtor copia um objeto se ele for conversível para o tipo atual.

O sexto e o sétimo construtores são construtores de movimentação. O sétimo construtor move um objeto se ele for conversível para o tipo atual.

ComPtr::CopyTo

Copia a interface atual ou especificada associada a esse ComPtr para o ponteiro especificado.

HRESULT CopyTo(
   _Deref_out_ InterfaceType** ptr
);

HRESULT CopyTo(
   REFIID riid,
   _Deref_out_ void** ptr
) const;

template<typename U>
HRESULT CopyTo(
   _Deref_out_ U** ptr
) const;

Parâmetros

U
O nome de um tipo.

ptr
Quando essa operação for concluída, um ponteiro para a interface solicitada.

riid
Um ID de interface.

Valor de retorno

S_OK se tiver êxito; caso contrário, um HRESULT que indica por que a operação implícita QueryInterface falhou.

Comentários

A primeira função retorna uma cópia de um ponteiro para a interface associada a esse ComPtr. Essa função sempre retorna S_OK.

A segunda função executa uma operação QueryInterface na interface associada a esse ComPtr para a interface especificada pelo parâmetro riid.

A terceira função executa uma operação QueryInterface na interface associada a esse ComPtr para a interface subjacente do parâmetro U.

ComPtr::Detach

Desassocia esse objeto ComPtr da interface que ele representa.

T* Detach();

Valor de retorno

Um ponteiro para a interface que foi representada por esse objeto ComPtr.

ComPtr::Get

Recupera um ponteiro para a interface associada a esse ComPtr.

T* Get() const;

Valor de retorno

Um ponteiro para a interface associada a esse ComPtr

ComPtr::GetAddressOf

Recupera o endereço do membro de dados ptr_, que contém um ponteiro para a interface representada por esse ComPtr.

T* const* GetAddressOf() const;
T** GetAddressOf();

Valor de retorno

O endereço de uma variável.

ComPtr::InternalAddRef

Incrementa a contagem de referência da interface associada a esse ComPtr.

void InternalAddRef() const;

Comentários

Esse método é protegido.

ComPtr::InternalRelease

Executa uma operação de versão COM na interface associada a esse ComPtr.

unsigned long InternalRelease();

Comentários

Esse método é protegido.

ComPtr::operator&

Libera a interface associada a esse objeto ComPtr e recupera o endereço do objeto ComPtr.

Details::ComPtrRef<WeakRef> operator&()

const Details::ComPtrRef<const WeakRef> operator&() const

Valor de retorno

Uma referência fraca ao ComPtr atual.

Comentários

A diferença entre esse método e ComPtr::GetAddressOf é que esse método libera uma referência ao ponteiro da interface. Use ComPtr::GetAddressOf quando precisar do endereço do ponteiro da interface, mas não quiser liberar essa interface.

ComPtr::operator->

Recupera o ponteiro para o tipo especificado pelo parâmetro de modelo atual.

WRL_NOTHROW Microsoft::WRL::Details::RemoveIUnknown<InterfaceType>* operator->() const;

Valor de retorno

Ponteiro para o tipo especificado pelo nome do tipo de modelo atual.

Comentários

Essa função auxiliar remove a sobrecarga desnecessária causada pelo uso da macro STDMETHOD. Essa função faz IUnknown tipos private em vez de virtual.

ComPtr::operator=

Atribui um valor ao ComPtr atual.

WRL_NOTHROW ComPtr& operator=(
   decltype(__nullptr)
);
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ T *other
);
template <typename U>
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ U *other
);
WRL_NOTHROW ComPtr& operator=(
   const ComPtr &other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   const ComPtr<U>& other
);
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr &&other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr<U>&& other
);

Parâmetros

U
Uma classe.

other
Uma referência de ponteiro, referência ou rvalue para um tipo ou outro ComPtr.

Valor de retorno

Uma referência ao ComPtr atual.

Comentários

A primeira versão desse operador atribui um valor vazio ao ComPtr atual.

Na segunda versão, se o ponteiro da interface de atribuição não for o mesmo que o ponteiro da interface ComPtr atual, o segundo ponteiro de interface será atribuído ao ComPtr atual.

Na terceira versão, o ponteiro da interface de atribuição é atribuído ao ComPtr atual.

Na quarta versão, se o ponteiro da interface do valor de atribuição não for o mesmo que o ponteiro da interface ComPtr atual, o segundo ponteiro de interface será atribuído ao ComPtr atual.

A quinta versão é um operador de cópia; uma referência a um ComPtr é atribuída ao ComPtr atual.

A sexta versão é um operador de cópia que usa semântica de movimentação; uma referência rvalue a um tipo ComPtr se qualquer tipo for estático e, em seguida, atribuído ao ComPtr atual.

A sétima versão é um operador de cópia que usa semântica de movimentação; uma referência rvalue a um ComPtr de tipo U é convertida em estática e atribuída ao ComPtr atual.

ComPtr::operator==

Indica se dois objetos ComPtr são iguais.

bool operator==(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator==(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator==(
   decltype(__nullptr),
   const ComPtr<T>& a
);

Parâmetros

a
Uma referência a um objeto ComPtr.

b
Uma referência a outro objeto ComPtr.

Valor de retorno

O primeiro operador produz true se o objeto a for igual ao objeto b; caso contrário, false.

O segundo e o terceiro operadores produzem true se o objeto a for igual a nullptr; caso contrário, false.

ComPtr::operator!=

Indica se dois objetos ComPtr não são iguais.

bool operator!=(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator!=(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator!=(
   decltype(__nullptr),
   const ComPtr<T>& a
);

Parâmetros

a
Uma referência a um objeto ComPtr.

b
Uma referência a outro objeto ComPtr.

Valor de retorno

O primeiro operador produz true se o objeto a não for igual ao objeto b; caso contrário, false.

O segundo e o terceiro operadores produzem true se o objeto a não for igual a nullptr; caso contrário, false.

ComPtr::operator Microsoft::WRL::Details::BoolType

Indica se um ComPtr está gerenciando o tempo de vida do objeto de uma interface.

WRL_NOTHROW operator Microsoft::WRL::Details::BoolType() const;

Valor de retorno

Se uma interface estiver associada a esse ComPtr, o endereço do membro de dados BoolStruct::Member; caso contrário, nullptr.

ComPtr::ptr_

Contém um ponteiro para a interface associada e gerenciado por esse ComPtr.

InterfaceType *ptr_;

Comentários

ptr_ é um membro de dados interno protegido.

ComPtr::ReleaseAndGetAddressOf

Libera a interface associada a esse ComPtr e recupera o endereço do membro de dados ptr_, que contém um ponteiro para a interface que foi liberada.

T** ReleaseAndGetAddressOf();

Valor de retorno

O endereço do membro de dados ptr_ desse ComPtr.

ComPtr::Reset

Libera a interface associada a esse ComPtr e retorna a nova contagem de referência.

unsigned long Reset();

Valor de retorno

O número de referências restantes para a interface subjacente, se houver.

ComPtr::Swap

Troca a interface gerenciada pelo ComPtr atual com a interface gerenciada pelo ComPtr especificado.

void Swap(
   _Inout_ ComPtr&& r
);

void Swap(
   _Inout_ ComPtr& r
);

Parâmetros

r
Um ComPtr.