Parameters doorgeven aan verwachte API's

Voor bepaalde typen biedt C++/WinRT alternatieve methoden voor het doorgeven van een parameter aan een geprojecteerde API. Deze klassen die parameters accepteren, zijn geplaatst in de naamruimte winrt::param. Alleen door C++/WinRT gegenereerde code moet deze klassen gebruiken; gebruik ze niet in uw eigen functies en methoden.

Belangrijk

Je moet de typen in de winrt::param-naamruimte niet zelf gebruiken. Ze zijn ten behoeve van de projectie.

Sommige van deze alternatieve opties maken onderscheid tussen synchrone en asynchrone aanroepen. De versie voor asynchrone aanroepen neemt doorgaans het eigendom van de parametergegevens over om ervoor te zorgen dat de waarden geldig en ongewijzigd blijven totdat de asynchrone aanroep is voltooid. Houd er echter rekening mee dat deze beveiliging niet wordt uitgebreid naar wijzigingen in de verzameling vanuit een andere thread. Voorkomen dat dat uw verantwoordelijkheid is.

Alternatieven voor tekenreeksparameters

winrt::param::hstring vereenvoudigt het doorgeven van parameters als winrt::hstring. Naast winrt::hstring worden deze alternatieven ook geaccepteerd:

Alternatief Opmerkingen
{} Een lege tekenreeks.
std::wstring_view De weergave moet worden gevolgd door een null-eindteken.
std::wstring
wchar_t const* Een tekenreeks die door null is beëindigd.

U kunt nullptr niet doorgeven om de lege tekenreeks weer te geven. Gebruik in plaats daarvan L"" of {}.

De compiler weet hoe wcslen op string literals tijdens het compileren moet worden geëvalueerd. Dus voor letterlijke gegevens L"Name"sv en L"Name" zijn ze gelijkwaardig.

Houd er rekening mee dat std::wstring_view-objecten niet null-beëindigd zijn, maar C++/WinRT vereist dat het teken na het einde van de weergave een null is. Als u een niet-null-beëindigde std::wstring_view doorgeeft, wordt het proces beëindigd.

Alternatieven voor iterable parameters

winrt::param::iterable<T> en winrt::param::async_iterable<T> vereenvoudigen het doorgeven van parameters als IIterable<T>.

De Windows Runtime verzamelingen IVector<T> en IVectorView<T> bieden al ondersteuning voor IIterable<T>. De Windows Runtime verzamelingen IMap<K, V> en IMapView<K, V> bieden al ondersteuning voor IIterable<IKeyValuePair<K, V>>.

Naast IIterable<T> worden ook de volgende alternatieven geaccepteerd. Houd er rekening mee dat sommige alternatieven alleen beschikbaar zijn voor synchrone methoden.

Alternatief Sync Async Opmerkingen
std::vector<T> const& Yes No
std::vector<T>&& Yes Yes Inhoud wordt verplaatst naar een tijdelijke itereerbaar bestand.
std::initializer_list<T> Yes Yes De asynchrone versie kopieert de items.
std::initializer_list<U> Yes No U moet converteerbaar zijn naar T.
{ begin, end } Yes No begin en end moeten forward iterators zijn en *begin moet converteerbaar zijn naar een T.

De dubbele iterator werkt in het algemeen voor het geval u een verzameling hebt die niet past bij een van de bovenstaande scenario's, zolang u deze kunt herhalen en dingen kunt produceren die kunnen worden geconverteerd naar T. U hebt bijvoorbeeld een IVector<U> of std::vector<U>, waarbij U converteert naar T.

In het volgende voorbeeld verwacht de methode SetStorageItems een IIterable<IStorageItem>. Met het dubbele iteratorpatroon kunnen andere typen verzamelingen worden doorgegeven.

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

Voor het geval van IIterable<IKeyValuePair<K, V>>, worden de volgende alternatieven geaccepteerd. Houd er rekening mee dat sommige alternatieven alleen beschikbaar zijn voor synchrone methoden.

Alternatief Sync Async Opmerkingen
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes Inhoud wordt verplaatst naar een tijdelijke itereerbaar bestand.
std::unordered_map<K, V> const& Yes No
std::unordered_map<K, V>&& Yes Yes Inhoud wordt verplaatst naar een tijdelijke itereerbaar bestand.
std::initializer_list<std::pair<K, V>> Yes Yes De async-versie kopieert de lijst in een tijdelijke iterable.
{ begin, end } Yes No begin en end moeten voorwaartse iterators zijn, en begin->first en begin->second moeten respectievelijk converteerbaar zijn tot K en V.

Alternatieven voor vectorweergaveparameters

winrt::p aram::vector_view<T> en winrt::p aram::async_vector_view<T> vereenvoudigen het doorgeven van parameters als IVectorView<T>.

U kunt IVector<T>::GetView aanroepen om een IVectorView<T> op te halen van een IVector<T>.

Naast IVectorView<T> worden ook de volgende alternatieven geaccepteerd. Houd er rekening mee dat sommige alternatieven alleen beschikbaar zijn voor synchrone methoden.

Alternatief Sync Async Opmerkingen
std::vector<T> const& Yes No
std::vector<T>&& Yes Yes Inhoud wordt verplaatst naar een tijdelijke weergave.
std::initializer_list<T> Yes Yes Asynchrone versie kopieert de lijst naar een tijdelijke weergave.
{ begin, end } Yes No begin en end moeten forward iterators zijn en *begin moet converteerbaar zijn naar een T.

Ook hier kan de double-iterator-versie worden gebruikt om vectorweergaven te maken van dingen die niet passen bij een bestaand alternatief. De tijdelijke weergave is efficiënter wanneer de iteratoren begin en end iteratoren voor willekeurige toegang zijn.

Alternatieven voor kaartweergaveparameters

winrt::p aram::map_view<T> en winrt::p aram::async_map_view<T> vereenvoudigen het doorgeven van parameters als IMapView<T>.

U kunt IMap<K, V>::GetView aanroepen om een IMapView<K, V> op te halen van een IMap<K, V>.

Naast IMapView<K, V> worden ook de volgende alternatieven geaccepteerd. Houd er rekening mee dat sommige alternatieven alleen beschikbaar zijn voor synchrone methoden.

Alternatief Sync Async Opmerkingen
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes Inhoud wordt verplaatst naar een tijdelijke weergave.
std::unordered_map<K, V> const& Yes No
std::unordered_map<K, V>&& Yes Yes Inhoud wordt verplaatst naar een tijdelijke weergave.
std::initializer_list<std::pair<K, V>> Yes Yes Inhoud wordt gekopieerd naar een tijdelijke weergave. Sleutels worden mogelijk niet gedupliceerd.

Alternatieven voor vectorparameters

winrt::param::vector<T> vereenvoudigt het doorgeven van parameters als een IVector<T>. Naast IVector<T> worden deze alternatieven ook geaccepteerd:

Alternatief Opmerkingen
std::vector<T>&& De inhoud wordt verplaatst naar een tijdelijke vector. De resultaten worden niet teruggezet.
std::initializer_list<T>

Als de methode de tijdelijke vector muteert, worden deze wijzigingen niet doorgevoerd in de oorspronkelijke parameters. Als u de wijzigingen wilt bekijken, geeft u een IVector<T> door.

Alternatieven voor kaartparameters

winrt::param::map<K, V> vereenvoudigt het doorgeven van parameters in de vorm van IMap<K, V>. Naast IMap<K, V> worden deze alternatieven ook geaccepteerd:

U kunt doorgeven Opmerkingen
std::map<K, V>&& De inhoud wordt verplaatst naar een tijdelijke kaart. De resultaten worden niet teruggezet.
std::unordered_map<K, V>&& De inhoud wordt verplaatst naar een tijdelijke kaart. De resultaten worden niet teruggezet.
std::initializer_list<std::pair<K, V>>

Als de methode de tijdelijke map wijzigt, worden die wijzigingen niet weerspiegeld in de oorspronkelijke parameters. Om de wijzigingen te volgen, moet u een IMap<K, V> doorgeven.

Alternatieven voor matrixparameters

winrt::array_view<T> maakt geen deel uit van de naamruimte winrt::param, maar wordt gebruikt voor parameters die arrays in C-stijl zijn. Naast een expliciete array_view<T> worden deze alternatieven ook geaccepteerd:

Alternatief Opmerkingen
{} Lege array.
U[] Een C-stijlmatrix, waarbij U converteerbaar is naar T, en sizeof(U) == sizeof(T).
std::array<U, N> Waar U converteert naar T, en sizeof(U) == sizeof(T).
std::vector<U> Waar U converteert naar T, en sizeof(U) == sizeof(T).
{ begin, end } begin en end moet van het type T* zijn, dat het bereik [begin, end) vertegenwoordigt.
std::initializer_list<T>
std::span<U, N> Waar U converteert naar T, en sizeof(U) == sizeof(T).

Zie ook het blogbericht De verschillende patronen voor het doorgeven van C-stijl matrices over de Windows Runtime ABI-grens.

  • Last updated on