Parametreleri öngörülen API'lere geçirme

Belirli türler için C++/WinRT, bir parametreyi öngörülen API'ye geçirmek için alternatif yöntemler sağlar. Bu parametre kabul eden sınıflar winrt::p aram ad alanına yerleştirilir. Yalnızca C++/WinRT tarafından oluşturulan kod bu sınıfları kullanmalıdır; bunları kendi işlevlerinizde ve yöntemlerinizde kullanmayın.

Önemli

winrt::param ad alanındaki türleri kendiniz kullanmamalısınız. Bunlar projeksiyonun yararına.

Bu alternatiflerden bazıları eşzamanlı ve eşzamansız çağrıları birbirinden ayırır. Eşzamansız çağrılar için olan sürüm, değerlerin eşzamansız çağrı tamamlanana kadar geçerli kalmasını ve değişmemesini sağlamak amacıyla genellikle parametre verilerinin sahipliğini devralır. Ancak unutmayın ki bu koruma, başka bir iş parçacığından yapılan koleksiyon değişiklikleri için geçerli değildir. Bunu önlemek sizin sorumluluğunuzdadır.

Dize parametreleri için alternatifler

winrt::param::hstring, parametrelerin winrt::hstring olarak geçirilmesini basitleştirir. winrt::hstring'e ek olarak, bu alternatifler de kabul edilir:

Alternatif	Notes
{}	Boş bir dize.
std::wstring_view	Görünümün ardından bir null sonlandırıcı gelmelidir.
std::wstring
wchar_t const*	Null olarak sonlandırılan bir dize.

Boş diziyi temsil etmesi için nullptr geçiremezsiniz. Bunun yerine L"" veya {} kullanın.

Derleyici, wcslen ifadesini dize sabitleri üzerinde derleme zamanında nasıl değerlendireceğini bilir. Dolayısıyla, değişmez değerler için L"Name"sv ve L"Name" eşdeğerdir.

std::wstring_view nesnelerinin null olarak sonlandırılmadığını, ancak C++/WinRT'nin görünümün sonundan sonraki karakterin null olmasını gerektirdiğini unutmayın. std::wstring_view için null ile sonlandırılmamış bir değer geçirirseniz işlem sonlanır.

Yinelenebilir parametreler için alternatifler

winrt::param::iterable<T> ve winrt::param::async_iterable<T>, parametreleri IIterable<T> olarak geçirmeyi basitleştirir.

Windows Çalışma Zamanı koleksiyonları IVector<T> ve IVectorView<T>, IIterable<T'yi> zaten destekliyor. Windows Çalışma Zamanı koleksiyonları IMap<K, V> ve IMapView<K, V> zaten IIterable<IKeyValuePair<K, V'yi>> destekliyor.

IIterable<T'ye> ek olarak aşağıdaki alternatifler de kabul edilir. Bazı alternatiflerin yalnızca zaman uyumlu yöntemler için kullanılabildiğini unutmayın.

Alternatif	Sync	Async	Notes
std::vector<T> const&	Yes	No
std::vector<T>&	Yes	Yes	İçerik geçici bir yinelenebilir nesneye taşınır.
std::initializer_list<T>	Yes	Yes	Eşzamansız sürüm öğeleri kopyalar.
std::initializer_list<U>	Yes	No	U, T'ye dönüştürülebilir olmalıdır.
{ begin, end }	Yes	No	begin ve endileri yineleyiciler olmalı ve *beginT'ye dönüştürülebilir olmalıdır.

Çift yineleyici, yukarıdaki senaryoların hiçbirine uymayan bir koleksiyonunuz olduğu durumlarda daha genel olarak çalışır. Bunun üzerinde yineleme yapabilir ve T'ye dönüştürülebilecek şeyler üretebilirsiniz. Örneğin, U'un < dönüştürülebileceği bir < veya std::vector>U'nuz olabilir.

Aşağıdaki örnekte, SetStorageItems yöntemi IIterable<IStorageItem> bekler. Çift yineleyici kalıbı, diğer koleksiyon türlerini aktarabilmemizi sağlar.

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

IIterable<IKeyValuePair<K, V>> için aşağıdaki alternatifler kabul edilir. Bazı alternatiflerin yalnızca zaman uyumlu yöntemler için kullanılabildiğini unutmayın.

Alternatif	Sync	Async	Notes
std::map<K, V> const&	Yes	No
std::map<K, V>&&	Yes	Yes	İçerikler geçici bir yinelenebilir nesneye taşınır.
std::unordered_map<K, V> const&	Yes	No
std::unordered_map<K, V>&&	Yes	Yes	İçerikler geçici bir yinelenebilir nesneye taşınır.
std::initializer_list<std::pair<K, V>>	Yes	Yes	Eşzamansız sürüm, listeyi geçici bir yinelenebilir nesneye kopyalar.
{ begin, end }	Yes	No	begin ve endileri yineleyiciler olmalı ve begin->firstbegin->second sırasıyla K ve V'ye dönüştürülebilir olmalıdır.

Vektör görünümü parametreleri için alternatifler

winrt::p aram::vector_view<T> ve winrt::p aram::async_vector_view<T> , parametreleri IVectorView<T> olarak geçirmeyi basitleştirir.

Bir IVector<T> öğesinden IVectorView<T> almak için IVector<T>::GetView'u çağırabilirsiniz.

IVectorView<T'ye> ek olarak aşağıdaki alternatifler de kabul edilir. Bazı alternatiflerin yalnızca zaman uyumlu yöntemler için kullanılabildiğini unutmayın.

Alternatif	Sync	Async	Notes
std::vector<T> const&	Yes	No
std::vector<T>&	Yes	Yes	İçerikler geçici bir görünüme taşınır.
std::initializer_list<T>	Yes	Yes	Eşzamansız sürüm, listeyi geçici bir görünüme kopyalar.
{ begin, end }	Yes	No	begin ve endileri yineleyiciler olmalı ve *beginT'ye dönüştürülebilir olmalıdır.

Yine çift yineleyici sürümü, mevcut bir alternatife uymayan öğelerin dışında vektör görünümleri oluşturmak için kullanılabilir. Geçici görünüm, begin ve end yineleyicileri rastgele erişimli yineleyicilerse daha verimlidir.

Harita görünümü parametreleri için alternatifler

winrt::param::map_view<T> ve winrt::param::async_map_view<T>, parametrelerin IMapView<T> olarak geçirilmesini basitleştirir.

Bir IMap<K, V> nesnesinden IMapView<K, V> elde etmek için IMap<K, V>::GetView yöntemini çağırabilirsiniz.

IMapView<K, V'ye> ek olarak aşağıdaki alternatifler de kabul edilir. Bazı alternatiflerin yalnızca zaman uyumlu yöntemler için kullanılabildiğini unutmayın.

Alternatif	Sync	Async	Notes
std::map<K, V> const&	Yes	No
std::map<K, V>&&	Yes	Yes	İçerikler geçici bir görünüme taşınır.
std::unordered_map<K, V> const&	Yes	No
std::unordered_map<K, V>&&	Yes	Yes	İçerikler geçici bir görünüme taşınır.
std::initializer_list<std::pair<K, V>>	Yes	Yes	İçerikler geçici bir görünüme kopyalanır. Anahtarlar çoğaltılamayabilir.

Vektör parametreleri için alternatifler

winrt::param::vector<T>, parametrelerin IVector<T> olarak geçirilmesini basitleştirir. IVector<T'ye> ek olarak, bu alternatifler de kabul edilir:

Alternatif	Notes
std::vector<T>&	İçerikler geçici bir vektöre taşınır. Sonuçlar geri taşınmaz.
std::initializer_list<T>

Yöntem geçici vektörü değiştirirse, bu değişiklikler orijinal parametrelere yansımaz. Değişiklikleri gözlemlemek için bir IVector<T> iletin.

Harita parametreleri için alternatifler

winrt::param::map<K, V>, parametrelerin IMap<K, V> olarak geçirilmesini basitleştirir. IMap<K, V'ye> ek olarak, bu alternatifler de kabul edilir:

Geçebilirsiniz	Notes
std::map<K, V>&&	İçerikler geçici bir haritaya taşınır. Sonuçlar geri taşınmaz.
std::unordered_map<K, V>&&	İçerikler geçici bir haritaya taşınır. Sonuçlar geri taşınmaz.
std::initializer_list<std::pair<K, V>>

Yöntem geçici eşleme yapısını değiştirirse, bu değişiklikler orijinal parametrelere yansımaz. Değişiklikleri gözlemlemek için bir IMap<K, V geçirin>.

Dizi parametreleri için alternatifler

winrt::array_view<T>, winrt::param ad alanında yer almaz, ancak C stili diziler için parametre olarak kullanılır. Açık array_view<T'ye> ek olarak, bu alternatifler de kabul edilir:

Alternatif	Notes
{}	Boş dizi.
U[]	U'nun T'ye dönüştürülebildiği ve sizeof(U) == sizeof(T) olan C stili bir dizi.
std::array<U, N>	Burada U , T'ye dönüştürülebilir ve sizeof(U) == sizeof(T).
std::vector<U>	Burada U , T'ye dönüştürülebilir ve sizeof(U) == sizeof(T).
{ begin, end }	beginve end [, begin) aralığını temsil eden end türünde olmalıdır.
std::initializer_list<T>
std::span<U, N>	Burada U , T'ye dönüştürülebilir ve sizeof(U) == sizeof(T).

Ayrıca Windows Çalışma Zamanı ABI sınırını aşarken C tarzı dizileri aktarmaya yönelik farklı kalıpları ele alan blog gönderisine de göz atın.