Übergeben von Parametern an projizierte APIs

Artikel
06/21/2024

Für bestimmte Typen stellt C++/WinRT alternative Methoden zum Übergeben eines Parameters an eine projizierte API bereit. Diese Parameter akzeptierenden Klassen werden im winrt::p aram-Namespace platziert. Nur C++/WinRT-generierter Code sollte diese Klassen verwenden; verwenden Sie diese nicht in Ihren eigenen Funktionen und Methoden.

Wichtig

Verwenden Sie nicht selbst die Typen im winrt::param-Namespace. Sie dienen der Projektion.

Einige dieser Alternativen unterscheiden zwischen synchronen und asynchronen Aufrufen. Die Version für asynchrone Aufrufe übernimmt in der Regel den Besitz der Parameterdaten, um sicherzustellen, dass die Werte gültig und unverändert bleiben, bis der asynchrone Aufruf abgeschlossen ist. Beachten Sie jedoch, dass dieser Schutz nicht auf Änderungen an der Sammlung von einem anderen Thread erweitert wird. Es liegt in Ihrer Verantwortung, das Mutieren zu verhindern.

Alternativen für Zeichenfolgenparameter

winrt::p aram::hstring vereinfacht das Übergeben von Parametern als winrt::hstring. Zusätzlich zu winrt::hstring werden diese Alternativen ebenfalls akzeptiert:

Alternative	Hinweise
`{}`	Eine leere Zeichenfolge.
std::wstring_view	Auf die Ansicht muss ein Null-Abschlusszeichen folgen.
std::wstring
wchar_t const*	Eine NULL-terminierte Zeichenfolge.

Sie können nicht nullptr übergeben, um die leere Zeichenkette darzustellen. Verwenden Sie stattdessen L"" oder {}.

Der Compiler kann zur Kompilierzeit wcslen für Zeichenfolgeliterale auswerten. Für Literale sind somit L"Name"sv und L"Name" äquivalent.

Beachten Sie, dass std::wstring_view-Objekte nicht mit Nullen enden, aber C++/WinRT verlangt, dass das Zeichen nach dem Ende der Ansicht eine Null ist. Wenn Sie eine std::wstring_view übergeben, die nicht NULL-terminiert ist, wird der Prozess beendet.

Alternativen für wiederholbare Parameter

winrt::param::iterable<T> und winrt::param::async_iterable<T> vereinfachen die Übergabe von Parametern als Iterable<T>.

Die Windows-Runtime-Auflistungen IVector<T> und IVectorView<T> unterstützen Iterable<T> bereits. Die Windows-Runtime-Auflistungen IMap<K, V> und IMapView <K, V> unterstützen Iterable<IKeyValuePair<K, V>> bereits.

Zusätzlich zu Iterable<T> werden auch die folgenden Alternativen akzeptiert. Beachten Sie, dass einige Alternativen nur für synchrone Methoden verfügbar sind.

Alternative	Sync	Async	Hinweise
std::vector<T> const&	Ja	No
std::vector<T>&&	Ja	Ja	Der Inhalt wird in eine temporäre Iterable verschoben.
std::initializer_list<T>	Ja	Ja	Die asynchrone Version kopiert die Objekte.
std::initializer_list<U>	Ja	Nein	U muss in T konvertierbar sein.
`{ begin, end }`	Ja	Nein	`begin` und `end` müssen Vorwärts-Iteratoren sein und `*begin` in T konvertierbar sein.

Die Version mit doppeltem Iterator eignet sich generell für Sammlungen, die nicht den oben genannten Szenarien entsprechen, solange Sie sie durchlaufen können und Elemente erzeugen, die sich in T konvertieren lassen. Sie können z. B. über einen IVector<U> oder std::vector<U> verfügen, wobei U in T konvertierbar ist.

Im folgenden Beispiel erwartet die Methode SetStorageItems ein IIterable<IStorageItem>. Mit dem Doppeliterator-Muster können wir andere Arten von Sammlungen übergeben.

// 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 den Fall von IIterable<IKeyValuePair<K, V>> werden die folgenden Alternativen akzeptiert. Beachten Sie, dass einige Alternativen nur für synchrone Methoden verfügbar sind.

Alternative	Sync	Async	Hinweise
std::map<K, V> const&	Ja	No
std::map<K, V>&&	Ja	Ja	Der Inhalt wird in eine temporäre Iterable verschoben.
std::unordered_map<K, V> const&	Ja	No
std::unordered_map<K, V>&&	Ja	Ja	Der Inhalt wird in eine temporäre Iterable verschoben.
std::initializer_list<std::pair<K, V>>	Ja	Ja	Die asynchrone Version kopiert die Liste in eine temporäre Iterable.
`{ begin, end }`	Ja	Nein	`begin` und `end` müssen Vorwärts-Iteratoren sein und `begin->first` `begin->second` müssen in K bzw. V konvertierbar sein.

Alternativen für Vektoransichtsparameter

winrt::param::vector_view<T> und winrt::param::async_vector_view<T> vereinfachen die Übergabe von Parametern als IVectorView<T>.

Sie können IVector<T>::GetView aufrufen, um eine IVectorView<T> von einem IVector<T> zu erhalten.

Neben IVectorView<T> werden auch die folgenden Alternativen akzeptiert. Beachten Sie, dass einige Alternativen nur für synchrone Methoden verfügbar sind.

Alternative	Sync	Async	Hinweise
std::vector<T> const&	Ja	No
std::vector<T>&&	Ja	Ja	Inhalte werden in eine temporäre Ansicht verschoben.
std::initializer_list<T>	Ja	Ja	Die asynchrone Version kopiert die Liste in eine temporäre Ansicht.
`{ begin, end }`	Ja	Nein	`begin` und `end` müssen Vorwärts-Iteratoren sein und `*begin` in T konvertierbar sein.

Auch hier kann die Doppeliterator-Version verwendet werden, um Vektoransichten aus Elementen zu erstellen, die nicht zu einer vorhandenen Alternative passen. Die temporäre Ansicht ist effizienter, wenn die begin und end- Interatoren zufälligen Zugriff haben.

Alternativen für Kartenansichtsparameter

winrt::param::map_view<T> und winrt::param::async_map_view<T> vereinfachen die Übergabe von Parametern IMapView<T>.

Sie können IMap<K, V>::GetView aufrufen, um eine IMapView<K, V> von einer IMap<K, V> zu erhalten.

Zusätzlich zu IMapView<K, V> werden auch die folgenden Alternativen akzeptiert. Beachten Sie, dass einige Alternativen nur für synchrone Methoden verfügbar sind.

Alternative	Sync	Async	Hinweise
std::map<K, V> const&	Ja	No
std::map<K, V>&&	Ja	Ja	Inhalte werden in eine temporäre Ansicht verschoben.
std::unordered_map<K, V> const&	Ja	No
std::unordered_map<K, V>&&	Ja	Ja	Inhalte werden in eine temporäre Ansicht verschoben.
std::initializer_list<std::pair<K, V>>	Ja	Ja	Inhalte werden in eine temporäre Ansicht kopiert. Schlüssel können nicht dupliziert werden.

Alternativen für Vektorparameter

winrt::p aram::vector<T> vereinfacht das Übergeben von Parametern als IVector<T>. Zusätzlich zu IVector<T> werden diese Alternativen ebenfalls akzeptiert:

Alternative	Hinweise
std::vector<T>&&	Inhalte werden in einen temporären Vektor verschoben. Die Ergebnisse werden nicht zurückgesetzt.
std::initializer_list<T>

Wenn die Methode den temporären Vektor verändert, werden diese Änderungen nicht in den ursprünglichen Parametern wiedergegeben. Um die Änderungen zu beobachten, übergeben Sie einen IVector<T>.

Alternativen für Kartenparameter

winrt::p aram::map<K, V> vereinfacht das Übergeben von Parametern als IMap<K, V>. Zusätzlich zu IMap<K, V> werden diese Alternativen ebenfalls akzeptiert:

Sie können weitergehen	Hinweise
std::map<K, V>&&	Inhalte werden in eine temporäre Zuordnung verschoben. Die Ergebnisse werden nicht zurück verschoben.
std::unordered_map<K, V>&&	Inhalte werden in eine temporäre Zuordnung verschoben. Die Ergebnisse werden nicht zurückgesetzt.
std::initializer_list<std::pair<K, V>>

Wenn die Methode die temporäre Zuordnung verändert, werden diese Änderungen nicht in den ursprünglichen Parametern wiedergegeben. Um die Änderungen zu beobachten, übergeben Sie eine IMap<K, V>.

Alternativen für Arrayparameter

winrt::array_view<T> liegt nicht im winrt::param-Namespace, wird aber für Parameter verwendet, die Arrays im C-Stil sind. Zusätzlich zu einem expliziten array_view<T> werden diese Alternativen ebenfalls akzeptiert:

Alternative	Hinweise
`{}`	Leeres Array.
U[]	Ein C-Stil-Array, bei dem U in T konvertierbar ist, und `sizeof(U) == sizeof(T)`.
std::array<U, N>	Wo U in T konvertierbar ist und `sizeof(U) == sizeof(T)`.
std::vector<U>	Wo U in T konvertierbar ist und `sizeof(U) == sizeof(T)`.
`{ begin, end }`	`begin` und `end` muss vom Typ T*sein, der den Bereich [`begin`, `end`) darstellt.
std::initializer_list<T>
std::span<U, N>	Wo U in T konvertierbar ist und `sizeof(U) == sizeof(T)`.

Weitere Informationen finden Sie im Blogbeitrag The various patterns for passing C-style arrays across the Windows Runtime ABI boundary (Die verschiedenen Muster für die Weitergabe von Arrays im C-Stil über die Windows-Runtime-ABI-Grenze).

Freigeben über