Passando parâmetros para APIs projetadas

Para determinados tipos, o C++/WinRT fornece métodos alternativos para passar um parâmetro para uma API projetada. Essas classes de aceitação de parâmetros são colocadas no namespace winrt::p aram. Somente um código gerado por C++/WinRT deve usar essas classes, não use elas nas suas funções e métodos.

Algumas dessas alternativas distinguem entre chamadas síncronas e assíncronas. A versão para chamadas assíncronas normalmente assume a propriedade dos dados do parâmetro para garantir que os valores permaneçam válidos e inalterados até que a chamada assíncrona seja concluída. No entanto, observe que essa proteção não se estende a alterações na coleção de outro thread. Impedir isso é sua responsabilidade.

Alternativas para parâmetros de cadeia de caracteres

O winrt::p aram::hstring simplifica os parâmetros de passagem como o winrt::hstring. Além do winrt::hstring, essas alternativas também são aceitas:

Você não pode passar nullptr para representar a cadeia de caracteres vazia. Use L"" ou {}.

O compilador sabe como avaliar wcslen em literais de cadeia de caracteres em tempo de compilação. Portanto, para literais, L"Name"sv e L"Name" são equivalentes.

Observe que objetos std::wstring_view não são terminados em nulo, mas o C++/WinRT exige que o caractere após o final da cadeia de caracteres seja nulo. Se você passar uma std::wstring_view não terminada em nulo, o processo será encerrado.

Alternativas para parâmetros iteráveis

O winrt::param::iterable<T> e o winrt::param::async_iterable<T> simplificam a passagem de parâmetros como o IIterable<T>.

As coleções IVector<T> e IVectorView<T> do Windows Runtime já dão suporte a IIterable<T>. As coleções do Windows Runtime IMap<K, V> e IMapView<K, V> já dão suporte a IIterable<IKeyValuePair<K, V>>.

Além do IIterable<T>, as alternativas a seguir também são aceitas. Observe que algumas alternativas estão disponíveis apenas para métodos síncronos.

O iterador duplo funciona de maneira mais geral no caso em que você tem uma coleção que não se encaixa em nenhum dos cenários acima, desde que você possa iterar nele e produzir coisas que possam ser convertidas em T. Por exemplo, você pode ter um IVector<U> ou um std::vector<U>, em que U é conversível para T.

No exemplo a seguir, o método SetStorageItems espera um IIterable<IStorageItem>. O padrão de iterador duplo nos permite passar outros tipos de coleções.

// IVector of derived types.
winrt::Windows::Foundation::Collections::IVector<winrt::Windows::Storage::StorageFile>
    storageFiles{ /* initialization elided */ };
dataPackage.SetStorageItems(storageFiles); // doesn't work
dataPackage.SetStorageItems({ storageFiles.begin(), storageFiles.end() }); // works

// Array of derived types.
std::array<winrt::Windows::Storage::StorageFile, 3>
    storageFiles{ /* initialization elided */ };
dataPackage.SetStorageItems(storageFiles); // doesn't work
dataPackage.SetStorageItems({ storageFiles.begin(), storageFiles.end() }); // works

Para o caso do IIterable<IKeyValuePair<K, V>>, as alternativas a seguir são aceitas. Observe que algumas alternativas estão disponíveis apenas para métodos síncronos.

Alternativas para parâmetros de exibição de vetor

O winrt::param::vector_view<T> e o winrt::param::async_vector_view<T> simplificam a passagem de parâmetros como o IVectorView<T>.

Você pode chamar IVector<T>::GetView para obter um IVectorView<T> de um IVector<T>.

Além do IVectorView<T>, as alternativas a seguir também são aceitas. Observe que algumas alternativas estão disponíveis apenas para métodos síncronos.

Novamente, a versão do iterador duplo pode ser usada para criar exibições de vetor de itens que não se encaixam em uma alternativa existente. A exibição temporária será mais eficiente se os iteradores begin e end forem iteradores de acesso aleatório.

Alternativas para parâmetros de exibição de mapa

O winrt::param::map_view<T> e o winrt::param::async_map_view<T> simplificam a passagem de parâmetros como o IMapView<T>.

Você pode chamar IMap<K, V>::GetView para obter um IMapView<K, V> de um IMap<K, V>.

Além do IMapView<K, V>, as alternativas a seguir também são aceitas. Observe que algumas alternativas estão disponíveis apenas para métodos síncronos.

Alternativas para parâmetros de vetor

O winrt::p aram::vector<T> simplifica a passagem de parâmetros como o IVector<T>. Além do IVector<T>, essas alternativas também são aceitas:

Se o método alterar o vetor temporário, essas alterações não serão refletidas nos parâmetros originais. Para observar as alterações, passe um IVector<T>.

Alternativas para parâmetros de mapa

O winrt::p aram::map<K, V> simplifica a passagem de parâmetros como o IMap<K, V>. Além do IMap<K, V>, essas alternativas também são aceitas:

Se o método alterar o mapa temporário, essas alterações não serão refletidas nos parâmetros originais. Para observar as alterações, passe um IMap<K, V>.

Alternativas para parâmetros de matriz

O winrt::array_view<T> não está no namespace winrt::param, mas é usado para parâmetros que são matrizes de estilo C. Além de um array_view<T>explícito, essas alternativas também são aceitas:

Confira também a postagem no blog Os vários padrões para transmitir matrizes em estilo C entre o limite do ABI do Windows Runtime.