Skicka parametrar till projicerade API:er

För vissa typer tillhandahåller C++/WinRT alternativa metoder för att skicka en parameter till ett beräknat API. Dessa parameterbetagande klasser placeras i namnområdet winrt::p aram . Endast C++/WinRT-genererad kod bör använda dessa klasser. använd dem inte i dina egna funktioner och metoder.

Viktigt!

Du bör inte använda typerna i winrt::param namnutrymme själv. De är för att gynna projektionen.

Några av dessa alternativ skiljer mellan synkrona och asynkrona anrop. Versionen för asynkrona anrop tar vanligtvis ägarskap för parameterdata för att säkerställa att värdena förblir giltiga och oförändrade tills det asynkrona anropet har slutförts. Observera dock att det här skyddet inte omfattar ändringar i samlingen från en annan tråd. Att förhindra det är ditt ansvar.

Alternativ för strängparametrar

winrt::p aram::hstring förenklar överföring av parametrar som winrt::hstring. Förutom winrt::hstring accepteras även dessa alternativ:

Alternativ	Noteringar
{}	En tom sträng.
std::wstring_view	Vyn måste följas av en nollterminator.
std::wstring
wchar_t const*	En nollterminerad sträng.

Du kan inte skicka nullptr för att representera den tomma strängen. Använd L"" i stället eller {}.

Kompilatorn vet hur man ska utvärdera wcslen på strängliteraler under kompileringen. Så för literaler L"Name"sv och L"Name" är likvärdiga.

Observera att std::wstring_view objekt inte är null-avslutade, men C++/WinRT kräver att tecknet efter vyns slut är null. Om du skickar en std::wstring_viewsom inte avslutas med null, kommer processen att avslutas.

Alternativ för itererbara parametrar

winrt::param::iterable<T> och winrt::param::async_iterable<T> förenklar att skicka parametrar som IIterable<T>.

Windows Runtime-samlingarna IVector<T> och IVectorView<T> stöder redan IIterable<T>. Windows Runtime-samlingarna IMap<K, V> och IMapView<K, V> stöder redan IIterable<IKeyValuePair<K, V>>.

Förutom IIterable<T> accepteras även följande alternativ. Observera att vissa alternativ endast är tillgängliga för synkrona metoder.

Alternativ	Synkronisering	Asynkron	Noteringar
std::vector<T> const&	Ja	Nej
std::vector<T>&&	Ja	Ja	Innehållet flyttas till en tillfällig iterbar fil.
std::initializer_list<T>	Ja	Ja	Async-versionen kopierar elementen.
std::initializer_list<U>	Ja	Nej	U måste konverteras till T.
{ begin, end }	Ja	Nej	begin och end måste vara vidarebefordrande iteratorer, och *begin måste vara konvertibla till T.

Dubbel-iteratorn fungerar mer allmänt för det fall där du har en samling som inte passar något av scenarierna ovan, så länge du kan iterera över den och producera saker som kan konverteras till T. Du kan till exempel ha en IVector<U> eller std::vector<U>, där U kan konverteras till T.

I följande exempel förväntar sig metoden SetStorageItems en IIterable<IStorageItem>. Med dubbel iteratormönstret kan vi skicka andra typer av samlingar.

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

För IIterable<IKeyValuePair<K, V>> godkänns följande alternativ. Observera att vissa alternativ endast är tillgängliga för synkrona metoder.

Alternativ	Synkronisering	Asynkron	Noteringar
std::map<K, V> const&	Ja	Nej
std::map<K, V>&&	Ja	Ja	Innehållet flyttas till en tillfällig iterbar fil.
std::unordered_map<K, V> const&	Ja	Nej
std::unordered_map<K, V>&&	Ja	Ja	Innehållet flyttas till en tillfällig iterbar fil.
std::initializer_list<std::p air<K, V>>	Ja	Ja	Async-versionen kopierar listan till en tillfällig iterbar version.
{ begin, end }	Ja	Nej	begin och end måste vara vidarebefordrande iteratorer och begin->firstbegin->second måste vara konvertibla till K respektive V.

Alternativ för vektorvyparametrar

winrt::p aram::vector_view<T> och winrt::p aram::async_vector_view<T> förenklar överföringsparametrar som IVectorView<T>.

Du kan anropa IVector<T>::GetView för att hämta en IVectorView<T> från en IVector<T>.

Förutom IVectorView<T> godkänns även följande alternativ. Observera att vissa alternativ endast är tillgängliga för synkrona metoder.

Alternativ	Synkronisering	Asynkron	Noteringar
std::vector<T> const&	Ja	Nej
std::vector<T>&&	Ja	Ja	Innehållet flyttas till en tillfällig vy.
std::initializer_list<T>	Ja	Ja	Async-versionen kopierar listan till en tillfällig vy.
{ begin, end }	Ja	Nej	begin och end måste vara vidarebefordrande iteratorer, och *begin måste vara konvertibla till T.

Återigen kan dubbel iteratorversionen användas för att skapa vektorvyer av saker som inte passar ett befintligt alternativ. Den tillfälliga vyn är effektivare om begin iteratorerna och end är iteratorer med slumpmässig åtkomst.

Alternativ för kartvyparametrar

winrt::p aram::map_view<T> och winrt::p aram::async_map_view<T> förenklar överföring av parametrar som IMapView<T>.

Du kan anropa IMap<K, V>::GetView för att hämta en IMapView<K, V> från en IMap<K, V>.

Förutom IMapView<K, V>, accepteras även följande alternativ. Observera att vissa alternativ endast är tillgängliga för synkrona metoder.

Alternativ	Synkronisering	Asynkron	Noteringar
std::map<K, V> const&	Ja	Nej
std::map<K, V>&&	Ja	Ja	Innehållet flyttas till en tillfällig vy.
std::unordered_map<K, V> const&	Ja	Nej
std::unordered_map<K, V>&&	Ja	Ja	Innehållet flyttas till en tillfällig vy.
std::initializer_list<std::p air<K, V>>	Ja	Ja	Innehållet kopieras till en tillfällig vy. Det är förbjudet att kopiera nycklar.

Alternativ för vektorparametrar

winrt::param::vector<T> förenklar att skicka parametrar i form av IVector<T>. Förutom IVector<T> accepteras även dessa alternativ:

Alternativ	Noteringar
std::vector<T>&&	Innehållet flyttas till en tillfällig vektor. Resultaten flyttas inte tillbaka.
std::initializer_list<T>

Om metoden muterar den tillfälliga vektorn återspeglas inte dessa ändringar i de ursprungliga parametrarna. Om du vill observera ändringarna skickar du en IVector<T>.

Alternativ för kartparametrar

winrt::param::map<K, V> förenklar att skicka parametrar som IMap<K, V>. Förutom IMap<K, V>, accepteras även dessa alternativ:

Du kan passera	Noteringar
std::map<K, V>&&	Innehållet flyttas till en tillfällig karta. Resultaten flyttas inte tillbaka.
std::unordered_map<K, V>&&	Innehållet flyttas till en tillfällig karta. Resultaten flyttas inte tillbaka.
std::initializer_list<std::p air<K, V>>

Om metoden muterar den tillfälliga kartan återspeglas inte dessa ändringar i de ursprungliga parametrarna. Om du vill observera ändringarna skickar du en IMap<K, V>.

Alternativ för matrisparametrar

winrt::array_view<T> finns inte i namnområdet winrt::p aram , men det används för parametrar som är C-formatmatriser. Förutom en explicit array_view<T> godkänns även dessa alternativ:

Alternativ	Noteringar
{}	Tomt fält.
U[]	En matris i C-stil, där U är konvertibelt till T och sizeof(U) == sizeof(T).
std::array<U, N>	Där U är konvertibelt till T och sizeof(U) == sizeof(T).
std::vector<U>	Där U är konvertibelt till T och sizeof(U) == sizeof(T).
{ begin, end }	begin och end måste vara av typen T*, som representerar intervallet [begin, end).
std::initializer_list<T>
std::span<U, N>	Där U är konvertibelt till T och sizeof(U) == sizeof(T).

Se även blogginlägget De olika mönstren för att skicka C-formatmatriser över Windows Runtime ABI-gränsen.