Clase WeakRef

Representa una referencia débil que solo puede usar Windows en tiempo de ejecución, no COM clásico. Una referencia débil representa un objeto que puede ser o no accesible.

Sintaxis

class WeakRef : public ComPtr<IWeakReference>;

Miembros

Constructores públicos

Nombre	Descripción
WeakRef::WeakRef constructor	Inicializa una nueva instancia de la clase WeakRef.
WeakRef::~WeakRef destructor	Desinicializa la instancia actual de la clase WeakRef.

Métodos públicos

Nombre	Descripción
WeakRef::As	Establece el parámetro de puntero ComPtr especificado para representar la interfaz especificada.
WeakRef::AsIID	Establece el parámetro de puntero ComPtr especificado para representar el identificador de interfaz especificado.
WeakRef::CopyTo	Asigna un puntero a una interfaz, si está disponible, para la variable de puntero especificada.

Operadores públicos

Nombre	Descripción
WeakRef::operator&	Devuelve un objeto ComPtrRef que representa el objeto WeakRef actual.

Comentarios

Un objeto WeakRef mantiene una referencia segura, asociada a un objeto, y puede ser o no válida. Llame al método As() o AsIID() para obtener una referencia segura. Cuando la referencia segura se válida, puede obtener acceso al objeto asociado. Cuando la referencia segura no es válida (nullptr), el objeto asociado es inaccesible.

Un objeto WeakRef se usa normalmente para representar un objeto cuya existencia se controla mediante una aplicación o un subproceso externo. Por ejemplo, construya un objeto WeakRef a partir de una referencia a un objeto de archivo. Mientras el archivo esté abierto, la referencia segura será válida. Sin embargo, si el archivo está abierto, la referencia segura no será válida.

Hay un cambio de comportamiento en los métodos As, AsIID y CopyTo en el Windows SDK. Anteriormente, después de llamar a cualquiera de estos métodos, podía comprobar WeakRef para nullptr para determinar si se obtuvo correctamente una referencia segura, como en el código siguiente:

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!");
}

El código anterior no funciona al usar el SDK de Windows 10 (o posterior). En su lugar, compruebe el puntero que se pasó para nullptr.

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

Jerarquía de herencia

ComPtr
 └ WeakRef

Requisitos

Encabezadoclient.h:

Espacio de nombres:Microsoft::WRL

Constructor WeakRef::WeakRef

Inicializa una nueva instancia de la clase 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
Puntero, referencia o referencia rvalue a un objeto existente que inicializa el objeto WeakRef actual.

Comentarios

El primer constructor inicializa un objeto WeakRef vacío. El segundo constructor inicializa un objeto WeakRef desde un puntero a la interfaz IWeakReference. El tercer constructor inicializa un objeto WeakRef de una referencia a un objeto ComPtr<IWeakReference>. Los constructores cuarto y quinto inicializan un objeto WeakRef de otro objeto WeakRef.

WeakRef::~WeakRef destructor

Desinicializa la instancia actual de la clase WeakRef.

~WeakRef();

WeakRef::As

Establece el parámetro de puntero ComPtr especificado para representar la interfaz especificada.

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

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

Parámetros

U
Id. de interfaz.

ptr
Cuando se completa esta operación, un objeto que representa el parámetro U.

Valor devuelto

• S_OK si esta operación es correcta; de lo contrario, un HRESULT que indica el motivo del error de la operación y ptr se establece en nullptr.

• S_OK si esta operación es correcta, pero el objeto WeakRef actual ya se ha liberado. El parámetro ptr se establece en nullptr.

• S_OK si esta operación se realiza correctamente, pero el objeto WeakRef actual no se deriva del parámetro U. El parámetro ptr se establece en nullptr.

Comentarios

Se genera un error si el parámetro U es IWeakReference, o no se deriva de IInspectable.

La primera plantilla es el formulario que debe usar en el código. La segunda plantilla es una especialización del asistente interno, que admite características del lenguaje C++, como palabra clave de deducción de tipos auto.

A partir del SDK de Windows 10, este método no establece la instancia de WeakRef en nullptr si no se pudo obtener la referencia débil, por lo que debería evitar el código de comprobación de errores que comprueba WeakRef para nullptr. En su lugar, compruebe ptr para nullptr.

WeakRef::AsIID

Establece el parámetro de puntero ComPtr especificado para representar el identificador de interfaz especificado.

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

Parámetros

riid
Id. de interfaz.

ptr
Cuando se completa esta operación, un objeto que representa el parámetro riid.

Valor devuelto

• S_OK si esta operación es correcta; de lo contrario, un HRESULT que indica el motivo del error de la operación y ptr se establece en nullptr.

• S_OK si esta operación es correcta, pero el objeto WeakRef actual ya se ha liberado. El parámetro ptr se establece en nullptr.

• S_OK si esta operación se realiza correctamente, pero el objeto WeakRef actual no se deriva del parámetro riid. El parámetro ptr se establece en nullptr. (Para más información, vea la sección Comentarios.)

Comentarios

Se genera un error si el parámetro riid no se deriva de IInspectable. Este error sustituye el valor devuelto.

La primera plantilla es el formulario que debe usar en el código. La segunda plantilla (no se muestra aquí, pero se declara en el archivo de encabezado) es una especialización del asistente interno, que admite características del lenguaje C++, como la palabra clave de deducción de tipos auto.

A partir del SDK de Windows 10, este método no establece la instancia de WeakRef en nullptr si no se pudo obtener la referencia débil, por lo que debería evitar el código de comprobación de errores que comprueba WeakRef para nullptr. En su lugar, busque ptr para nullptr.

WeakRef::CopyTo

Asigna un puntero a una interfaz, si está disponible, para la variable de puntero 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
Puntero a una interfaz IInspectable. Se genera un error si U no se deriva de IInspectable.

riid
Id. de interfaz. Se genera un error si riid no se deriva de IWeakReference.

ptr
Puntero indirecto doble a IInspectable o IWeakReference.

Valor devuelto

S_OK si se realiza correctamente; de lo contrario, un HRESULT que describe el error. Para obtener más información, vea Comentarios.

Comentarios

Un valor devuelto de S_OK significa que esta operación se realizó correctamente, pero no indica si la referencia débil se resolvió en una referencia segura. Si se devuelve S_OK, pruebe que ese parámetro ptr es una referencia segura; es decir, el parámetro ptr no es igual a nullptr.

A partir del SDK de Windows 10, este método no establece la instancia de WeakRef en nullptr si no se pudo obtener la referencia débil, por lo que debería evitar el código de comprobación de errores que comprueba WeakRef para nullptr. En su lugar, busque ptr para nullptr.

WeakRef::operator&

Devuelve un objeto ComPtrRef que representa el objeto WeakRef actual.

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

Valor devuelto

Objeto ComPtrRef que representa el objeto WeakRef actual.

Comentarios

WeakRef::operator& es un operador auxiliar interno que no está diseñado para usarse en el código.