Passaggio di parametri ad API proiettate

Per determinati tipi, C++/WinRT fornisce metodi alternativi per passare un parametro a un'API proiettata. Queste classi che accettano parametri vengono inserite nello spazio dei nomi winrt::p aram. Solo il codice generato da C++/WinRT deve usare queste classi; non devono essere usate nelle funzioni e nei metodi personalizzati.

Importante

Non usare direttamente i tipi dello spazio dei nomi winrt::param. Sono destinati alla proiezione.

Alcune di queste alternative distinguono tra chiamate sincrone e asincrone. La versione per le chiamate asincrone assume in genere la proprietà dei dati dei parametri per garantire che i valori rimangano validi e invariati fino al completamento della chiamata asincrona. Si noti, tuttavia, che questa protezione non si estende alle modifiche apportate alla raccolta da un altro thread. È tua responsabilità impedirne la modifica.

Alternative per i parametri di stringa

winrt::param::hstring semplifica il passaggio di parametri alle API che accettano winrt::hstring. Oltre a winrt::hstring, vengono accettate anche le seguenti alternative:

Alternativa	Note
{}	stringa vuota
std::wstring_view	La vista deve essere seguita da un carattere di terminazione Null.
std::wstring
wchar_t const*	Specifica una stringa che termina con Null.

Non è possibile passare nullptr per rappresentare la stringa vuota. Usare invece L"" o {}.

Il compilatore sa come valutare wcslen su valori letterali stringa in fase di compilazione. Di conseguenza, per i valori letterali, L"Name"sv e L"Name" sono equivalenti.

Nota che gli oggetti std::wstring_view non hanno terminazione Null, ma C++/WinRT richiede che il carattere dopo la fine della vista sia Null. Se passi un tipo std::wstring_view con terminazione non Null, il processo verrà terminato.

Alternative per i parametri iterabili

I parametri winrt::param::iterable<T> e winrt::param::async_iterable<T> semplificano il passaggio di parametri alle API che accettano IIterable<T>.

Le raccolte di Windows Runtime IVector<T> e IVectorView<T> supportano già IIterable<T>. Le raccolte IMap<K, V> e IMapView<K, V> di Windows Runtime supportano già IIterable<IKeyValuePair<K, V>>.

Oltre a IIterable<T>, vengono accettate anche le alternative seguenti. Si noti che alcune alternative sono disponibili solo per i metodi sincroni.

Alternativa	Sync	Async	Note
std::vector<T> const&	Sì	No
std::vector<T>&&	Sì	Sì	Il contenuto viene spostato in un iterabile temporaneo.
std::initializer_list<T>	Sì	Sì	La versione asincrona copia gli elementi.
std::initializer_list<U>	Sì	No	U deve essere convertibile in T.
{ begin, end }	Sì	No	begin e end devono essere iteratori in avanti e *begin devono essere convertibili in T.

Il doppio iteratore funziona più in generale per il caso in cui si disponga di una raccolta che non rientra in nessuno degli scenari precedenti, purché sia possibile eseguire l'iterazione su di essa e produrre elementi che possono essere convertiti in T. Ad esempio, è possibile avere un IVector U o std::vector U<, dove> U è convertibile in<T>.

Nell'esempio seguente il metodo Set Archiviazione Items prevede un IIterable<I Archiviazione Item>. Il modello a doppio iteratore consente di passare altri tipi di raccolte.

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

Per il caso di IIterable<IKeyValuePair<K, V>>, vengono accettate le alternative seguenti. Si noti che alcune alternative sono disponibili solo per i metodi sincroni.

Alternativa	Sync	Async	Note
std::map<K, V> const&	Sì	No
std::map<K, V>&&	Sì	Sì	Il contenuto viene spostato in un iterabile temporaneo.
std::unordered_map<K, V> const&	Sì	No
std::unordered_map<K, V>&&	Sì	Sì	Il contenuto viene spostato in un iterabile temporaneo.
std::initializer_list<std::pair<K, V>>	Sì	Sì	La versione asincrona copia l'elenco in un'iterabile temporaneo.
{ begin, end }	Sì	No	begin e end devono essere iteratori in avanti e begin->first devono begin->second essere convertibili rispettivamente in K e V.

Alternative per i parametri di visualizzazione vettoriale

winrt::param::vector_view<T> e winrt::param::async_vector_view<T> semplificano il passaggio di parametri alle API che accettano IVectorView<T>.

È possibile chiamare IVector<T>::GetView per ottenere IVectorView<T> da IVector<T>.

Oltre a IVectorView<T>, vengono accettate anche le alternative seguenti. Si noti che alcune alternative sono disponibili solo per i metodi sincroni.

Alternativa	Sync	Async	Note
std::vector<T> const&	Sì	No
std::vector<T>&&	Sì	Sì	Il contenuto viene spostato in una vista temporanea.
std::initializer_list<T>	Sì	Sì	La versione asincrona copia l'elenco in una vista temporanea.
{ begin, end }	Sì	No	begin e end devono essere iteratori in avanti e *begin devono essere convertibili in T.

Anche in questo caso, la versione a doppio iteratore può essere usata per creare visualizzazioni vettoriali non adatte a un'alternativa esistente. La visualizzazione temporanea è più efficiente se gli iteratori begin e end sono iteratori ad accesso casuale.

Alternative per i parametri di visualizzazione mappa

winrt::param::map_view<T> e winrt::param::async_map_view<T> semplificano il passaggio di parametri alle API che accettano IMapView<T>.

È possibile chiamare IMap<K, V>::GetView per ottenere un IMapView<K, V> da un IMap<K, V>.

Oltre a IMapView<K, V>, vengono accettate anche le alternative seguenti. Si noti che alcune alternative sono disponibili solo per i metodi sincroni.

Alternativa	Sync	Async	Note
std::map<K, V> const&	Sì	No
std::map<K, V>&&	Sì	Sì	Il contenuto viene spostato in una vista temporanea.
std::unordered_map<K, V> const&	Sì	No
std::unordered_map<K, V>&&	Sì	Sì	Il contenuto viene spostato in una vista temporanea.
std::initializer_list<std::pair<K, V>>	Sì	Sì	Il contenuto viene copiato in una visualizzazione temporanea. Le chiavi devono essere univoche.

Alternative per i parametri vettoriali

winrt::param::vector<T> semplifica il passaggio di parametri come IVector<T>. Oltre a IVector<T>, sono accettate anche queste alternative:

Alternativa	Note
std::vector<T>&&	Il contenuto viene spostato in un vettore temporaneo. I risultati non vengono riposizionati.
std::initializer_list<T>

Se il metodo modifica il vettore temporaneo, tali modifiche non vengono riflesse nei parametri originali. Per osservare le modifiche, passare un IVector<T>.

Alternative per i parametri di mappa

winrt::p aram::map<K, V> semplifica il passaggio di parametri come IMap<K, V>. Oltre a IMap<K, V>, sono accettate anche queste alternative:

È possibile passare	Note
std::map<K, V>&&	Il contenuto viene spostato in una mappa temporanea. I risultati non vengono riposizionati.
std::unordered_map<K, V>&&	Il contenuto viene spostato in una mappa temporanea. I risultati non vengono riposizionati.
std::initializer_list<std::pair<K, V>>

Se il metodo modifica la mappa temporanea, tali modifiche non vengono riflesse nei parametri originali. Per osservare le modifiche, passare un IMap<K, V>.

Alternative per i parametri di matrice

winrt::array_view<T> non è incluso nello stesso spazio dei nomi winrt::param, ma viene usato per il parametri costituiti da matrici in stile C. Oltre a un array_view<T> esplicito, vengono accettate anche queste alternative:

Alternativa	Note
{}	Matrice vuota.
U[]	Matrice di tipo C, in cui U è convertibile in T e sizeof(U) == sizeof(T).
std::array<U, N>	Dove U è convertibile in T e sizeof(U) == sizeof(T).
std::vector<U>	Dove U è convertibile in T e sizeof(U) == sizeof(T).
{ begin, end }	begin e end deve essere di tipo T*, che rappresenta l'intervallo [begin, end).
std::initializer_list<T>
std::span<U, N>	Dove U è convertibile in T e sizeof(U) == sizeof(T).

Vedi anche il post di blog relativo ai vari modelli per passare le matrici di tipo C attraverso il limite ABI di Windows Runtime.