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 usarli nelle funzioni e nei metodi personalizzati.

Importante

Non dovresti usare direttamente i tipi del namespace winrt::param. Servono a favorire la 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. Prevenire questa è la responsabilità dell'utente.

Alternative per i parametri di stringa

winrt::p aram::hstring semplifica il passaggio di parametri come winrt::hstring. Oltre a winrt::hstring, vengono accettate anche queste alternative:

Alternativa Notes
{} Stringa vuota.
std::wstring_view La visualizzazione deve essere seguita da un terminatore null.
std::wstring
wchar_t const* Stringa che termina con un valore Null.

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

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

Si noti che gli oggetti std::wstring_view non vengono terminati con null, ma C++/WinRT richiede che il carattere dopo la fine della visualizzazione sia null. Se si passa un std::wstring_view con terminazione non Null, il processo verrà terminato.

Alternative per i parametri iterabili

winrt::param::iterable<T> e winrt::param::async_iterable<T> semplificano il passaggio di parametri come IIterable<T>.

Le raccolte di Windows Runtime IVector<T> e IVectorView<T> supportano già IIterable<T>. Le raccolte Windows Runtime IMap<K, V> e IMapView<K, V> 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 Notes
std::vector<T> const& Yes No
std::vector<T>& Yes Yes I contenuti vengono spostati in un iterabile temporaneo.
std::initializer_list<T> Yes Yes La versione asincrona copia gli elementi.
std::initializer_list<U> Yes No U deve essere convertibile in T.
{ begin, end } Yes No begin e end devono essere iteratori in avanti e *begin devono essere convertibili in T.

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

Nell'esempio seguente il metodo SetStorageItems prevede un IIterable<IStorageItem>. 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 Notes
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes I contenuti vengono spostati in un iterabile temporaneo.
std::unordered_map<K, V> const& Yes No
std::unordered_map<K, V>&& Yes Yes I contenuti vengono spostati in un iterabile temporaneo.
std::initializer_list<std::pair<K, V>> Yes Yes La versione asincrona copia l'elenco in un oggetto iterabile temporaneo.
{ begin, end } Yes 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::p aram::vector_view<T> e winrt::p aram::async_vector_view<T> semplificano il passaggio di parametri come IVectorView<T>.

È possibile chiamare IVector<T>::GetView per ottenere un oggetto IVectorView<T> da un oggetto 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 Notes
std::vector<T> const& Yes No
std::vector<T>& Yes Yes Il contenuto viene spostato in una visualizzazione temporanea.
std::initializer_list<T> Yes Yes La versione asincrona copia l'elenco in una visualizzazione temporanea.
{ begin, end } Yes No begin e end devono essere iteratori in avanti e *begin devono essere convertibili in T.

Di nuovo, la versione a doppio iteratore può essere usata per creare viste di vettore a partire da elementi che non rientrano in nessuna alternativa esistente. La visualizzazione temporanea è più efficiente se gli begin iteratori e end sono iteratori ad accesso casuale.

Alternative per i parametri di visualizzazione mappa

winrt::p aram::map_view<T> e winrt::p aram::async_map_view<T> semplificano il passaggio di parametri come IMapView<T>.

È possibile chiamare IMap<K, V>::GetView per ottenere una IMapView<K, V> a partire 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 Notes
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes Il contenuto viene spostato in una visualizzazione temporanea.
std::unordered_map<K, V> const& Yes No
std::unordered_map<K, V>&& Yes Yes Il contenuto viene spostato in una visualizzazione temporanea.
std::initializer_list<std::pair<K, V>> Yes Yes Il contenuto viene copiato in una visualizzazione temporanea. Le chiavi potrebbero non essere duplicate.

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 Notes
std::vector<T>& Il contenuto viene spostato in un vettore temporaneo. I risultati non vengono spostati indietro.
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 della mappa

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

È possibile passare Notes
std::map<K, V>&& Il contenuto viene spostato in una mappa temporanea. I risultati non vengono riportati indietro.
std::unordered_map<K, V>&& Il contenuto viene spostato in una mappa temporanea. I risultati non vengono riportati indietro.
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 si trova nello spazio dei nomi winrt::p aram , ma viene usato per i parametri che sono matrici di tipo C. Oltre a un array_view<T> esplicito, queste alternative vengono accettate anche:

Alternativa Notes
{} 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).

Vedere anche il post di blog I vari modelli per passare matrici di tipo C attraverso il limite ABI Windows Runtime.

  • Last updated on