Edit

Share via


WeakReference Class

Supports the WRL infrastructure and is not intended to be used directly from your code.

Syntax

class WeakReference;

Remarks

Represents a weak reference that can be used with the Windows Runtime or classic COM. A weak reference represents an object that might or might not be accessible.

A WeakReference object maintains a strong reference, which is a pointer to an object, and a strong reference count, which is the number of copies of the strong reference that have been distributed by the Resolve() method. While the strong reference count is nonzero, the strong reference is valid and the object is accessible. When the strong reference count becomes zero, the strong reference is invalid and the object is inaccessible.

A WeakReference object is typically used to represent an object whose existence is controlled by an external thread or application. For example, construct a WeakReference object from a reference to a file object. While the file is open, the strong reference is valid. But if the file is closed, the strong reference becomes invalid.

The WeakReference methods are thread safe.

Members

Public Constructors

Name Description
WeakReference::WeakReference Initializes a new instance of the WeakReference class.
WeakReference::~WeakReference Deinitializes (destroys) the current instance of the WeakReference class.

Public Methods

Name Description
WeakReference::DecrementStrongReference Decrements the strong reference count of the current WeakReference object.
WeakReference::IncrementStrongReference Increments the strong reference count of the current WeakReference object.
WeakReference::Resolve Sets the specified pointer to the current strong reference value if the strong reference count is nonzero.
WeakReference::SetUnknown Sets the strong reference of the current WeakReference object to the specified interface pointer.

Inheritance Hierarchy

WeakReference

Requirements

Header: implements.h

Namespace: Microsoft::WRL::Details

WeakReference::~WeakReference

Supports the WRL infrastructure and is not intended to be used directly from your code.

virtual ~WeakReference();

Return Value

Remarks

Deinitializes the current instance of the WeakReference class.

WeakReference::DecrementStrongReference

Supports the WRL infrastructure and is not intended to be used directly from your code.

ULONG DecrementStrongReference();

Remarks

Decrements the strong reference count of the current WeakReference object.

When the strong reference count becomes zero, the strong reference is set to nullptr.

Return Value

The decremented strong reference count.

WeakReference::IncrementStrongReference

Supports the WRL infrastructure and is not intended to be used directly from your code.

ULONG IncrementStrongReference();

Return Value

The incremented strong reference count.

Remarks

Increments the strong reference count of the current WeakReference object.

WeakReference::Resolve

Supports the WRL infrastructure and is not intended to be used directly from your code.

STDMETHOD(Resolve)
   (REFIID riid,
   _Deref_out_opt_ IInspectable **ppvObject
);

Parameters

riid
An interface ID.

ppvObject
When this operation completes, a copy of the current strong reference if the strong reference count is nonzero.

Return Value

  • S_OK if this operation is successful and the strong reference count is zero. The ppvObject parameter is set to nullptr.

  • S_OK if this operation is successful and the strong reference count is nonzero. The ppvObject parameter is set to the strong reference.

  • Otherwise, an HRESULT that indicates the reason this operation failed.

Remarks

Sets the specified pointer to the current strong reference value if the strong reference count is nonzero.

WeakReference::SetUnknown

Supports the WRL infrastructure and is not intended to be used directly from your code.

void SetUnknown(
   _In_ IUnknown* unk
);

Parameters

unk
A pointer to the IUnknown interface of an object.

Remarks

Sets the strong reference of the current WeakReference object to the specified interface pointer.

WeakReference::WeakReference

Supports the WRL infrastructure and is not intended to be used directly from your code.

WeakReference();

Remarks

Initializes a new instance of the WeakReference class.

The strong reference pointer for the WeakReference object is initialized to nullptr, and the strong reference count is initialized to 1.