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

表示一种符合 C 样式的数据数组,其中,基础缓冲区通过 COM 任务分配器分配并释放,因此是名称。Represents a C-style conformant array of data where the underlying buffer is allocated and freed via the COM task allocator, hence the name. 它通常用于表示 C 样式相容数组,该数组由一个组件分配并由另一个组件释放。It's typically used to represent a C-style conformant array that's allocated by one component, and freed by another.

winrt:: com_array 用于在 Windows 运行时 api 之间传递参数。winrt::com_array is used for passing parameters to and from Windows Runtime APIs. 如果正在创作 Api,则可能需要构建 winrt:: com_array 将投影数组返回给调用方;作为返回值,或通过输出参数。If you're authoring APIs then you'll probably need to construct a winrt::com_array to return a projected array to the caller; either as the return value, or through an output parameter.

winrt:: com_arraywinrt:: array_view派生。winrt::com_array derives from winrt::array_view. 请参阅 winrt:: array_view 结构模板主题,该主题介绍了也可用于 winrt:: com_array的成员和自由运算符。See the winrt::array_view struct template topic, which documents members and free operators that are also available to winrt::com_array. 但请注意,基类型 winrt:: array_view ((这是一种非所有者视图,或者跨越一系列连续的值) 和 winrt:: com_array (的语义之间的语义差别,) 将分配并释放其自己的元素。However, be aware of the difference in semantics between the base type winrt::array_view (which is a non-owning view, or span, of a contiguous series of values), and winrt::com_array (which allocates and frees its own elements).

语法Syntax

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

模板参数Template parameters

typename TCom_array包含) 值 (元素的类型。typename T The type of the values (elements) that the com_array contains.

要求Requirements

支持的最低 SDK: Windows SDK 版本 10.0.17134.0 (Windows 10 版本 1803) Minimum supported SDK: Windows SDK version 10.0.17134.0 (Windows 10, version 1803)

命名空间: winrtNamespace: winrt

标头 % WindowsSdkDir% 包括 <WindowsTargetPlatformVersion> 默认情况下包含的 \cppwinrt\winrt\base.h () Header %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (included by default)

构造函数Constructors

构造函数Constructor 说明Description
com_array:: com_array 构造函数com_array::com_array constructor 使用输入数据的副本初始化 com_array 结构的新实例, T 如果未提供任何数据,则使用的默认值初始化。Initializes a new instance of the com_array struct with a copy of the input data, or with default values of T if no data is provided.

成员函数Member functions

函数Function 说明Description
com_array:: clear 函数com_array::clear function 使 com_array 对象为空。Makes the com_array object empty.

成员运算符Member operators

运算符Operator 说明Description
com_array:: operator = (赋值运算符) com_array::operator= (assignment operator) com_array 对象赋值。Assigns a value to the com_array object.

Free 函数Free functions

函数Function 说明Description
detach_abi 函数detach_abi function com_array 对象与其原始值分离,可能会将其返回给调用方。Detaches the com_array object from its raw values, perhaps to return them to a caller. Com_array已清除。The com_array is cleared. 另请参阅 winrt::d etach_abi 函数Also see winrt::detach_abi function.
put_abi 函数put_abi function 检索 com_array 的地址,以便可以将其设置为其他值。Retrieves the address of the com_array so that it can be set to another value. 另请参阅 winrt::p ut_abi 函数Also see winrt::put_abi function.
swap 函数swap function 交换两个 com_array 参数的内容。Swaps the contents of the two com_array parameters.

com_array:: com_array 构造函数com_array::com_array constructor

使用输入数据的副本初始化 com_array 结构的新实例, T 如果未提供任何数据,则使用的默认值初始化。Initializes a new instance of the com_array struct with a copy of the input data, or with default values of T if no data is provided.

语法Syntax

构造函数进行编号,后面的 " 备注 " 中对其进行了进一步说明。The constructors are numbered, and described further in Remarks below.

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;

模板参数Template parameters

typename InIt 输入迭代器,提供输入数据。typename InIt An input iterator, which provides the input data.

size_t N``uint32_t N输入数据中) 元素 (值的数目。size_t N uint32_t N The number of values (elements) in the input data.

parametersParameters

arrayValue用于初始化com_array对象的std:: array值。arrayValue A std::array value that initializes the com_array object.

comArrayValue初始化com_array对象的另一个com_arraycomArrayValue Another com_array that initializes the com_array object. 构造函数返回后, comArrayValue 将为空。After the constructor returns, comArrayValue will be empty.

countCom_array对象的元素计数。count The element count of the com_array object.

first``last一对输入迭代器。first last A pair of input iterators. 范围 [firstlast) 中的值用于初始化 com_array 对象。The values in the range [first, last) are used to initialize the com_array object.

initializerListValue 初始化 com_array 对象的初始值设定项列表值。initializerListValue An initializer list value that initializes the com_array object.

ptr 指向使用 CoTaskMemAlloc分配的 N 值块的指针。ptr A pointer to a block of N values, which you've allocated by using CoTaskMemAlloc. Com_array对象获取此内存的所有权。The com_array object takes ownership of this memory.

rawArrayValue用于初始化 com_array 对象的 C 样式数组 com_array   。rawArrayValue A C-style array that initializes the com_array object.

value 要赋给 com_array 对象的每个元素的值。value The value to give to each element of the com_array object.

vectorValue用于初始化com_array对象的std:: vector值。vectorValue A std::vector value that initializes the com_array object.

备注Remarks

构造函数按上述 语法 进行编号。The constructors are numbered in Syntax above.

1. 默认构造函数1. Default constructor

构造一个空缓冲区。Constructs an empty buffer.

2. 容量构造函数;默认值2. Capacity constructor; default value

创建 count 元素的缓冲区,所有这些元素都是默认构造的 T的副本。Creates a buffer of count elements, all of which are copies of a default-constructed T.

这类似于 (,但与) 创建 count 元素缓冲区相同,其中每个元素都是默认构造的 TThis is similar to (but not the same as) creating a buffer of count elements, each of which is a default-constructed T.

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

MediaPlayer对象的默认构造函数创建对新 media player 对象的引用,其复制构造函数复制引用。The MediaPlayer object's default constructor creates a reference to a new media player object, and its copy constructor copies the reference. 因此,上述代码行创建对同一 media player 对象的50引用数组。Therefore, the above line of code creates an array of 50 references to the same media player object. 它不会创建50不同媒体播放器对象的数组。It doesn't create an array of 50 different media player objects.

3. 容量构造函数;显式值3. Capacity constructor; explicit value

创建 count 元素的缓冲区,其中每个元素都是所提供的 的副本。Creates a buffer of count elements, each of which is a copy of the provided value.

winrt::com_array(2, 42) 被解释为尝试使用范围构造函数 (4) 。winrt::com_array(2, 42) is interpreted as an attempt to use the range constructor (4). 但失败是因为2和42不是迭代器。But it fails because 2 and 42 aren't iterators. 若要使其被解释为具有显式 int32_t 值的容量构造函数,请使用显式无符号整数作为第一个参数: com_array(2u, 42)To get this to be interpreted as a capacity constructor with an explicit int32_t value, use an explicitly unsigned integer as the first parameter: com_array(2u, 42).

4. 范围构造函数4. Range constructor

创建一个缓冲区,该缓冲区是范围 [firstlast) 的副本。Creates a buffer that is a copy of the range [first, last).

显式声明基础类型 T ,如下所示。State the underlying type T explicitly, like this.

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

若要移动范围,而不是复制它,请使用 std:: move_iterator 迭代器适配器。To move the range, rather than copying it, use the std::move_iterator iterator adaptor.

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

5. Vector 构造函数5. Vector constructor

创建作为 vectorValue内容副本的缓冲区。Creates a buffer that is a copy of the contents of vectorValue.

6. Array 构造函数6. Array constructor

创建作为 arrayValue内容副本的缓冲区。Creates a buffer that is a copy of the contents of arrayValue.

7. C 样式数组构造函数7. C-style array constructor

创建一个缓冲区,该缓冲区是 rawArrayValue的 C 样式数组内容的副本。Creates a buffer that is a copy of the contents of the C-style array rawArrayValue.

8. 初始值设定项列表构造函数8. Initializer-list constructor

创建作为初始值设定项列表 initializerListValue内容副本的缓冲区。Creates a buffer that is a copy of the contents of the initializer list initializerListValue.

9. ABI 构造函数9. ABI constructor

取得指定长度的缓冲区的所有权。Takes ownership of a buffer of specified length.

这一最低级别的构造函数。This lowest-level of the constructors. 如果已通过 CoTaskMemAlloc分配了内存块,并希望 com_array 为其承担责任,则可以使用此方法。Use it when you have a block of memory already allocated via Co­Task­Mem­Alloc, and you want the com_array to assume responsibility for it. 若要强调此构造函数的特殊要求,最后一个参数必须是 winrt:: take_ownership_from_abiTo emphasize the special requirements for this constructor, the final argument must be winrt::take_ownership_from_abi.

10. 移动构造函数10. Move constructor

从同一类型的另一个 com_array 移动资源,保留原始的空。Moves the resources from another com_array of the same type, leaving the original empty.

构造函数5、6和7Constructors 5, 6, and 7

副本是所提供容器的内容。Copies are taken of the contents of the provided container. 可以将范围构造函数 (4) 与 std:: move_iterator 迭代器适配器一起使用,将内容移动到 com_array 而不是复制它们。You can use the range constructor (4) with the std::move_iterator iterator adaptor to move the contents into the com_array instead of copying them.

com_array:: clear 函数com_array::clear function

使 com_array 对象为空。Makes the com_array object empty.

语法Syntax

void clear() noexcept;

detach_abi 函数detach_abi function

com_array 对象与其原始值分离,可能会将其返回给调用方。Detaches the com_array object from its raw values, perhaps to return them to a caller. Com_array已清除。The com_array is cleared. 另请参阅 winrt::d etach_abi 函数Also see winrt::detach_abi function.

语法Syntax

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

parametersParameters

object 要操作的 com_array 对象。object A com_array object to operate on.

返回值Return value

包含元素计数的两元素元组,以及 com_array 跨的连续值序列。A two-element tuple containing an element count, and the contiguous series of values that the com_array spanned.

com_array:: operator = (赋值运算符) com_array::operator= (assignment operator)

com_array 对象赋值。Assigns a value to the com_array object.

语法Syntax

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

parametersParameters

comArrayValue要分配给com_array对象的com_array值。comArrayValue A com_array value to assign to the com_array object.

返回值Return value

com_array 对象的引用。A reference to the com_array object.

put_abi 函数put_abi function

检索 com_array 的地址,以便可以将其设置为其他值。Retrieves the address of the com_array so that it can be set to another value. 另请参阅 winrt::p ut_abi 函数Also see winrt::put_abi function.

语法Syntax

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

parametersParameters

object 要操作的 com_array 对象。object A com_array object to operate on.

返回值Return value

Com_array的地址,可以设置为另一个值。The address of the com_array, ready to be set to another value.

swap 函数swap function

交换两个 com_array 参数的内容。Swaps the contents of the two com_array parameters.

语法Syntax

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

parametersParameters

left``right一个com_array值,其内容与其他参数的内容相互交换。left right A com_array value whose contents to mutually swap with those of the other parameter.

示例Example

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

另请参阅See also