引用计数的 COM 智能指针模板。 com_ptr 表示指向 template 参数指定的接口或运行时类实现类型的指针。 它通过专用原始指针自动管理其目标的引用计数。
语法
template <typename T>
struct com_ptr
模板参数
typename T 接口或运行时类实现类型，指向其的指针由 com_ptr 表示。 这是智能指针的目标类型。
要求
支持的最低 SDK： Windows SDK 版本 10.0.17134.0（Windows 10 版本 1803）
命名空间： winrt
标头： %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h（默认包含）
成员类型别名
| 别名 | 类型 |
|---|---|
| com_ptr：：type | 模板参数的实现定义表示 typename T 形式的同义词。 |
构造 函数
| 构造 函数 | 描述 |
|---|---|
| com_ptr：：com_ptr 构造函数 | 初始化 com_ptr 结构的新实例，可以选择使用输入数据的副本或移动。 |
成员函数
| 功能 | 描述 |
|---|---|
| com_ptr：：as 函数 | 如果支持请求的接口，则返回请求的接口。 如果不是，则引发。 |
| com_ptr：：attach 函数 | 附加到拥有对其目标的引用的原始指针;不会添加其他引用。 |
| com_ptr：：capture 函数 | 调用指定的函数或方法（自动对其调用 winrt：：check_hresult ），并将函数或方法输出的接口指针捕获为 void**. |
| com_ptr：：copy_from 函数 | 从另一个指针复制。 递减当前引用的任何接口或对象的引用计数，复制原始指针参数，并开始管理它指向的接口或对象的生存期。 |
| com_ptr：：copy_to 函数 | 从 com_ptr 对象复制到另一个指针。 递增当前引用的任何接口或对象的引用计数，并将该接口或对象的内存地址复制到参数中。 |
| com_ptr：:d etach 函数 | 从引用的接口或对象中分离，而不递减引用计数，或许可以将其返回到调用方。 |
| com_ptr：：get 函数 | 如果需要将基础原始指针传递给函数，则返回该指针。 |
| com_ptr：:p ut 函数 | 返回基础原始指针的地址;此函数可帮助你调用通过指向指针的指针以 out 参数的形式返回引用的方法（如 COM 方法）。 |
| com_ptr：:p ut_void 函数 | 返回基础原始指针的地址，作为指向 void 的指针的指针;此函数可帮助你调用方法（如 COM 方法），这些方法通过指向 void 的指针将引用作为 OUT 参数返回。 |
| com_ptr：：try_as 函数 | 如果支持请求的接口，则返回请求的接口。 返回 ，否则false返回 nullptr或 。 |
| com_ptr：：try_capture 函数 | 不引发失败但返回成功或false失败的 com_ptr：：capture 版本。true |
成员运算符
| 算子 | 描述 |
|---|---|
| com_ptr：：operator bool | 检查智能指针是否引用接口或对象。 |
| com_ptr：：operator* （间接运算符） | 返回对 com_ptr目标的引用，以便您可以将其传递给需要对目标类型 T 的引用的函数。 |
| com_ptr：：operator= （赋值运算符） | 为 com_ptr 对象分配一个值。 |
| com_ptr：：operator-> （箭头运算符） | 若要能够访问引用的接口或对象的方法，请返回基础原始指针。 |
免费函数
| 功能 | 描述 |
|---|---|
| attach_abi 功能 | 将 com_ptr 对象附加到拥有对其目标的引用的原始指针;不会添加其他引用。 |
| detach_abi 功能 | 将 com_ptr 对象从其原始接口中分离，而不减少引用计数，可能是为了将其返回给调用方。 |
| swap 函数 | 交换两个 com_ptr 参数的内容，以便它们指向彼此的目标。 |
免费运算符
| 功能 | 描述 |
|---|---|
| operator！= （不等运算符） | 返回一个值，该值指示这两个参数是否引用不同的目标。 |
| 运算符< （小于运算符） | 返回一个值，该值指示第一个参数的目标是否早于内存中的第二个参数的目标。 |
| operator<=（小于或等于运算符） | 返回一个值，该值指示第一个参数的目标是在内存中早于第二个参数的目标，还是在与第二个参数相同的位置发生。 |
| operator== （相等运算符） | 返回一个值，该值指示这两个参数是否引用同一接口和/或对象。 |
| 运算符> （greater-than 运算符） | 返回一个值，该值指示第一个参数的目标在内存中是否晚于第二个参数的目标。 |
| operator>=（大于或等于运算符） | 返回一个值，该值指示第一个参数的目标在内存中是晚于第二个参数的目标，还是在与第二个参数相同的位置发生。 |
com_ptr：：com_ptr 构造函数
初始化 com_ptr 结构的新实例，可以选择使用输入数据的副本或移动。
void*构造函数采用 T* 并承担所有权。
winrt：：take_ownership_from_abi_t 是一种标记类型，它明确 表示释放此指针的责任现在正在转移到com_ptr。 refcount 不必完全为 1;只是说责任正在转移。
语法
com_ptr(winrt::com_ptr const& other) noexcept;
com_ptr(std::nullptr_t = nullptr) noexcept;
com_ptr(void* ptr, winrt::take_ownership_from_abi_t) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U> const& other) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U>&& other) noexcept;
模板参数
typename U 输入智能指针指向的目标类型。
参数
other另一个初始化 com_ptr 对象的 com_ptr。 参数的 T 必须可转换为 com_ptr 对象的 T。
com_ptr：：as 函数
如果支持请求的接口，则返回请求的接口。 如果不是，则引发。 如果要查询不需要传回调用方接口，则此函数非常有用。
有关代码示例，请参阅 实例化和返回投影类型和接口部分，以及该主题中的其他部分。
语法
template <typename To> auto as() const;
template <typename To> void as(To& to) const;
模板参数
typename To 请求的接口的类型。
参数
to 对用于接收所请求接口的值的引用。
返回值
引用所请求接口的 com_ptr ，或所请求接口的强类型智能指针（由 C++/WinRT 或第三方声明）。
com_ptr：：attach 函数
附加到拥有对其目标的引用的原始指针;不会添加其他引用。 如果需要，可以使用此函数合并引用。
语法
void attach(T* value) noexcept;
参数
value 拥有对其目标的引用的原始指针。
com_ptr：：capture 函数
调用指定的函数或方法（自动对其调用 winrt：：check_hresult ），并将函数或方法输出的接口指针捕获为 void**.
另请参阅 winrt：：capture 函数模板。
语法
template <typename F, typename...Args>
void capture(F function, Args&&...args);
template <typename O, typename M, typename...Args>
void capture(O* p, M method, Args&& ...args);
template <typename O, typename M, typename...Args>
void capture(winrt::com_ptr<O> const& object, M method, Args&&...args);
模板参数
typename F 函数对象类型，例如 free 函数或 std：：function。
typename O 接口类型。
typename M 方法类型。
typename Args 零个或多个参数类型。
参数
function 类型 F为 的函数对象。
p 指向 类型的 O对象的指针。
object类型为 O的 winrt：：com_ptr 。
method类型M为 的方法（由 O实现）。
args 零个或多个 类型的 Args参数。
言论
-
capture(F function, Args&&...args)重载调用 function 对象。 -
capture(O* p, M method, Args&& ...args)重载调用指针上的方法。 -
capture(winrt::com_ptr<O> const& object, M method, Args&&...args)重载调用对象上的方法。
所有重载都会传递（调用者）提供的任何其他参数。 所有重载还传递此类调用所需的两个附加参数，具体而言， REFIID （ winrt：：com_ptr 目标的 ID）和 void** （指向 winrt：：com_ptr 目标的指针的地址）。
例
winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);
com_ptr：：copy_from 函数
从另一个指针复制。 递减当前引用的任何接口或对象的引用计数，复制原始指针参数，并开始管理它指向的接口或对象的生存期。
语法
void copy_from(T* other) noexcept;
参数
other 指向目标的原始指针，其生存期应由 com_ptr 对象管理。
com_ptr：：copy_to 函数
从 com_ptr 对象复制到另一个指针。 递增当前引用的任何接口或对象的引用计数，并将该接口或对象的内存地址复制到参数中。 此函数允许您在不调用 QueryInterface 的情况下分发对同一接口的引用。
语法
void copy_to(T** other) const noexcept;
参数
other 原始指针的地址;将指针复制到 com_ptr 对象目标的指针中。
com_ptr：:d etach 函数
从引用的接口或对象中分离，而不递减引用计数，或许可以将其返回到调用方。
语法
T* detach() noexcept;
返回值
指向 com_ptr 对象引用的接口或对象的指针。
com_ptr：：get 函数
如果需要将基础原始指针传递给函数，则返回该指针。 可以在返回的指针上调用 AddRef、 Release 或 QueryInterface 。
语法
T* get() const noexcept;
返回值
指向 com_ptr 对象引用的接口或对象的指针。
com_ptr：:p ut 函数
返回要传递给将填充该值的函数的基础原始指针的地址;此函数可帮助您调用方法（如 COM 方法），这些方法通过指向指针的指针将引用作为 OUT 参数返回。
语法
T** put() noexcept;
返回值
基础原始指针的地址。
com_ptr：:p ut_void 函数
将基础原始指针的地址作为指向 void 的指针的指针返回，以将其传递给函数 （，例如 COM 方法） ，该函数通过指向 void 的指针将引用作为 out 参数返回。
语法
void** put_void() noexcept;
返回值
基础原始指针的地址，作为指向 void 的指针的指针。
com_ptr：：try_as 函数
如果支持请求的接口，则返回请求的接口。 返回 nullptr （ auto-returning 重载） 或 false （ bool-returning 重载） （如果不是）。 如果要查询不需要传回调用方接口，则此函数非常有用。
语法
template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;
模板参数
typename To 请求的接口的类型。
参数
to 对用于接收所请求接口的值的引用。
返回值
引用所请求接口的 com_ptr ，或所请求接口的强类型智能指针（由 C++/WinRT 或第三方声明），如果支持的接口受支持，否则 nullptr （ auto-returning 重载）或 false （ bool-returning 重载）。
com_ptr：：try_capture 函数
不引发失败但返回成功或false失败的 com_ptr：：capture 版本。true
另请参阅 winrt：：try_capture 函数模板。
com_ptr：：operator bool
检查智能指针是否引用接口或对象。 如果智能指针未引用接口或对象，则其逻辑为 null;否则，逻辑上不为 null。
语法
explicit operator bool() const noexcept;
返回值
true 如果智能指针引用接口或对象（逻辑上不为 null），否则 false （逻辑上为 null）。
com_ptr：：operator* （间接运算符）
返回对 com_ptr目标的引用，以便您可以将其传递给需要对目标类型 T 的引用的函数。
语法
T& operator*() const noexcept;
返回值
对 com_ptr目标的引用。
com_ptr：：operator= （赋值运算符）
为 com_ptr 对象分配一个值。
语法
winrt::com_ptr& operator=(winrt::com_ptr const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U> const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U>&& other) noexcept;
模板参数
typename U 所分配的值所指向的类型。
参数
other 要分配给 com_ptr 对象的 com_ptr 值。 参数的 T 必须可转换为 com_ptr 对象的 T。
返回值
对 com_ptr 对象的引用。
com_ptr：：operator-> （箭头运算符）
若要能够访问引用的接口或对象的方法，请返回基础原始指针。 不能对返回的指针调用 AddRef 或 Release ，但可以调用 QueryInterface。
语法
auto operator->() const noexcept;
返回值
指向 com_ptr 对象引用的接口或对象的指针。
attach_abi 函数
将 com_ptr 对象附加到拥有对其目标的引用的原始指针;不会添加其他引用。 如果需要，可以使用此函数合并引用。
语法
void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;
参数
object 要作的 com_ptr 对象。
value 拥有对其目标的引用的原始指针。
detach_abi函数
将 com_ptr 对象从其原始接口中分离，而不减少引用计数，可能是为了将其返回给调用方。
语法
auto detach_abi(winrt::com_ptr<T>& object) noexcept;
参数
object 要作的 com_ptr 对象。
返回值
指向 com_ptr 对象引用的原始接口的指针。
operator！= （不等运算符）
返回一个值，该值指示这两个参数是否引用不同的目标。
语法
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator!=(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
参数
left
right 一个 com_ptr 值，其目标的内存地址要与其他参数的内存地址进行比较。
返回值
true 如果两个参数指向不同的 target，则 false.
运算符< （小于运算符）
返回一个值，该值指示第一个参数的目标是否早于内存中的第二个参数的目标。
语法
template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
参数
left
right 一个 com_ptr 值，其目标的内存地址要与其他参数的内存地址进行比较。
返回值
true 如果第一个参数的目标的内存地址小于第二个参数的内存地址，否则 false.
operator<=（小于或等于运算符）
返回一个值，该值指示第一个参数的目标是在内存中早于第二个参数的目标，还是在与第二个参数相同的位置发生。
语法
template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
参数
left
right 一个 com_ptr 值，其目标的内存地址要与其他参数的内存地址进行比较。
返回值
true 如果第一个参数的目标的内存地址小于或等于第二个参数的内存地址，否则 false.
operator== （相等运算符）
返回一个值，该值指示这两个参数是否引用同一接口和/或对象。
语法
template <typename T> bool operator==(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator==(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
参数
left
right 一个 com_ptr 值，其目标的内存地址要与其他参数的内存地址进行比较。
返回值
true 如果两个参数指向同一个目标，则为 false。
运算符> （greater-than 运算符）
返回一个值，该值指示第一个参数的目标在内存中是否晚于第二个参数的目标。
语法
template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
参数
left
right 一个 com_ptr 值，其目标的内存地址要与其他参数的内存地址进行比较。
返回值
true 如果第一个参数的目标的内存地址大于第二个参数的内存地址，否则 false.
operator>=（大于或等于运算符）
返回一个值，该值指示第一个参数的目标在内存中是晚于第二个参数的目标，还是在与第二个参数相同的位置发生。
语法
template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
参数
left
right 一个 com_ptr 值，其目标的内存地址要与其他参数的内存地址进行比较。
返回值
true 如果第一个参数的目标的内存地址大于或等于第二个参数的内存地址，否则 false.
swap 函数
交换两个 com_ptr 参数的内容，以便它们指向彼此的目标。
语法
void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;
参数
left
right 一个 com_ptr 值，其指针与另一个参数的指针相互交换。