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

表示通过 COM 任务分配器分配和释放基础缓冲区的 C 样式一致性数据数组，因此该数组的名称。 它通常用于表示由一个组件分配的 C 样式一致性数组，并释放另一个组件。

winrt：：com_array用于向Windows 运行时 API 传递参数。 如果要创作 API，则可能需要构造 winrt：：com_array 才能将投影的数组返回到调用方;作为返回值或通过输出参数。

winrt：：com_array 派生自 winrt：：array_view。 请参阅 winrt：：array_view 结构模板主题，该主题记录了 winrt：：com_array 也可用于 winrt：：com_array 的成员和免费运算符。 但是，请注意基类型 winrt：：array_view (（即非拥有视图或跨度）) 的连续一系列值的语义差异，以及 winrt：：com_array (分配和释放其自己的元素) 。

语法

template <typename T>
struct com_array : winrt::array_view<T>

模板参数

typename T com_array 包含的值 (元素) 的类型。

要求

支持的最低 SDK：Windows SDK 版本 10.0.17134.0 (Windows 10版本 1803)

命名空间： winrt

标头： %WindowsSdkDir%IncludeWindowsTargetPlatformVersion<>\cppwinrt\winrt\base.h (默认包含)

构造函数

构造函数	说明
com_array：：com_array 构造函数	使用输入数据的副本初始化 com_array 结构的新实例，或者未提供任何数据的默认值 T 。

成员函数

函数	说明
com_array：：clear 函数	使 com_array 对象为空。

成员运算符

操作员	说明
com_array：：operator= (赋值运算符)	将值分配给 com_array 对象。

免费函数

函数	说明
detach_abi 函数	将 com_array 对象与其原始值分离，也许要将其返回到调用方。 清除 com_array 。 另请参阅 winrt：:d etach_abi 函数。
put_abi函数	检索 com_array 的地址，以便它可以设置为另一个值。 另请参阅 winrt：:p ut_abi 函数。
swap 函数	交换两 个com_array 参数的内容。

com_array：：com_array 构造函数

使用输入数据的副本初始化 com_array 结构的新实例，或者未提供任何数据的默认值 T 。

语法

构造函数已编号，并在下面 的说明 中进行了进一步说明。

1.  com_array() noexcept;
2.  com_array(uint32_t const count);
3.  com_array(uint32_t const count, T const& value);
4.  template <typename InIt> com_array(InIt first, InIt last);
5.  com_array(std::vector<T> const& vectorValue);
6.  template <size_t N> com_array(std::array<T, N> const& arrayValue);
7.  template <uint32_t N> com_array(T const(&rawArrayValue)[N])
8.  com_array(std::initializer_list<T> initializerListValue);
9.  com_array(void* ptr, uint32_t const count, winrt::take_ownership_from_abi_t) noexcept;
10. com_array(com_array&& comArrayValue) noexcept;

模板参数

typename InIt 一个输入迭代器，它提供输入数据。

size_t Nuint32_t N 输入数据中元素) 的值数 (。

parameters

arrayValue初始化com_array对象的 std：：array 值。

comArrayValue另一个初始化com_array对象的com_array。 构造函数返回后， comArrayValue 将为空。

countcom_array对象的元素计数。

firstlast 一对输入迭代器。 范围 [first， last) 中的值用于初始化 com_array 对象。

initializerListValue 初始化 com_array 对象的初始值设定项列表值。

ptr 指向使用 CoTaskMemAlloc 分配的 N 值的块的指针。 com_array对象获取此内存的所有权。

rawArrayValue 一个 C 样式数组，用于初始化 com_array 对象。

value 要提供给 com_array 对象的每个元素的值。

vectorValue初始化com_array对象的 std：：vector 值。

备注

构造函数在上面的 语法 中编号。

1. 默认构造函数

构造空缓冲区。

2. 容量构造函数;默认值

创建 计数 元素的缓冲区，所有这些元素都是默认构造 的 T 的副本。

这类似于 (，但与) 创建 计数 元素缓冲区不同，每个缓冲区都是默认构造 的 T。

auto players{ winrt::com_array<MediaPlayer>(50) };

MediaPlayer 对象的默认构造函数创建对新媒体播放器对象的引用，其复制构造函数复制引用。 因此，上述代码行创建对同一媒体播放器对象的 50 个引用的数组。 它不会创建 50 个不同的媒体播放器对象的数组。

3. 容量构造函数;显式值

创建 计数 元素的缓冲区，每个元素都是所提供的 值的副本。

winrt::com_array(2, 42) 被解释为尝试使用范围构造函数 (4) 。 但它失败，因为 2 和 42 不是迭代器。 若要将此值解释为具有显式int32_t值的容量构造函数，请使用显式无符号整数作为第一个参数： com_array(2u, 42)

4. 范围构造函数

创建一个缓冲区，该缓冲区是范围的副本 [first， last) 。

显式声明基础类型 T ，如下所示。

auto a{ winrt::com_array<T>(source.begin(), source.end()) };

若要移动范围，而不是复制它，请使用 std：：move_iterator 迭代器适配器。

auto a{ winrt::com_array<T>(std::move_iterator(source.begin()),
                            std::move_iterator(source.end())) };

5. 矢量构造函数

创建一个缓冲区，该缓冲区是 vectorValue 的内容的副本。

6. 数组构造函数

创建一个缓冲区，该缓冲区是 arrayValue 的内容的副本。

7. C 样式数组构造函数

创建一个缓冲区，该缓冲区是 C 样式数组 rawArrayValue 的内容的副本。

8. Initializer-list 构造函数

创建一个缓冲区，该缓冲区是初始值设定项列表 initializerListValue 的内容的副本。

9. ABI 构造函数

获取指定长度的缓冲区的所有权。

此最低级别的构造函数。 如果已通过 CoTaskMemAlloc 分配内存块，并且希望 com_array 承担其责任，请使用它。 若要强调此构造函数的特别要求，最终参数必须是 winrt：：take_ownership_from_abi。

10. 移动构造函数

将资源从同一类型的另一 个com_array 移动，使原始资源保持空。

构造函数 5、6 和 7

副本是获取提供的容器的内容。 可以将范围构造函数 (4) 与 std：：move_iterator 迭代器适配器配合使用，将内容移动到 com_array 而不是复制它们。

com_array：：clear 函数

使 com_array 对象为空。

语法

void clear() noexcept;

detach_abi 函数

将 com_array 对象与其原始值分离，也许要将其返回到调用方。 清除 com_array 。 另请参阅 winrt：:d etach_abi 函数。

语法

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

parameters

object要操作的com_array对象。

返回值

一个包含元素计数的双元素元组，以及 com_array 跨越的连续一系列值。

com_array：：operator= (赋值运算符)

将值分配给 com_array 对象。

语法

com_array& operator=(winrt::com_array&& comArrayValue) noexcept;

parameters

comArrayValue要分配给com_array对象的com_array值。

返回值

对 com_array 对象的引用。

put_abi函数

检索 com_array 的地址，以便它可以设置为另一个值。 另请参阅 winrt：:p ut_abi 函数。

语法

template<typename T> auto put_abi(winrt::com_array<T>& object) noexcept;

parameters

object要操作的com_array对象。

返回值

com_array的地址，准备设置为另一个值。

swap 函数

交换两 个com_array 参数的内容。

语法

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

parameters

leftright一个com_array值，其内容与另一个参数的内容相互交换。

示例

using namespace winrt;
...
    com_array<byte> left{ 1,2,3 };
    com_array<byte> right{ 4,5,6 };
    swap(left, right);

请参阅

• winrt 命名空间