winrt::com_ptr 结构模板 (C++/WinRT)

项目
06/10/2023

引用计数的 COM 智能指针模板。 com_ptr 表示指向模板参数指定的接口或运行时类实现类型的指针。它通过专用原始指针自动管理其目标的引用计数。

语法

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 函数	返回基础原始指针的地址;此函数可帮助你调用方法 (例如 COM 方法) ，这些方法通过指向指针的指针以输出参数的形式返回引用。
com_ptr：:p ut_void 函数	返回基础原始指针的地址，作为指向 void 的指针的指针;此函数可帮助调用方法 (例如 COM 方法) ，这些方法通过指向 void 的指针以 out 参数的形式返回引用。
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 对象从其原始接口中分离，而不减少引用计数，也许可以将其返回到调用方。
swap 函数	交换两个 com_ptr 参数的内容，以便它们指向彼此的目标。

免费运算符

函数	说明
operator！= (不相等运算符)	返回一个值，该值指示两个参数是否引用不同的目标。
运算符< (小于运算符)	返回一个值，该值指示第一个参数的目标是否早于第二个参数的目标出现在内存中。
operator<= (小于或等于运算符)	返回一个值，该值指示第一个参数的目标出现在内存中是否早于或与第二个参数的目标位于同一位置。
operator== (相等运算符)	返回一个值，该值指示两个参数是否引用相同的接口和/或对象。
运算符> (大于运算符)	返回一个值，该值指示第一个参数的目标是否晚于第二个参数的目标出现在内存中。
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 输入智能指针指向的目标类型。

parameters

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 请求的接口的类型。

parameters

to 对值以接收请求的接口的引用。

返回值

引用所请求接口 的com_ptr ，或由 C++/WinRT 或第三方) 声明 (请求接口的强类型智能指针。

com_ptr：：attach 函数

附加到拥有对其目标引用的原始指针;不会添加其他引用。如果需要，可以使用此函数来合并引用。

语法

void attach(T* value) noexcept;

parameters

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 零个或多个参数类型。

parameters

function 类型的 F函数对象。

p 指向类型的 O对象的指针。

object类型的 Owinrt：：com_ptr。

method由类型M) 实现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;

parameters

other 指向其生存期应由 com_ptr 对象管理的目标的原始指针。

com_ptr：：copy_to 函数

从 com_ptr 对象复制到另一个指针。递增当前引用的任何接口或对象的引用计数，并将该接口或对象的内存地址复制到参数中。此函数允许你分发对同一接口的引用，而无需调用 QueryInterface。

语法

void copy_to(T** other) const noexcept;

parameters

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 方法) ，这些方法通过指向指针的指针以输出参数的形式返回引用。如果com_ptr对象已有目标，则在调用此函数之前分配给nullptrcom_ptr对象，否则该函数将断言。

语法

T** put() noexcept;

返回值

基础原始指针的地址。

com_ptr：:p ut_void 函数

返回基础原始指针的地址，作为指向 void 的指针的指针;此函数可帮助调用方法 (例如 COM 方法) ，这些方法通过指向 void 的指针以 out 参数的形式返回引用。如果com_ptr对象已有目标，则在调用此函数之前分配给nullptrcom_ptr对象，否则该函数将断言。

语法

void** put_void() noexcept;

返回值

基础原始指针的地址，作为指向 void 的指针的指针。

com_ptr：：try_as 函数

如果支持，则返回请求的接口。 nullptr (auto返回重载) 返回，或者false (bool返回重载) （如果不是）。如果要查询不需要传递回调用方接口，则此函数非常有用。

语法

template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;

模板参数

typename To 请求的接口的类型。

parameters

to 对值以接收请求的接口的引用。

返回值

引用请求的接口 的com_ptr ，或请求的接口的强类型智能指针 (由 C++/WinRT 或第三方) 声明（如果支持请求的接口），否则 nullptr (auto返回重载) ，或 false (bool返回重载) 。

com_ptr：：try_capture 函数

com_ptr：：capture 的版本不会在失败时引发，但如果成功，则返回返回true，false否则返回。

另请参阅 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 所分配的值指向的类型。

parameters

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;

parameters

object 要操作 的com_ptr 对象。

value 拥有对其目标的引用的原始指针。

detach_abi 函数

将 com_ptr 对象从其原始接口中分离，而不减少引用计数，也许可以将其返回到调用方。

语法

auto detach_abi(winrt::com_ptr<T>& object) noexcept;

parameters

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;

parameters

leftright一个 com_ptr值，其目标内存地址要与其他参数的内存地址进行比较。

返回值

true 如果两个参数指向不同的目标，则为 ;否则为 false。

运算符< (小于运算符)

返回一个值，该值指示第一个参数的目标是否早于第二个参数的目标出现在内存中。

语法

template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

parameters

leftright一个 com_ptr值，其目标内存地址要与其他参数的内存地址进行比较。

返回值

true 如果第一个参数的目标内存地址小于第二个参数的内存地址，则为 ;否则为 false。

operator<= (小于或等于运算符)

返回一个值，该值指示第一个参数的目标出现在内存中是否早于或与第二个参数的目标位于同一位置。

语法

template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

parameters

leftright一个 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;

parameters

leftright一个 com_ptr值，其目标内存地址要与其他参数的内存地址进行比较。

返回值

true 如果两个参数指向同一目标，则为 ;否则为 false。

运算符> (大于运算符)

返回一个值，该值指示第一个参数的目标是否晚于第二个参数的目标出现在内存中。

语法

template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

parameters

leftright一个 com_ptr值，其目标内存地址要与其他参数的内存地址进行比较。

返回值

true 如果第一个参数的目标的内存地址大于第二个参数的内存地址，则为 ;否则 false为。

operator>= (大于或等于运算符)

返回一个值，该值指示第一个参数的目标出现在内存中是否晚于第二个参数的目标所在的同一位置。

语法

template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

parameters

leftright一个 com_ptr值，其目标内存地址要与其他参数的内存地址进行比较。

返回值

true 如果第一个参数的目标的内存地址大于或等于第二个参数的内存地址，则为 ;否则为 false。

swap 函数

交换两个 com_ptr 参数的内容，以便它们指向彼此的目标。

语法

void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;

parameters

leftright一个 com_ptr值，其指向的指针与其他参数的指针相互交换。