Partilhar via

Classe WeakRef

  • Artigo

Representa uma referência fraca que pode ser usada apenas pelo Windows Runtime, não pelo COM clássico. Uma referência fraca representa um objeto que pode ou não estar acessível.

Sintaxe

class WeakRef : public ComPtr<IWeakReference>;

Membros

Construtores públicos

Nome Descrição
WeakRef::WeakRef constructor Inicializa uma nova instância da classe WeakRef.
WeakRef::~WeakRef destructor Desinicializa a instância atual da classe WeakRef.

Métodos públicos

Nome Descrição
WeakRef::As Define o parâmetro de ponteiro ComPtr especificado para representar a interface especificada.
WeakRef::AsIID Define o parâmetro de ponteiro ComPtr especificado para representar a ID da interface especificada.
WeakRef::CopyTo Atribui um ponteiro a uma interface, se disponível, à variável de ponteiro especificada.

Operadores públicos

Nome Descrição
WeakRef::operator& Retorna um objeto ComPtrRef que representa o objeto WeakRef atual.

Comentários

Um objeto WeakRef mantém uma referência forte, que está associada a um objeto, e pode ser válida ou inválida. Chame o método As() ou AsIID() o método para obter uma referência forte. Quando a referência forte é válida, ela pode acessar o objeto associado. Quando a referência forte é inválida (nullptr), o objeto associado fica inacessível.

Um objeto WeakRef normalmente é usado para representar um objeto cuja existência é controlada por um thread ou aplicativo externo. Por exemplo, construa um objeto WeakRef a partir de uma referência a um objeto de arquivo. Enquanto o arquivo está aberto, a referência forte é válida. Mas se o arquivo for fechado, a referência forte se tornará inválida.

Há uma mudança de comportamento nos métodos As, AsIID e CopyTo no SDK do Windows. Anteriormente, após chamar qualquer um desses métodos, você poderia verificar o WeakRef para nullptr para determinar se uma referência forte foi obtida com sucesso, como no código a seguir:

WeakRef wr;
strongComptrRef.AsWeak(&wr);

// Now suppose that the object strongComPtrRef points to no longer exists
// and the following code tries to get a strong ref from the weak ref:
ComPtr<ISomeInterface> strongRef;
HRESULT hr = wr.As(&strongRef);

// This check won't work with the Windows 10 SDK version of the library.
// Check the input pointer instead.
if(wr == nullptr)
{
    wprintf(L"Couldn't get strong ref!");
}

O código acima não funciona ao usar o SDK do Windows 10 (ou posterior). Em vez disso, verifique o ponteiro que foi passado para nullptr.

if (strongRef == nullptr)
{
    wprintf(L"Couldn't get strong ref!");
}

Hierarquia de herança

ComPtr
 └ WeakRef

Requisitos

Cabeçalho: client.h

Namespace: Microsoft::WRL

Construtor WeakRef::WeakRef

Inicializa uma nova instância da classe WeakRef.

WeakRef();
WeakRef(
   decltype(__nullptr)
);

WeakRef(
   _In_opt_ IWeakReference* ptr
);

WeakRef(
   const ComPtr<IWeakReference>& ptr
);

WeakRef(
   const WeakRef& ptr
);

WeakRef(
   _Inout_ WeakRef&& ptr
);

Parâmetros

ptr
Um ponteiro, referência ou referência rvalue para um objeto existente que inicializa o objeto WeakRef atual.

Comentários

O primeiro construtor inicializa um objeto WeakRef vazio. O segundo construtor inicializa um objeto WeakRef de um ponteiro para a interface IWeakReference. O terceiro construtor inicializa um objeto WeakRef de uma referência a um objeto ComPtr<IWeakReference>. O quarto e o quinto construtores inicializam um objeto WeakRef de outro objeto WeakRef.

WeakRef::~WeakRef destructor

Desinicializa a instância atual da classe WeakRef.

~WeakRef();

WeakRef::As

Define o parâmetro de ponteiro ComPtr especificado para representar a interface especificada.

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

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

Parâmetros

U
Um ID de interface.

ptr
Quando essa operação for concluída, um objeto que representa o parâmetro U.

Valor retornado

  • S_OK se essa operação tiver êxito; caso contrário, um HRESULT que indica o motivo pelo qual a operação falhou, e ptr é definido como nullptr.

  • S_OK se essa operação tiver êxito, mas o objeto WeakRef atual já tiver sido liberado. O parâmetro ptr é definido como nullptr.

  • S_OK se essa operação for bem-sucedida, mas o objeto WeakRef atual não for derivado do parâmetro U. O parâmetro ptr é definido como nullptr.

Comentários

Um erro será emitido se o parâmetro U for IWeakReference, ou não for derivado de IInspectable.

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

A partir do SDK do Windows 10, esse método não define a instância WeakRef como nullptr se a referência fraca não puder ser obtida, portanto, evite o código de verificação de erros que verifica o WeakRef para nullptr. Em vez disso, verifique se há ptr para nullptr.

WeakRef::AsIID

Define o parâmetro de ponteiro ComPtr especificado para representar a ID da interface especificada.

HRESULT AsIID(
   REFIID riid,
   _Out_ ComPtr<IInspectable>* ptr
);

Parâmetros

riid
Um ID de interface.

ptr
Quando essa operação for concluída, um objeto que representa o parâmetro riid.

Valor retornado

  • S_OK se essa operação tiver êxito; caso contrário, um HRESULT que indica o motivo pelo qual a operação falhou, e ptr é definido como nullptr.

  • S_OK se essa operação tiver êxito, mas o objeto WeakRef atual já tiver sido liberado. O parâmetro ptr é definido como nullptr.

  • S_OK se essa operação for bem-sucedida, mas o objeto WeakRef atual não for derivado do parâmetro riid. O parâmetro ptr é definido como nullptr. (Para obter mais informações, confira Comentários.)

Comentários

Um erro será emitido se o parâmetro riid não for derivado de IInspectable. Esse erro substitui o valor retornado.

O primeiro modelo é o formulário que você deve usar em seu código. O segundo modelo (não mostrado aqui, mas declarado no arquivo de cabeçalho) é uma especialização interna do auxiliar que dá suporte a recursos de linguagem C++, como a palavra-chave de dedução de tipo auto.

A partir do SDK do Windows 10, esse método não define a instância WeakRef como nullptr se a referência fraca não puder ser obtida, portanto, evite o código de verificação de erros que verifica o WeakRef para nullptr. Em vez disso, verifique ptr para nullptr.

WeakRef::CopyTo

Atribui um ponteiro a uma interface, se disponível, à variável de ponteiro especificada.

HRESULT CopyTo(
   REFIID riid,
   _Deref_out_ IInspectable** ptr
);

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

HRESULT CopyTo(
   _Deref_out_ IWeakReference** ptr
);

Parâmetros

U
Ponteiro de uma interface IInspectable. Um erro será emitido se U não for derivado de IInspectable.

riid
Um ID de interface. Um erro será emitido se riid não for derivado de IWeakReference.

ptr
Um ponteiro indireto duplamente para IInspectable ou IWeakReference.

Valor retornado

S_OK se tiver êxito; caso contrário, um HRESULT que descreve a falha. Para obter mais informações, consulte Comentários.

Comentários

Um valor retornado de S_OK significa que essa operação teve êxito, mas não indica se a referência fraca foi resolvida para uma referência forte. Se S_OK for retornado, teste se esse parâmetro ptr é uma referência forte; ou seja, o parâmetro ptr não é igual a nullptr.

A partir do SDK do Windows 10, esse método não define a instância WeakRef como nullptr se a referência fraca não puder ser obtida, portanto, evite o código de verificação de erros que verifica o WeakRef para nullptr. Em vez disso, verifique ptr para nullptr.

WeakRef::operator&

Retorna um objeto ComPtrRef que representa o objeto WeakRef atual.

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

Valor retornado

Um objeto ComPtrRef que representa o objeto WeakRef atual.

Comentários

WeakRef::operator& é um operador auxiliar interno que não deve ser usado em seu código.