Předávání parametrů do předpokládaných rozhraní API

Pro určité typy poskytuje C++/WinRT alternativní metody pro předání parametru do předpokládaného rozhraní API. Tyto třídy pro příjem parametrů jsou umístěny v winrt::p aram oboru názvů. Tyto třídy by měly používat pouze kód vygenerovaný jazykem C++/WinRT; nepoužívejte je ve vlastních funkcích a metodách.

Důležité

Typy v oboru názvů winrt::param byste neměli používat přímo. Jsou pro výhodu projekce.

Některé z těchto alternativ rozlišují mezi synchronními a asynchronními voláními. Verze asynchronních volání obvykle přebírá vlastnictví dat parametrů, aby se zajistilo, že hodnoty zůstanou platné a beze změny, dokud asynchronní volání nebude dokončeno. Upozorňujeme však, že tato ochrana se nevztahuje na změny kolekce z jiného vlákna. Je vaší odpovědností tomu zabránit.

Alternativy pro parametry řetězce

winrt::param::hstring zjednodušuje předávání parametrů typu winrt::hstring. Kromě winrt::hstring jsou také přijímány tyto alternativy:

Alternativa Notes
{} Prázdný řetězec.
std::wstring_view Za zobrazením musí následovat ukončovací znak null.
std::wstring
wchar_t const* Řetězec ukončený hodnotou null.

nullptr nelze předat jako reprezentaci prázdného řetězce. Místo toho použijte L"" nebo {}.

Kompilátor ví, jak vyhodnotit wcslen u řetězcových literálů během kompilace. Takže pro literály L"Name"sv a L"Name" jsou ekvivalentní.

Všimněte si, že objekty std::wstring_view nejsou ukončeny hodnotou null, ale C++/WinRT vyžaduje, aby znak za koncem zobrazení byl null. Pokud předáte std::wstring_view, který není ukončen znakem null, proces bude ukončen.

Alternativy pro iterovatelné parametry

winrt::param::iterable<T> a winrt::param::async_iterable<T> zjednodušují předávání parametrů ve formě IIterable<T>.

Kolekce prostředí Windows Runtime IVector<T> a IVectorView<T> již podporují IIterable<T>. Kolekce prostředí Windows Runtime IMap<K, V> a IMapView<K> již podporují IIterable<IKeyValuePair<K, V>>.

Kromě IIterable<T> jsou přijímány také následující alternativy. Upozorňujeme, že některé alternativy jsou k dispozici pouze pro synchronní metody.

Alternativa Synchronizace Async Notes
std::vector<T> const& Yes No
std::vector<T>&& Yes Yes Obsah je přesunut do dočasného iterovatelného objektu.
std::initializer_list<T> Yes Yes Asynchronní verze zkopíruje položky.
std::initializer_list<U> Yes No U musí být sklápěcí na T.
{ begin, end } Yes No begin a end musí být dopředné iterátory a *begin musí být převoditelný na T.

Dvojitý iterátor funguje obecněji pro případ, kdy máte kolekci, která neodpovídá žádnému z výše uvedených scénářů, pokud můžete iterovat a vytvářet věci, které se dají převést na T. Můžete mít například IVector<U> nebo std::vector<U>, kde U je konvertibilní na T.

V následujícím příkladu metoda SetStorageItems očekává IIterable<IStorageItem>. Vzor dvojitého iterátoru nám umožňuje předávat další typy kolekcí.

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

Pro případ IIterable<IKeyValuePair<K, V>> jsou přijímány následující alternativy. Upozorňujeme, že některé alternativy jsou k dispozici pouze pro synchronní metody.

Alternativa Synchronizace Async Notes
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes Obsah je dočasně přesunut do iterovatelného objektu.
std::unordered_map<K, V> const& Yes No
std::unordered_map<K, V>&&& Yes Yes Obsah se přesune do dočasné iterovatelné.
std::initializer_list<std::pair<K, V>> Yes Yes Asynchronní verze zkopíruje seznam do dočasné iterovatelné verze.
{ begin, end } Yes No begin a end musí být dopředné iterátory a begin->first a begin->second musí být převoditelné na K a V, v uvedeném pořadí.

Alternativy parametrů zobrazení vektoru

winrt::param::vector_view<T> a winrt::param::async_vector_view<T> zjednodušují předávání parametrů ve formě IVectorView<T>.

Pomocí IVector<T>::GetView můžete získat objekt IVectorView<T> z objektu IVector<T>.

Kromě IVectorView<T> jsou také přijímány následující alternativy. Upozorňujeme, že některé alternativy jsou k dispozici pouze pro synchronní metody.

Alternativa Synchronizace Async Notes
std::vector<T> const& Yes No
std::vector<T>&& Yes Yes Obsah se přesune do dočasného zobrazení.
std::initializer_list<T> Yes Yes Asynchronní verze zkopíruje seznam do dočasného zobrazení.
{ begin, end } Yes No begin a end musí být dopředné iterátory a *begin musí být převoditelný na T.

Verze dvojitého iterátoru se dá znovu použít k vytvoření vektorových zobrazení z věcí, které neodpovídají stávající alternativě. Dočasné zobrazení je efektivnější, pokud jsou iterátory begin a end iterátory s náhodným přístupem.

Alternativy parametrů zobrazení mapy

winrt::param::map_view<T> a winrt::param::async_map_view<T> zjednodušují předávání parametrů jako IMapView<T>.

Můžete volat IMap<K, V>::GetView k získání IMapView<K, V> z IMap<K, V>.

Kromě IMapView<K, V> jsou také přijímány následující alternativy. Upozorňujeme, že některé alternativy jsou k dispozici pouze pro synchronní metody.

Alternativa Synchronizace Async Notes
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes Obsah se přesune do dočasného zobrazení.
std::unordered_map<K, V> const& Yes No
std::unordered_map<K, V>&&& Yes Yes Obsah se přesune do dočasného zobrazení.
std::initializer_list<std::pair<K, V>> Yes Yes Obsah se zkopíruje do dočasného zobrazení. Klíče nemusí být duplikované.

Alternativy pro parametry vektoru

winrt::param::vector<T> zjednodušuje předávání parametrů ve formě IVector<T>. Kromě IVector<T> jsou také přijímány tyto alternativy:

Alternativa Notes
std::vector<T>&& Obsah se přesune do dočasného vektoru. Výsledky se nepřesunou zpět.
std::initializer_list<T>

Pokud metoda změní dočasný vektor, pak se tyto změny nepromítnou do původních parametrů. Pokud chcete sledovat změny, předejte IVector<T>.

Alternativy pro parametry mapy

winrt::param::map<K, V> zjednodušuje předávání parametrů ve formě IMap<K, V>. Kromě IMap<K, V, tyto> alternativy jsou také přijímány:

Můžete předat Notes
std::map<K, V>&& Obsah se přesune do dočasné mapy. Výsledky se nepřesunou zpět.
std::unordered_map<K, V>&&& Obsah se přesune do dočasné mapy. Výsledky se nepřesunou zpět.
std::initializer_list<std::pair<K, V>>

Pokud metoda upraví dočasnou mapu, pak se tyto změny neprojeví v původních parametrech. Pokud chcete sledovat změny, předejte IMap<K, V>.

Alternativy parametrů pole

winrt::array_view<T> není v oboru názvů winrt::param, ale používá se pro parametry představované poli ve stylu jazyka C. Kromě explicitního array_view<T> jsou také přijímány tyto alternativy:

Alternativa Notes
{} Prázdné pole.
U[] Pole ve stylu jazyka C, kde U je konvertibilní na T a sizeof(U) == sizeof(T).
std::array<U, N> Kde U je sklápěcí na T a sizeof(U) == sizeof(T).
std::vector<U> Kde U je sklápěcí na T a sizeof(U) == sizeof(T).
{ begin, end } begin a end musí být typu T*, který představuje rozsah [begin, end).
std::initializer_list<T>
std::span<U, N> Kde U je sklápěcí na T a sizeof(U) == sizeof(T).

Podívejte se také na blogový příspěvek Různé vzory pro předávání polí ve stylu C přes hranice prostředí Windows Runtime ABI.

  • Last updated on