winrt：：com_ptr结构模板（C++/WinRT）
引用计数的 COM 智能指针模板。 com_ptr 表示指向模板参数指定的接口或运行时类实现类型的指针。 它通过专用原始指针自动管理其目标的引用计数。
语法
template <typename T>
struct com_ptr
模板参数
typename T 接口或运行时类实现类型，指针由 com_ptr表示。 这是智能指针的目标类型。
要求
受支持的最低 SDK： Windows SDK 版本 10.0.17134.0 （Windows 10 版本 1803）
Namespace： 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 void的指针;此函数可帮助你调用通过指向 void指针的指针返回作为 out 参数的引用的方法（如 COM 方法）。 |
| com_ptr：：try_as 函数 | 如果支持请求的接口，则返回请求的接口。 如果不是，则返回 nullptr或 false。 |
| com_ptr：：try_capture 函数 |
com_ptr：：capture 的版本不会在失败时引发，但如果失败，则返回 true，否则返回 false。 |
成员运算符
| 算子 | 描述 |
|---|---|
| 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 对象从其原始接口中分离，而不递减引用计数，可能将其返回到调用方。 |
| 交换函数 | 交换两个 com_ptr 参数的内容，以便它们指向彼此的目标。 |
免费运算符
| 功能 | 描述 |
|---|---|
| 运算符！= （不等运算符） | 返回一个值，该值指示这两个参数是否引用不同的目标。 |
| 运算符<（小于运算符） | 返回一个值，该值指示第一个参数的目标是否早于内存中的第二个参数的目标。 |
| 运算符<= | 返回一个值，该值指示第一个参数的目标是在内存中早于第二个参数的目标，还是在与第二个参数相同的位置发生。 |
| 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 函数对象类型，例如自由函数，或 std：：function。
typename O 接口类型。
typename M 方法类型。
typename Args 零个或多个参数类型。
参数
function 类型为 F的函数对象。
p 指向 O类型的对象的指针。
object 类型 O的 winrt：：com_ptr。
method 类型 M的 A 方法（由 O实现）。
args 类型 Args的零个或多个参数。
言论
-
capture(F function, Args&&...args)重载调用函数对象。 -
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 函数
返回基础原始指针的地址;此函数可帮助你调用通过指向指针的指针以 out 参数的形式返回引用的方法（如 COM 方法）。 如果 com_ptr 对象已有目标，则在调用此函数之前将 nullptr 分配给 com_ptr 对象，否则该函数将断言。
语法
T** put() noexcept;
返回值
基础原始指针的地址。
com_ptr：:p ut_void 函数
返回基础原始指针的地址，作为指向指向 void void的指针;此函数可帮助你调用通过指向 void指针的指针返回作为 out 参数的引用的方法（如 COM 方法）。 如果 com_ptr 对象已有目标，则在调用此函数之前将 nullptr 分配给 com_ptr 对象，否则该函数将断言。
语法
void** put_void() noexcept;
返回值
基础原始指针的地址，作为指向指向 void的指针。
com_ptr：：try_as 函数
如果支持请求的接口，则返回请求的接口。 如果不是，则返回 nullptr（auto-returning overload）或 false（bool-returning overload）。 如果要查询不需要传回调用方接口，则此函数非常有用。
语法
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 overload）或 false（bool-returning overload）。
com_ptr：：try_capture 函数
com_ptr：：capture 的版本不会在失败时引发，但如果失败，则返回 true，否则返回 false。
另请参阅 winrt：：try_capture 函数模板。
com_ptr：：operator bool
检查智能指针是否引用接口或对象。 如果智能指针未引用接口或对象，则其逻辑为 null;否则，逻辑上不为 null。
语法
explicit operator bool() const noexcept;
返回值
如果智能指针引用接口或对象（逻辑上不为 null），则 true 否则 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 否则 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。
运算符<= （小于或等于运算符）
返回一个值，该值指示第一个参数的目标是在内存中早于第二个参数的目标，还是在与第二个参数相同的位置发生。
语法
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。
运算符>（大于运算符）
返回一个值，该值指示第一个参数的目标在内存中是否晚于第二个参数的目标。
语法
template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
参数
left
right 一个 com_ptr 值，其目标内存地址与其他参数的内存地址进行比较。
返回值
如果第一个参数的目标内存地址大于第二个参数的内存地址，则 true 否则 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。
swap 函数
交换两个 com_ptr 参数的内容，以便它们指向彼此的目标。
语法
void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;
参数
left
right 一个 com_ptr 值，其指向与其他参数的相互交换的指针。
另请参阅
- winrt 命名空间
- 通过 C++/WinRT 使用 API