Класс `WeakRef`

Статья
10/12/2023

Представляет собой слабую ссылку , которая может использоваться только в среде выполнения Windows, а не в классической модели COM. Слабая ссылка представляет собой объект, который может быть доступен или недоступен.

Синтаксис

class WeakRef : public ComPtr<IWeakReference>;

Участники

Открытые конструкторы

Имя	Описание
`WeakRef::WeakRef` Конструктор	Инициализирует новый экземпляр класса `WeakRef`.
`WeakRef::~WeakRef` Деструктор	Деинициализирует текущий `WeakRef` экземпляр класса.

Открытые методы

Имя	Описание
`WeakRef::As`	Задает указанный `ComPtr` параметр указателя для представления указанного интерфейса.
`WeakRef::AsIID`	Задает указанный `ComPtr` параметр указателя для представления указанного идентификатора интерфейса.
`WeakRef::CopyTo`	Присваивает указатель на интерфейс (при его наличии) указанной переменной указателя.

Общедоступные операторы

Имя	Описание
`WeakRef::operator&`	`ComPtrRef` Возвращает объект, представляющий текущий `WeakRef` объект.

Замечания

Объект WeakRef поддерживает надежную ссылку, связанную с объектом, и может быть допустимой или недопустимой. As() Вызовите или AsIID() метод для получения строгой ссылки. Когда строгая ссылка допустима, возможно обращение к связанному объекту. Когда строгая ссылка недопустима (nullptr), связанный объект недоступен.

Объект WeakRef обычно используется для представления объекта, существование которого контролируется внешним потоком или приложением. Например, создайте WeakRef объект из ссылки на файловый объект. Пока открыт файл, строгая ссылка является действительной. Но если закрыть файл, строгая ссылка станет недействительной.

В пакете SDK для Windows изменяется AsAsIIDповедение и CopyTo методы. Ранее после вызова любого из этих методов можно проверка WeakRef для nullptr определения успешности получения строгой ссылки, как показано в следующем коде:

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

Приведенный выше код не работает при использовании пакета SDK для Windows 10 (или более поздней версии). Вместо этого проверка указатель, который был передан для nullptr.

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

Иерархия наследования

ComPtr
└ WeakRef

Требования

Заголовок.client.h

Пространство именMicrosoft::WRL:

Конструктор `WeakRef::WeakRef`

Инициализирует новый экземпляр класса WeakRef.

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

WeakRef(
   _In_opt_ IWeakReference* ptr
);

WeakRef(
   const ComPtr<IWeakReference>& ptr
);

WeakRef(
   const WeakRef& ptr
);

WeakRef(
   _Inout_ WeakRef&& ptr
);

Параметры

ptr
Указатель, ссылка или rvalue-ссылка на существующий объект, который инициализирует текущий WeakRef объект.

Замечания

Первый конструктор инициализирует пустой WeakRef объект. Второй конструктор инициализирует WeakRef объект из указателя на IWeakReference интерфейс. Третий конструктор инициализирует WeakRef объект из ссылки на ComPtr<IWeakReference> объект. Четвертые и пятые конструкторы инициализируют WeakRef объект из другого WeakRef объекта.

`WeakRef::~WeakRef` Деструктор

Деинициализирует текущий WeakRef экземпляр класса.

~WeakRef();

`WeakRef::As`

Задает указанный ComPtr параметр указателя для представления указанного интерфейса.

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

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

Параметры

U
Идентификатор интерфейса.

ptr
После завершения этой операции объект, представляющий параметр U.

Возвращаемое значение

S_OK Значение , если эта операция выполнена успешно; в противном случае — HRESULT, указывающее причину сбоя операции и ptr задано значение nullptr.
S_OK Если эта операция выполнена успешно, но текущий WeakRef объект уже выпущен. Параметр ptr устанавливается в значение nullptr.
S_OK Если эта операция выполнена успешно, но текущий WeakRef объект не является производным от параметра U. Параметр ptr устанавливается в значение nullptr.

Замечания

Ошибка возникает, если параметр U имеет IWeakReferenceзначение или не является производным от IInspectable.

Первый шаблон — это форма, которую необходимо использовать в коде. Второй шаблон является внутренней вспомогательной специализацией; он поддерживает функции языка C++, такие как auto вычет типов ключевое слово.

Начиная с пакета SDK для Windows 10 этот метод не задает WeakRef экземплярnullptr, если не удалось получить слабую ссылку, поэтому следует избежать проверка кода ошибки, проверка WeakRef дляnullptr. Вместо этого проверка ptr для nullptr.

`WeakRef::AsIID`

Задает указанный ComPtr параметр указателя для представления указанного идентификатора интерфейса.

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

Параметры

riid
Идентификатор интерфейса.

ptr
Когда эта операция завершается, объект, представляющий параметр riid.

Возвращаемое значение

S_OK Значение , если эта операция выполнена успешно; в противном случае — HRESULT, указывающее причину сбоя операции и ptr задано значение nullptr.
S_OK Если эта операция выполнена успешно, но текущий WeakRef объект уже выпущен. Параметр ptr устанавливается в значение nullptr.
S_OK Если эта операция выполнена успешно, но текущий WeakRef объект не является производным от параметра riid. Параметр ptr устанавливается в значение nullptr. (Дополнительные сведения см. в разделе "Примечания".)

Замечания

Ошибка возникает, если параметр riid не является производным от IInspectable. Эта ошибка заменяет возвращаемое значение.

Первый шаблон — это форма, которую необходимо использовать в коде. Второй шаблон (не показан здесь, но объявленный в файле заголовка) является внутренней вспомогательной специализацией, которая поддерживает функции языка C++, такие как auto вычет типов ключевое слово.

`WeakRef::CopyTo`

Присваивает указатель на интерфейс (при его наличии) указанной переменной указателя.

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

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

HRESULT CopyTo(
   _Deref_out_ IWeakReference** ptr
);

Параметры

U
Указатель IInspectable на интерфейс. Ошибка возникает, если U не является производным от IInspectable.

riid
Идентификатор интерфейса. Ошибка возникает, если riid не является производным от IWeakReference.

ptr
Двойный косвенный указатель на IInspectable или IWeakReference.

Возвращаемое значение

S_OK в случае успешного выполнения; в противном случае — HRESULT, описывающий сбой. Дополнительные сведения см. в разделе Замечания.

Замечания

Возвращаемое значение S_OK означает, что эта операция выполнена успешно, но не указывает, была ли слабая ссылка разрешена в сильную ссылку. Если S_OK возвращается, проверьте, что параметр ptr является строгой ссылкой; то есть параметр ptr не равен nullptr.

Начиная с пакета SDK для Windows 10 этот метод не задает WeakRef экземплярnullptr, если не удалось получить слабую ссылку, поэтому следует избежать ошибок проверка кода, который проверка используется WeakRef для nullptr. Вместо этого проверка ptr для nullptr.

`WeakRef::operator&`

ComPtrRef Возвращает объект, представляющий текущий WeakRef объект.

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

Возвращаемое значение

Объект ComPtrRef , представляющий текущий WeakRef объект.

Замечания

WeakRef::operator& — это внутренний вспомогательный оператор, который не должен использоваться в коде.

Класс `WeakRef`

Синтаксис

Участники

Открытые конструкторы

Открытые методы

Общедоступные операторы

Замечания

Иерархия наследования

Требования

Конструктор `WeakRef::WeakRef`

Параметры

Замечания

`WeakRef::~WeakRef` Деструктор

`WeakRef::As`

Параметры

Возвращаемое значение

Замечания

`WeakRef::AsIID`

Параметры

Возвращаемое значение

Замечания

`WeakRef::CopyTo`

Параметры

Возвращаемое значение

Замечания

`WeakRef::operator&`

Возвращаемое значение

Замечания

Обратная связь

Обратная связь

Дополнительные ресурсы

Класс WeakRef

Синтаксис

Участники

Открытые конструкторы

Открытые методы

Общедоступные операторы

Замечания

Иерархия наследования

Требования

Конструктор WeakRef::WeakRef

Параметры

Замечания

WeakRef::~WeakRef Деструктор

WeakRef::As

Параметры

Возвращаемое значение

Замечания

WeakRef::AsIID

Параметры

Возвращаемое значение

Замечания

WeakRef::CopyTo

Параметры

Возвращаемое значение

Замечания

WeakRef::operator&

Возвращаемое значение

Замечания

Обратная связь

Обратная связь

Дополнительные ресурсы

Класс `WeakRef`

Конструктор `WeakRef::WeakRef`

`WeakRef::~WeakRef` Деструктор

`WeakRef::As`

`WeakRef::AsIID`

`WeakRef::CopyTo`

`WeakRef::operator&`