WeakRef 类

  • 项目

表示只能由 Windows 运行时而不是经典 COM 使用的 弱引用 。 弱引用表示可能可访问或可能不可访问的对象。

语法

class WeakRef : public ComPtr<IWeakReference>;

成员

公共构造函数

名称 描述
WeakRef::WeakRef构造函数 初始化 WeakRef 类的新实例。
WeakRef::~WeakRef 析构函数 取消初始化 WeakRef 类的当前实例。

公共方法

名称 描述
WeakRef::As 设置指定的 ComPtr 指针参数以表示指定的接口。
WeakRef::AsIID 设置指定的 ComPtr 指针参数以表示指定的接口 ID。
WeakRef::CopyTo 如果可用，请为指定的指针变量分配一个指向接口的指针。

公共运算符

“属性” 描述
WeakRef::operator& 返回表示当前 WeakRef 对象的 ComPtrRef 对象。

注解

WeakRef 对象维护与对象相关联的强引用，该引用可以是有效的，也可以是无效的。 调用 As() 或 AsIID() 方法以获取强引用。 如果强引用有效，就可以访问关联的对象。 如果强引用无效 (nullptr)，不可访问关联的对象。

WeakRef 对象通常用于表示由外部线程或应用程序控制其是否存在的对象。 例如，通过文件对象的引用构造 WeakRef 对象。 文件打开时，强引用有效。 但文件关闭时，强引用无效。

Windows SDK 中的 As、AsIID 和 CopyTo 方法的行为发生了变化。 以前，在调用下列任一方法后，可以检查 nullptr 的 WeakRef 确定是否已成功获得强引用，代码如下：

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

使用 Windows 10 SDK（或更高版本）时以上代码无效。 相反，请检查为 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
指向初始化当前 WeakRef 对象的现有对象的指针、引用或右值引用。

备注

第一个构造函数初始化一个空白 WeakRef 对象。 第二个构造函数从一个指向 IWeakReference 接口的指针初始化 WeakRef 对象。 第三个构造函数从一个 ComPtr<IWeakReference> 对象的引用初始化一个 WeakRef 对象。 第四个和第五个构造函数从另一个 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
接口 ID。

ptr
此操作完成后，返回一个表示参数 U 的对象。

返回值

  • 如果此操作成功，则为 S_OK；否则为指示此操作失败原因的错误 HRESULT，并且 ptr 被设置为 nullptr。

  • 如果此操作成功，但已释放当前 WeakRef 对象，则为 S_OK。 参数 ptr 被设置为 nullptr。

  • 如果此操作成功，但当前 WeakRef 对象不是派生自参数 U，则为 S_OK。 参数 ptr 被设置为 nullptr。

备注

如果参数 U 为 IWeakReference 或不是派生自 IInspectable，则会发出错误。

第一个模板是应在代码中使用的表单。 第二个模板是内部专用帮助器；第二个模板支持 auto 类型推导关键字等 C++ 语言功能。

从 Windows 10 SDK 开始，如果无法获得弱引用，此方法不再将 WeakRef 实例设置为 nullptr，因此应避免使用检查 nullptr 的 WeakRef 的错误检查代码。 相反，请检查 ptr 是否为 nullptr。

WeakRef::AsIID

设置指定的 ComPtr 指针参数以表示指定的接口 ID。

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

参数

riid
接口 ID。

ptr
此操作完成后，返回一个表示参数 riid的对象。

返回值

  • 如果此操作成功，则为 S_OK；否则为指示此操作失败原因的错误 HRESULT，并且 ptr 被设置为 nullptr。

  • 如果此操作成功，但已释放当前 WeakRef 对象，则为 S_OK。 参数 ptr 被设置为 nullptr。

  • 如果此操作成功，但当前 WeakRef 对象不是派生自参数 riid，则为 S_OK。 参数 ptr 被设置为 nullptr。 (有关更多信息，请参阅“备注”。)

注解

如果参数 riid 不是派生自 IInspectable，则出现错误。 此错误将取代返回值。

第一个模板是应在代码中使用的表单。 第二个模板（此处未显示，但在头文件中声明）是支持 auto 类型推导关键字等 C++ 语言功能的内部专用帮助器。

从 Windows 10 SDK 开始，如果无法获得弱引用，此方法不再将 WeakRef 实例设置为 nullptr，因此应避免使用检查 nullptr 的 WeakRef 的错误检查代码。 相反，检查 ptr 是否为 nullptr。

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
接口 ID。 如果 riid 不是派生自 IWeakReference，则出现错误。

ptr
指向 IInspectable 或 IWeakReference 的双重非直接指针。

返回值

如果成功，则为 S_OK；否则为描述失败的 HRESULT。 有关更多信息，请参见备注。

注解

返回值 S_OK 表示此操作成功，但并不指示弱引用是否解析为强引用。 如果返回 S_OK，则测试参数 ptr 是否为强引用；即，参数 ptr 不等于 nullptr。

从 Windows 10 SDK 开始，如果无法获得弱引用，此方法不再将 WeakRef 实例设置为 nullptr，因此应避免使用检查 nullptr 的 WeakRef 的错误检查代码。 相反，检查 ptr 是否为 nullptr。

WeakRef::operator&

返回表示当前 WeakRef 对象的 ComPtrRef 对象。

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

返回值

表示当前 WeakRef 对象的 ComPtrRef 对象。

备注

WeakRef::operator& 是一个内部辅助运算符，不打算在你的代码中使用。