ComPtr 类

项目
10/12/2023

创建表示模板参数指定的接口的 智能指针 类型。 ComPtr 会自动维护基础接口指针的引用计数，并在引用计数变为零时发布接口。

语法

template <typename T>
class ComPtr;

template<class U>
friend class ComPtr;

参数

T
ComPtr 表示的接口。

U
当前 ComPtr 为其友元的类。（使用此参数的模板受到保护。）

注解

ComPtr<> 声明表示基础接口指针的类型。使用 ComPtr<> 声明一个变量，然后使用箭头成员访问运算符 (->) 访问接口成员函数。

有关智能指针的详细信息，请参阅 COM 编码实践一文中的“COM 智能指针”部分。

成员

公共 Typedef

名称	描述
`InterfaceType`	`T` 模板参数指定的类型的同义词。

公共构造函数

名称	描述
`ComPtr::ComPtr`	初始化 `ComPtr` 类的新实例。重载提供默认、复制、移动和转换构造函数。
`ComPtr::~ComPtr`	取消初始化 `ComPtr` 的实例。

公共方法

名称	描述
`ComPtr::As`	返回表示由指定模板参数标识的接口的 `ComPtr` 对象。
`ComPtr::AsIID`	返回表示由指定接口 ID 标识的接口的 `ComPtr` 对象。
`ComPtr::AsWeak`	检索对当前对象的弱引用。
`ComPtr::Attach`	将此 `ComPtr` 与由当前模板类型参数指定的接口类型相关联。
`ComPtr::CopyTo`	将与此 `ComPtr` 关联的当前或指定接口复制到指定输出指针。
`ComPtr::Detach`	从此 `ComPtr` 所表示的接口取消关联它。
`ComPtr::Get`	检索指向与此 `ComPtr` 相关联的接口。
`ComPtr::GetAddressOf`	检索 `ptr_` 数据成员的地址，其中包含指向此 `ComPtr` 所表示的接口的指针。
`ComPtr::ReleaseAndGetAddressOf`	释放与此 `ComPtr` 关联的接口，然后检索 `ptr_` 数据成员的地址，其中包含指向已释放接口的指针。
`ComPtr::Reset`	释放与此 `ComPtr` 关联的接口，并返回新的引用计数。
`ComPtr::Swap`	交换由当前 `ComPtr` 托管的接口与由指定 `ComPtr` 托管的接口。

受保护方法

名称	描述
`ComPtr::InternalAddRef`	递增与此 `ComPtr` 关联的接口的引用计数。
`ComPtr::InternalRelease`	对与此 `ComPtr` 关联的接口执行 COM 释放操作。

公共运算符

“属性”	描述
`ComPtr::operator&`	检索当前 `ComPtr` 的地址。
`ComPtr::operator->`	检索指向当前模板参数所指定类型的指针。
`ComPtr::operator=`	为当前 `ComPtr` 赋值。
`ComPtr::operator==`	指示两个 `ComPtr` 对象是否相等。
`ComPtr::operator!=`	指示两个 `ComPtr` 对象是否不相等。
`ComPtr::operator Microsoft::WRL::Details::BoolType`	指示 `ComPtr` 是否管理接口的对象生存期。

受保护的数据成员

名称	描述
`ComPtr::ptr_`	包含指向与此 `ComPtr` 相关联且由其托管的接口。

继承层次结构

ComPtr

要求

标头：client.h

命名空间：Microsoft::WRL

`ComPtr::~ComPtr`

取消初始化 ComPtr 的实例。

WRL_NOTHROW ~ComPtr();

`ComPtr::As`

返回表示由指定模板参数标识的接口的 ComPtr 对象。

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

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

参数

U
要由参数 p 表示的接口。

p
一个 ComPtr 对象，表示由参数 U 指定的接口。参数 p 不得引用当前 ComPtr 对象。

注解

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

返回值

如果成功，则为 S_OK；否则为指示错误的 HRESULT。

`ComPtr::AsIID`

返回表示由指定接口 ID 标识的接口的 ComPtr 对象。

WRL_NOTHROW HRESULT AsIID(
   REFIID riid,
   _Out_ ComPtr<IUnknown>* p
) const;

参数

riid
接口 ID。

p
如果对象具有 ID 等于 riid 的接口，则为指向由 riid 参数指定的接口的双重间接指针。否则，为指向 IUnknown 的指针。

返回值

如果成功，则为 S_OK；否则为指示错误的 HRESULT。

`ComPtr::AsWeak`

检索对当前对象的弱引用。

HRESULT AsWeak(
   _Out_ WeakRef* pWeakRef
);

参数

pWeakRef
此操作完成后，指向弱引用对象的指针。

返回值

如果成功，则为 S_OK；否则为指示错误的 HRESULT。

`ComPtr::Attach`

将此 ComPtr 与由当前模板类型参数指定的接口类型相关联。

void Attach(
   _In_opt_ InterfaceType* other
);

参数

other
接口类型。

`ComPtr::ComPtr`

初始化 ComPtr 类的新实例。重载提供默认、复制、移动和转换构造函数。

WRL_NOTHROW ComPtr();

WRL_NOTHROW ComPtr(
   decltype(__nullptr)
);

template<class U>
WRL_NOTHROW ComPtr(
   _In_opt_ U *other
);

WRL_NOTHROW ComPtr(
   const ComPtr& other
);

template<class U>
WRL_NOTHROW ComPtr(
   const ComPtr<U> &other,
   typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

WRL_NOTHROW ComPtr(
   _Inout_ ComPtr &&other
);

template<class U>
WRL_NOTHROW ComPtr(
   _Inout_ ComPtr<U>&& other, typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

参数

U
other 参数的类型。

other
一个 U 类型的对象。

返回值

注解

第一个构造函数是默认构造函数，该构造函数隐式创建一个空对象。第二个构造函数指定 __nullptr，该构造函数显式创建一个空对象。

第三个构造函数从指针指定的对象创建对象。 ComPtr 现在拥有所指向的内存，并维护它的引用计数。

第四和第五个构造函数是复制构造函数。如果某个对象可转换为当前类型，则第五个构造函数将复制该对象。

第六和第七个构造函数是移动构造函数。如果某个对象可转换为当前类型，则第七个构造函数将移动该对象。

`ComPtr::CopyTo`

将与此 ComPtr 关联的当前或指定接口复制到指定指针。

HRESULT CopyTo(
   _Deref_out_ InterfaceType** ptr
);

HRESULT CopyTo(
   REFIID riid,
   _Deref_out_ void** ptr
) const;

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

参数

U
类型名称。

ptr
此操作完成后，为指向所请求的接口的指针。

riid
接口 ID。

返回值

如果成功，则为 S_OK；否则为一个指示隐式 QueryInterface 操作失败原因的 HRESULT。

注解

第一个函数返回指向与此 ComPtr 关联的接口的指针的副本。此函数始终返回 S_OK。

对于 riid 参数指定的接口，第二个函数对与此 ComPtr 关联的接口执行 QueryInterface 操作。

对于 U 参数的基础接口，第三个函数对与此 ComPtr 关联的接口执行 QueryInterface 操作。

`ComPtr::Detach`

从此 ComPtr 对象所表示的接口取消关联它。

T* Detach();

返回值

指向由此 ComPtr 对象表示的接口的指针。

`ComPtr::Get`

检索指向与此 ComPtr 相关联的接口。

T* Get() const;

返回值

指向与此 ComPtr 相关联的接口。

`ComPtr::GetAddressOf`

检索 ptr_ 数据成员的地址，其中包含指向此 ComPtr 所表示的接口的指针。

T* const* GetAddressOf() const;
T** GetAddressOf();

返回值

变量的地址。

`ComPtr::InternalAddRef`

递增与此 ComPtr 关联的接口的引用计数。

void InternalAddRef() const;

备注

此方法受到保护。

`ComPtr::InternalRelease`

对与此 ComPtr 关联的接口执行 COM 释放操作。

unsigned long InternalRelease();

注解

此方法受到保护。

`ComPtr::operator&`

释放与此 ComPtr 对象关联的接口，然后检索 ComPtr 对象的地址。

Details::ComPtrRef<WeakRef> operator&()

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

返回值

对当前 ComPtr 的弱引用。

备注

此方法不同于 ComPtr::GetAddressOf，因为此方法会释放对接口指针的引用。当需要接口指针的地址但不想释放该接口时，请使用 ComPtr::GetAddressOf。

`ComPtr::operator->`

检索指向当前模板参数所指定类型的指针。

WRL_NOTHROW Microsoft::WRL::Details::RemoveIUnknown<InterfaceType>* operator->() const;

返回值

指向当前模板类型名称所指定类型的指针。

注解

此帮助程序函数消除了使用 STDMETHOD 宏导致的不必要的开销。此函数使 IUnknown 成为 private 而不是 virtual。

`ComPtr::operator=`

为当前 ComPtr 赋值。

WRL_NOTHROW ComPtr& operator=(
   decltype(__nullptr)
);
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ T *other
);
template <typename U>
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ U *other
);
WRL_NOTHROW ComPtr& operator=(
   const ComPtr &other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   const ComPtr<U>& other
);
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr &&other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr<U>&& other
);

参数

U
一个类。

other
指向类型或其他 ComPtr 的指针，或者对它们的引用或 rvalue 引用。

返回值

对当前 ComPtr 的引用。

备注

此运算符的第一个版本将空值分配给当前 ComPtr。

在第二个版本中，如果分配接口指针与当前 ComPtr 接口指针不同，则第二个接口指针将分配给当前 ComPtr。

在第三个版本中，分配接口指针分配给当前 ComPtr。

在第四个版本中，如果分配值的接口指针与当前 ComPtr 接口指针不同，则第二个接口指针将分配给当前 ComPtr。

第五个版本是复制运算符；对 ComPtr 的引用分配给当前 ComPtr。

第六个版本是使用移动语义的复制运算符；对任意类型的 ComPtr 的 rvalue 引用是静态强制转换，然后分配给当前 ComPtr。

第七个版本是使用移动语义的复制运算符；对 U 类型的 ComPtr 的 rvalue 引用是静态强制转换，然后分配给当前 ComPtr。

`ComPtr::operator==`

指示两个 ComPtr 对象是否相等。

bool operator==(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator==(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator==(
   decltype(__nullptr),
   const ComPtr<T>& a
);

参数

a
对 ComPtr 对象的引用。

b
对另一个 ComPtr 对象的引用。

返回值

如果对象 a 等于对象 b，则第一个运算符生成 true；否则生成 false。

如果对象 a 等于 nullptr，则第二个和第三个运算符生成 true；否则生成 false。

`ComPtr::operator!=`

指示两个 ComPtr 对象是否不相等。

bool operator!=(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator!=(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator!=(
   decltype(__nullptr),
   const ComPtr<T>& a
);

参数

a
对 ComPtr 对象的引用。

b
对另一个 ComPtr 对象的引用。

返回值

如果对象 a 不等于对象 b，则第一个运算符生成 true；否则生成 false。

如果对象 a 不等于 nullptr，则第二个和第三个运算符生成 true；否则生成 false。

`ComPtr::operator Microsoft::WRL::Details::BoolType`

指示 ComPtr 是否管理接口的对象生存期。

WRL_NOTHROW operator Microsoft::WRL::Details::BoolType() const;

返回值

如果接口与此 ComPtr 关联，则为 BoolStruct::Member 数据成员的地址；否则为 nullptr。

`ComPtr::ptr_`

包含指向与此 ComPtr 相关联且由其托管的接口。

InterfaceType *ptr_;

备注

ptr_ 是内部的受保护数据成员。

`ComPtr::ReleaseAndGetAddressOf`

释放与此 ComPtr 关联的接口，然后检索 ptr_ 数据成员的地址，其中包含指向已释放接口的指针。

T** ReleaseAndGetAddressOf();

返回值

此 ComPtr 的 ptr_ 数据成员的地址。

`ComPtr::Reset`

释放与此 ComPtr 关联的接口，并返回新的引用计数。

unsigned long Reset();

返回值

基础接口剩余的引用数（如果有）。

`ComPtr::Swap`

交换由当前 ComPtr 托管的接口与由指定 ComPtr 托管的接口。

void Swap(
   _Inout_ ComPtr&& r
);

void Swap(
   _Inout_ ComPtr& r
);

参数

r
一个 ComPtr。

通过

ComPtr 类

语法

参数

注解

成员

公共 Typedef

公共构造函数

公共方法

受保护方法

公共运算符

受保护的数据成员

继承层次结构

要求

ComPtr::~ComPtr

ComPtr::As

参数

注解

返回值

ComPtr::AsIID

参数

返回值

ComPtr::AsWeak

参数

返回值

ComPtr::Attach

参数

ComPtr::ComPtr

参数

返回值

注解

ComPtr::CopyTo

参数

返回值

注解

ComPtr::Detach

返回值

ComPtr::Get

返回值

ComPtr::GetAddressOf

返回值

ComPtr::InternalAddRef

备注

ComPtr::InternalRelease

注解

ComPtr::operator&

返回值

备注

ComPtr::operator->

返回值

注解

ComPtr::operator=

参数

返回值

备注

ComPtr::operator==

参数

返回值

ComPtr::operator!=

参数

返回值

ComPtr::operator Microsoft::WRL::Details::BoolType

返回值

ComPtr::ptr_

备注

ComPtr::ReleaseAndGetAddressOf

返回值

ComPtr::Reset

返回值

ComPtr::Swap

参数

反馈

其他资源