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 中的 AsAsIIDCopyTo 方法的行为发生了变化。 以前,在调用下列任一方法后,可以检查 nullptrWeakRef 确定是否已成功获得强引用,代码如下:

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

要求

标头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

备注

如果参数 UIWeakReference 或不是派生自 IInspectable,则会发出错误。

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

从 Windows 10 SDK 开始,如果无法获得弱引用,此方法不再将 WeakRef 实例设置为 nullptr,因此应避免使用检查 nullptrWeakRef 的错误检查代码。 相反,请检查 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,因此应避免使用检查 nullptrWeakRef 的错误检查代码。 相反,检查 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
指向 IInspectableIWeakReference 的双重非直接指针。

返回值

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

注解

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

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

WeakRef::operator&

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

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

返回值

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

备注

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