Modelo de struct winrt::com_array (C++/WinRT)

Representa uma matriz de dados de estilo C em que o buffer subjacente é alocado e liberado por meio do alocador de tarefas COM, daí o nome. Normalmente, ele é usado para representar uma matriz compatível com estilo C alocada por um componente e liberada por outro.

winrt::com_array é usado para passar parâmetros de e para Windows Runtime APIs. Se você estiver criando APIs, provavelmente precisará construir um winrt::com_array para retornar uma matriz projetada ao chamador; como o valor retornado ou por meio de um parâmetro de saída.

winrt::com_array deriva de winrt::array_view. Consulte o tópico do modelo de struct winrt::array_view , que documenta membros e operadores gratuitos que também estão disponíveis para winrt::com_array. No entanto, lembre-se da diferença na semântica entre o tipo base winrt::array_view (que é uma exibição não proprietária, ou span, de uma série contígua de valores) e winrt::com_array (que aloca e libera seus próprios elementos).

Syntax

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

Parâmetros de modelo

typename T O tipo dos valores (elementos) que o com_array contém.

Requisitos

SDK mínimo com suporte: Windows SDK versão 10.0.17134.0 (Windows 10, versão 1803)

Namespace: winrt

Cabeçalho: %WindowsSdkDir%IncludeWindowsTargetPlatformVersion<>\cppwinrt\winrt\base.h (incluído por padrão)

Construtores

Construtor	Descrição
Construtor com_array::com_array	Inicializa uma nova instância do struct com_array com uma cópia dos dados de entrada ou com valores padrão de T se nenhum dado for fornecido.

Funções de membro

Função	Descrição
função com_array::clear	Torna o objeto com_array vazio.

Operadores membros

Operador	Descrição
com_array::operator= (operador de atribuição)	Atribui um valor ao objeto com_array .

Funções gratuitas

Função	Descrição
função detach_abi	Desanexa o objeto com_array de seus valores brutos, talvez para devolvê-los a um chamador. O com_array está limpo. Consulte também a função winrt::d etach_abi.
função put_abi	Recupera o endereço do com_array para que ele possa ser definido como outro valor. Consulte também a função winrt::p ut_abi.
função swap	Troca o conteúdo dos dois parâmetros de com_array .

Construtor com_array::com_array

Inicializa uma nova instância do struct com_array com uma cópia dos dados de entrada ou com valores padrão de T se nenhum dado for fornecido.

Syntax

Os construtores são numerados e descritos mais adiante em Comentários abaixo.

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;

Parâmetros de modelo

typename InIt Um iterador de entrada, que fornece os dados de entrada.

size_t Nuint32_t N O número de valores (elementos) nos dados de entrada.

Parâmetros

arrayValue Um valor std::array que inicializa o objeto com_array .

comArrayValue Outro com_array que inicializa o objeto com_array . Após o retorno do construtor, o comArrayValue ficará vazio.

count A contagem de elementos do objeto com_array .

firstlast Um par de iteradores de entrada. Os valores no intervalo [primeiro, último) são usados para inicializar o objeto com_array .

initializerListValue Um valor de lista de inicializador que inicializa o objeto com_array .

ptr Um ponteiro para um bloco de valores N, que você alocou usando CoTaskMemAlloc. O objeto com_array se apropria dessa memória.

rawArrayValue Uma matriz de estilo C que inicializa o objeto com_array .

value O valor a ser entregue a cada elemento do objeto com_array .

vectorValue Um valor std::vector que inicializa o objeto com_array .

Comentários

Os construtores são numerados na sintaxe acima.

1. Construtor padrão

Constrói um buffer vazio.

2. Construtor de capacidade; valor padrão

Cria um buffer de elementos de contagem , todos copiados de um T construído por padrão.

Isso é semelhante a (mas não o mesmo que) criar um buffer de elementos de contagem , cada um dos quais é um T construído por padrão.

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

O construtor padrão do objeto MediaPlayer cria uma referência a um novo objeto de player de mídia e seu construtor de cópia copia a referência. Portanto, a linha de código acima cria uma matriz de 50 referências ao mesmo objeto de player de mídia. Ele não cria uma matriz de 50 objetos diferentes do player de mídia.

3. Construtor de capacidade; valor explícito

Cria um buffer de elementos de contagem , cada um deles uma cópia do valor fornecido.

winrt::com_array(2, 42) é interpretado como uma tentativa de usar o construtor de intervalo (4). Mas falha porque 2 e 42 não são iteradores. Para que isso seja interpretado como um construtor de capacidade com um valor int32_t explícito, use um inteiro explicitamente sem sinal como o primeiro parâmetro: com_array(2u, 42).

4. Construtor de intervalo

Cria um buffer que é uma cópia do intervalo [primeiro, último).

Declare o tipo T subjacente explicitamente, assim.

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

Para mover o intervalo, em vez de copiá-lo, use o adaptador de iterador std::move_iterator .

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

5. Construtor vetor

Cria um buffer que é uma cópia do conteúdo de vectorValue.

6. Construtor de matriz

Cria um buffer que é uma cópia do conteúdo de arrayValue.

7. Construtor de matriz no estilo C

Cria um buffer que é uma cópia do conteúdo da matriz de estilo C rawArrayValue.

8. Construtor de lista de inicializadores

Cria um buffer que é uma cópia do conteúdo da lista de inicializadores initializer InitializerListValue.

9. Construtor ABI

Assume a propriedade de um buffer de comprimento especificado.

Este nível mais baixo dos construtores. Use-o quando você tiver um bloco de memória já alocado por meio do CoTaskMemAlloc e quiser que o com_array assuma a responsabilidade por ela. Para enfatizar os requisitos especiais para esse construtor, o argumento final deve ser winrt::take_ownership_from_abi.

10. Mover construtor

Move os recursos de outro com_array do mesmo tipo, deixando o original vazio.

Construtores 5, 6 e 7

As cópias são retiradas do conteúdo do contêiner fornecido. Você pode usar o construtor de intervalo (4) com o adaptador do iterador std::move_iterator para mover o conteúdo para o com_array em vez de copiá-los.

função com_array::clear

Torna o objeto com_array vazio.

Syntax

void clear() noexcept;

função detach_abi

Desanexa o objeto com_array de seus valores brutos, talvez para devolvê-los a um chamador. O com_array está limpo. Consulte também a função winrt::d etach_abi.

Sintaxe

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

Parâmetros

object Um objeto com_array para operar.

Valor retornado

Uma tupla de dois elementos que contém uma contagem de elementos e a série contígua de valores que o com_array estendeu.

com_array::operator= (operador de atribuição)

Atribui um valor ao objeto com_array .

Sintaxe

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

Parâmetros

comArrayValue Um valor com_array a ser atribuído ao objeto com_array .

Valor retornado

Uma referência ao objeto com_array .

função put_abi

Recupera o endereço do com_array para que ele possa ser definido como outro valor. Consulte também a função winrt::p ut_abi.

Sintaxe

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

Parâmetros

object Um objeto com_array para operar.

Valor retornado

O endereço do com_array, pronto para ser definido como outro valor.

função swap

Troca o conteúdo dos dois parâmetros com_array .

Sintaxe

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

Parâmetros

leftright Um com_array valor cujo conteúdo deve ser alternado mutuamente com os do outro parâmetro.

Exemplo

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

Confira também

• namespace winrt