Passage de paramètres aux API projetées

Pour certains types, C++/WinRT fournit d’autres méthodes pour transmettre un paramètre à une API projetée. Ces classes acceptant les paramètres sont placées dans l’espace de noms winrt::param. Seul le code généré par C++/WinRT doit utiliser ces classes ; ne les utilisez pas dans vos propres fonctions et méthodes.

Certaines de ces options font la distinction entre les appels synchrones et asynchrones. La version des appels asynchrones prend généralement la propriété des données de paramètre pour s’assurer que les valeurs restent valides et inchangées tant que l’appel asynchrone n’est pas terminé. Notez toutefois que cette protection ne s’étend pas aux modifications apportées à la collection à partir d’un autre thread. Il est de votre responsabilité d’empêcher cela.

Options pour les paramètres de chaîne

winrt::param::hstring simplifie le passage de paramètres en tant que winrt::hstring. En plus de winrt::hstring, ces options sont également acceptées :

Vous ne pouvez pas passer nullptr pour représenter la chaîne vide. Utilisez plutôt L"" ou {}.

Le compilateur sait comment évaluer wcslen sur les littéraux de chaîne au moment de la compilation. Pour les littéraux, L"Name"sv et L"Name" sont donc équivalents.

Notez que les objets std::wstring_view ne se terminent pas par une valeur null. Toutefois, C++/WinRT nécessite que le caractère situé après la chaîne soit une valeur null. Si vous passez un std::wstring_view qui ne se termine pas par une valeur null, le processus s’arrête.

Options pour les paramètres itérables

winrt::param::iterable<T> et winrt::param::async_iterable<T> simplifient le passage de paramètres en tant que IIterable<T>.

Les collections Windows Runtime IVector<T> et IVectorView<T> prennent déjà en charge IIterable<T>. Les collections Windows Runtime IMap<K, V> et IMapView<K, V> prennent déjà en charge IIterable<IKeyValuePair<K, V>>.

Outre IIterable<T>, les options suivantes sont également acceptées. Notez que certaines options sont disponibles uniquement pour les méthodes synchrones.

Le double-itérateur fonctionne généralement dans les cas où vous avez une collection qui ne correspond à aucun des scénarios ci-dessus, à condition toutefois que vous puissiez l’itérer et produire des éléments pouvant être convertis en T. Par exemple, vous pouvez avoir un IVector<U> ou std::vector<U>, où U est convertible en T.

Dans l’exemple suivant, la méthode SetStorageItems attend un IIterable<IStorageItem>. Le modèle double-itérateur nous permet de passer d’autres types de collections.

// 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

Pour le cas de IIterable<IKeyValuePair<K, V>>, les alternatives suivantes sont acceptées. Notez que certaines options sont disponibles uniquement pour les méthodes synchrones.

Options pour les paramètres de vue vectorielle

winrt::param::vector_view<T> et winrt::param::async_vector_view<T> simplifient le passage de paramètres en tant que IVectorView<T>.

Vous pouvez appeler IVector<T>::GetView pour obtenir un IVectorView<T> à partir d’un IVector<T>.

Outre IVectorView<T>, les options suivantes sont également acceptées. Notez que certaines options sont disponibles uniquement pour les méthodes synchrones.

Là encore, la version double-itérateur peut être utilisée pour créer des affichages vectoriels hors des éléments qui ne correspondent pas à une option existante. L’affichage temporaire est plus efficace si les itérateurs begin et end sont des itérateurs d’accès aléatoire.

Options pour les paramètres d’affichage cartographique

winrt::param::map_view<T> et winrt::param::async_map_view<T> simplifient le passage de paramètres en tant que IMapView<T>.

Vous pouvez appeler IMap<K, V>::GetView pour obtenir un IMapView<K, V> à partir d’un IMap<K, V>.

Outre IMapView<K, V>, les options suivantes sont également acceptées. Notez que certaines options sont disponibles uniquement pour les méthodes synchrones.

Options pour les paramètres de vecteur

winrt::param::vector<T> simplifie le passage de paramètres en tant que IVector<T>. Outre IVector<T>, ces options sont également acceptées :

Si la méthode mute le vecteur temporaire, ces modifications ne sont pas reflétées dans les paramètres d’origine. Pour observer les modifications, passez un IVector<T>.

Options pour les paramètres de carte

winrt::param::map<K, V> simplifie le passage de paramètres en tant que IMap<K, V>. Outre IMap<K, V>, ces options sont également acceptées :

Si la méthode mute la carte temporaire, ces modifications ne sont pas reflétées dans les paramètres d’origine. Pour observer les modifications, passez un IMap<K, V>.

Options pour les paramètres de tableau

winrt::array_view<T> n’est pas dans l’espace de noms winrt::param, mais il est utilisé pour les paramètres qui sont des tableaux de style C. En plus d’un array_view<T> explicite, ces options sont également acceptées :

Consultez également le billet de blog The various patterns for passing C-style arrays across the Windows Runtime ABI boundary.