ComPtr 类

创建表示模板参数指定的接口的 智能指针 类型。 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。