Paraméterek átadása előre jelzett API-knak

Bizonyos típusok esetén a C++/WinRT alternatív módszereket biztosít egy paraméter kivetített API-nak való átadásához. Ezek a paraméter-elfogadó osztályok a winrt::p aram névtérbe kerülnek. Ezeket az osztályokat csak C++/WinRT által létrehozott kód használhatja; ne használja őket a saját függvényeiben és metódusaiban.

Fontos

Nem szabad közvetlenül használnia a winrt::param névtér típusait. A kivetítést szolgálják.

Ezek közül néhány megkülönbözteti a szinkron és az aszinkron hívásokat. Az aszinkron hívások verziója általában a paraméteradatok tulajdonjogát veszi át, hogy az értékek érvényesek és változatlanok maradjanak az aszinkron hívás befejezéséig. Vegye figyelembe azonban, hogy ez a védelem nem terjed ki egy másik szál gyűjteményének módosítására. Ennek megakadályozása az Ön felelőssége.

A sztringparaméterek alternatívái

winrt::param::hstring egyszerűbbé teszi a paraméterek winrt::hstring-ként való átadását. A winrt::hstring mellett ezek az alternatívák is elfogadhatók:

Alternatív megoldás	Notes
{}	Üres sztring.
std::wstring_view	A nézetet null terminátornak kell követnie.
std::wstring
wchar_t const*	Nullával lezárt karakterlánc.

A(z) nullptr nem adható át az üres sztring jelölésére. Ehelyett használja L"" vagy {}.

A fordító képes fordítási időben kiértékelni a wcslen karakterlánc-literálokat. Tehát a literálok esetében a L"Name"sv és a L"Name" egyenértékű.

Vegye figyelembe, hogy az std::wstring_view objektumok nem null értékűek, de a C++/WinRT megköveteli, hogy a nézet vége utáni karakter null értékű legyen. Ha egy nem nullával lezárt std::wstring_view objektumot ad át, a folyamat leáll.

Az iteráló paraméterek alternatívái

winrt::param::iterable<T> és winrt::param::async_iterable<T> leegyszerűsítik a paraméterek IIterable<T>-ként való átadását.

Az IVector<T> és az IVectorView<T> Windows-futtatókörnyezet gyűjtemények már támogatják az IIterable<T-t>. A Windows-futtatókörnyezet IMap<K, V> és IMapView<K, V> gyűjteményei már támogatják a(z) IIterable<IKeyValuePair<K, V>> felületet.

Az IIterable<T> mellett a következő alternatívák is elfogadhatók. Vegye figyelembe, hogy egyes alternatívák csak szinkron metódusokhoz érhetők el.

Alternatív megoldás	Szinkronizálás	Async	Notes
std::vector<T> const&	Yes	No
std::vector<T>&&	Yes	Yes	A tartalmak egy ideiglenes iterálható objektumba kerülnek át.
std::initializer_list<T>	Yes	Yes	Az aszinkron verzió átmásolja az elemeket.
std::initializer_list<U>	Yes	No	U-nak T-vé konvertálhatónak kell lennie.
{ begin, end }	Yes	No	begin és endtovábbító iterátoroknak kell lenniük, és *beginT-vé kell konvertálni.

A dupla iterátor általánosabban működik abban az esetben, ha olyan gyűjteménye van, amely nem felel meg a fenti forgatókönyveknek, mindaddig, amíg át tudja iterálni, és olyan dolgokat hoz létre, amelyek átalakíthatók T-vé. Lehet például egy IVector<U> vagy std::vector<U>, ahol az UT-re konvertálható.

Az alábbi példában a SetStorageItems metódus egy IIterable<IStorageItem-et> vár. A dupla iterátorminta lehetővé teszi, hogy más típusú gyűjteményeket is átadjunk.

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

Az IIterable<IKeyValuePair<K, V>> esetében a következő alternatívákat fogadjuk el. Vegye figyelembe, hogy egyes alternatívák csak szinkron metódusokhoz érhetők el.

Alternatív megoldás	Szinkronizálás	Async	Notes
std::map<K, V> const&	Yes	No
std::map<K, V>&&	Yes	Yes	A tartalmak egy ideiglenes iterálható objektumba kerülnek.
std::unordered_map<K, V> const&	Yes	No
std::unordered_map<K, V>&&	Yes	Yes	A tartalom egy ideiglenes iterálóba kerül.
std::initializer_list<std::pair<K, V>>	Yes	Yes	Az aszinkron verzió egy ideiglenes iterálóba másolja a listát.
{ begin, end }	Yes	No	begin és end elemeknek előreiterátoroknak kell lenniük, továbbá begin->first és begin->second elemeknek sorrendben K, illetve V típusra konvertálhatónak kell lenniük.

A vektornézet paramétereinek alternatívái

winrt::param::vector_view<T> és winrt::param::async_vector_view<T> egyszerűsíti a paraméterek IVectorView<T> típusúként való átadását.

Az IVector<T>::GetView hívásával lekérhet egy IVectorView<T>-t egy IVector<T> objektumból.

Az IVectorView<T> mellett a következő alternatívákat is elfogadjuk. Vegye figyelembe, hogy egyes alternatívák csak szinkron metódusokhoz érhetők el.

Alternatív megoldás	Szinkronizálás	Async	Notes
std::vector<T> const&	Yes	No
std::vector<T>&&	Yes	Yes	A tartalom ideiglenes nézetbe kerül.
std::initializer_list<T>	Yes	Yes	Az aszinkron verzió ideiglenes nézetbe másolja a listát.
{ begin, end }	Yes	No	begin és endtovábbító iterátoroknak kell lenniük, és *beginT-vé kell konvertálni.

A dupla iterátorverzióval olyan vektornézetek hozhatók létre, amelyek nem felelnek meg egy meglévő alternatívának. Az ideiglenes nézet hatékonyabb, ha a begin és end iterátorok véletlen elérésű iterátorok.

A térképnézet paramétereinek alternatívái

winrt::param::map_view<T> és winrt::param::async_map_view<T> leegyszerűsítik a paraméterek IMapView<T>-ként történő átadását.

Az IMap<K, V> objektumból az IMap<K, V>::GetView meghívásával egy IMapView<K, V> kérhető le.

Az IMapView<K, V> mellett a következő alternatívák is elfogadhatók. Vegye figyelembe, hogy egyes alternatívák csak szinkron metódusokhoz érhetők el.

Alternatív megoldás	Szinkronizálás	Async	Notes
std::map<K, V> const&	Yes	No
std::map<K, V>&&	Yes	Yes	A tartalom ideiglenes nézetbe kerül.
std::unordered_map<K, V> const&	Yes	No
std::unordered_map<K, V>&&	Yes	Yes	A tartalom ideiglenes nézetbe kerül.
std::initializer_list<std::pair<K, V>>	Yes	Yes	A rendszer a tartalmat ideiglenes nézetbe másolja. Előfordulhat, hogy a kulcsok nem duplikálhatók.

A vektorparaméterek alternatívái

winrt::param::vector<T> megkönnyíti a paraméterek IVector<T> típusként történő átadását. Az IVector<T> mellett ezek az alternatívák is elfogadhatók:

Alternatív megoldás	Notes
std::vector<T>&&	A tartalom ideiglenes vektorba kerül. Az eredmények nem lesznek visszahelyezve.
std::initializer_list<T>

Ha a metódus az ideiglenes vektort mutálja, akkor ezek a változások nem jelennek meg az eredeti paraméterekben. A változások megfigyeléséhez adjon át egy IVector<T> vektort.

A térképparaméterek alternatívái

winrt::param::map<K, V> egyszerűbbé teszi a paraméterek IMap<K, V> való átadását. Az IMap<K, V> mellett ezek az alternatívák is elfogadhatók:

Átadhatja	Notes
std::map<K, V>&&	A tartalom ideiglenes térképre kerül. Az eredmények nem helyeződnek vissza.
std::unordered_map<K, V>&&	A tartalom ideiglenes térképre kerül. Az eredmények nem helyeződnek vissza.
std::initializer_list<std::pair<K, V>>

Ha a metódus az ideiglenes térképet mutálja, akkor ezek a módosítások nem jelennek meg az eredeti paraméterekben. A változások megfigyeléséhez adjon át egy IMap<K, V> protokollt.

A tömbparaméterek alternatívái

winrt::array_view<A T> nincs a winrt::p aram névtérben, de C stílusú tömbök paramétereihez használatos. Az explicit array_view<T> mellett ezek az alternatívák is elfogadottak:

Alternatív megoldás	Notes
{}	Üres tömb.
U[]	Egy C stílusú tömb, ahol az UT-vé konvertálható, és sizeof(U) == sizeof(T).
std::array<U, N>	Ahol az UT-vé konvertálható, és sizeof(U) == sizeof(T).
std::vector<U>	Ahol az UT-vé konvertálható, és sizeof(U) == sizeof(T).
{ begin, end }	begin és endT* típusúnak kell lennie, amely az [begin, end) tartományt jelöli.
std::initializer_list<T>
std::span<U, N>	Ahol az UT-vé konvertálható, és sizeof(U) == sizeof(T).

Lásd még ezt a blogbejegyzést: A C stílusú tömbök Windows-futtatókörnyezet ABI-határon keresztüli átadásának különböző mintái.