Meneruskan parameter ke API yang diproyeksikan

Untuk jenis tertentu, C++/WinRT menyediakan metode alternatif untuk meneruskan parameter ke API yang diproyeksikan. Kelas yang menerima parameter ini ditempatkan di namespace winrt::p aram . Hanya kode yang dihasilkan C++/WinRT yang harus menggunakan kelas ini; jangan gunakan dalam fungsi dan metode Anda sendiri.

Important

Anda sebaiknya tidak menggunakan tipe dalam namespace winrt::param secara langsung. Itu demi proyeksi.

Beberapa alternatif ini membedakan antara panggilan sinkron dan asinkron. Versi untuk panggilan asinkron biasanya mengambil kepemilikan data parameter untuk memastikan bahwa nilai tetap valid dan tidak berubah sampai panggilan asinkron selesai. Namun, perlu diperhatikan bahwa perlindungan ini tidak berlaku untuk perubahan pada koleksi yang dilakukan dari utas lain. Mencegah itu adalah tanggung jawab Anda.

Alternatif untuk parameter string

winrt::param::hstring menyederhanakan penerusan parameter sebagai winrt::hstring. Selain winrt::hstring, alternatif ini juga diterima:

Alternatif	Notes
{}	String kosong.
std::wstring_view	Tampilan harus diikuti oleh terminator null.
std::wstring
wchar_t const*	Sebuah string yang diakhiri dengan null.

Anda tidak dapat meneruskan nullptr untuk mewakili string kosong. Sebagai gantinya, gunakan L"" atau {}.

Kompiler tahu cara mengevaluasi wcslen pada literal string saat kompilasi. Jadi, untuk literal, L"Name"sv dan L"Name" setara.

Perhatikan bahwa objek std::wstring_view tidak diakhiri dengan null, tetapi C++/WinRT mengharuskan karakter setelah akhir tampilan tersebut berupa null. Jika Anda meneruskan std::wstring_view yang tidak diakhiri dengan null, proses akan dihentikan.

Alternatif untuk parameter yang dapat diulang

winrt::param::iterable<T> dan winrt::param::async_iterable<T> menyederhanakan penerusan parameter sebagai IIterable<T>.

Koleksi Windows Runtime IVector<T> dan IVectorView<T> sudah mendukung IIterable<T>. Koleksi Windows Runtime IMap<K, V> danIMapView<K, V> sudah mendukung IIterable<IKeyValuePair<K, V>>.

Selain IIterable<T>, alternatif berikut juga diterima. Perhatikan bahwa beberapa alternatif hanya tersedia untuk metode sinkron.

Alternatif	Sinkronisasi	Asinkron	Notes
std::vector<T> const&	Yes	No
std::vector<T>&&	Yes	Yes	Konten dipindahkan ke iterable sementara.
std::initializer_list<T>	Yes	Yes	Versi asinkron menyalin item.
std::initializer_list<U>	Yes	No	U harus dapat dikonversi ke T.
{ begin, end }	Yes	No	begin dan end harus berupa iterator maju, dan *begin harus dapat dikonversi ke T.

Iterator ganda bekerja lebih umum untuk kasus di mana Anda memiliki koleksi yang tidak sesuai dengan salah satu skenario di atas, selama Anda dapat melakukan iterasi di atasnya dan menghasilkan hal-hal yang dapat dikonversi ke T. Misalnya, Anda mungkin memiliki IVector<U> atau std::vector<U>, di mana U dapat dikonversi ke T.

Dalam contoh berikut, metode SetStorageItems mengharapkan IStorageItem< yang Dapat> Diubah. Pola iterator ganda memungkinkan kita meneruskan jenis koleksi lain.

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

Untuk IIterable<IKeyValuePair<K, V>>, alternatif berikut dapat diterima. Perhatikan bahwa beberapa alternatif hanya tersedia untuk metode sinkron.

Alternatif	Sinkronisasi	Asinkron	Notes
std::map<K, V> const&	Yes	No
std::map<K, V>&&	Yes	Yes	Isi dipindahkan ke iterable yang bersifat sementara.
std::unordered_map<K, V> const&	Yes	No
std::unordered_map<K, V>&&	Yes	Yes	Konten dipindahkan ke iterable sementara.
std::initializer_list<std::pair<K, V>>	Yes	Yes	Versi asinkron menyalin daftar ke dalam iterable temporer.
{ begin, end }	Yes	No	begin dan end harus berupa iterator maju, dan begin->first serta begin->second masing-masing harus dapat dikonversi menjadi K dan V.

Alternatif untuk parameter tampilan vektor

winrt::p aram::vector_view<T> dan winrt::p aram::async_vector_view<T> menyederhanakan parameter passing sebagai IVectorView<T>.

Anda dapat memanggil IVector<T>::GetView untuk mendapatkan IVectorView<T> dari IVector<T>.

Selain IVectorView<T>, alternatif berikut juga diterima. Perhatikan bahwa beberapa alternatif hanya tersedia untuk metode sinkron.

Alternatif	Sinkronisasi	Asinkron	Notes
std::vector<T> const&	Yes	No
std::vector<T>&&	Yes	Yes	Isi dipindahkan ke tampilan sementara.
std::initializer_list<T>	Yes	Yes	Versi asinkron menyalin daftar ke dalam tampilan sementara.
{ begin, end }	Yes	No	begin dan end harus berupa iterator maju, dan *begin harus dapat dikonversi ke T.

Sekali lagi, versi iterator ganda dapat digunakan untuk membuat tampilan vektor dari hal-hal yang tidak sesuai dengan alternatif yang ada. Tampilan sementara lebih efisien jika iterator begin dan end merupakan iterator akses acak.

Alternatif untuk parameter tampilan peta

winrt::p aram::map_view<T> dan winrt::p aram::async_map_view<T> menyederhanakan parameter passing sebagai IMapView<T>.

Anda dapat memanggil IMap<K, V>::GetView untuk mendapatkan IMapView<K, V> dari IMap<K, V>.

Selain IMapView<K, V>, alternatif berikut juga diterima. Perhatikan bahwa beberapa alternatif hanya tersedia untuk metode sinkron.

Alternatif	Sinkronisasi	Asinkron	Notes
std::map<K, V> const&	Yes	No
std::map<K, V>&&	Yes	Yes	Isi dipindahkan ke tampilan sementara.
std::unordered_map<K, V> const&	Yes	No
std::unordered_map<K, V>&&	Yes	Yes	Isi dipindahkan ke tampilan sementara.
std::initializer_list<std::pair<K, V>>	Yes	Yes	Isi disalin ke dalam tampilan sementara. Kunci mungkin tidak diduplikasi.

Alternatif untuk parameter vektor

winrt::param::vector<T> menyederhanakan penerusan parameter sebagai IVector<T>. Selain IVector<T>, alternatif ini juga diterima:

Alternatif	Notes
std::vector<T>&&	Konten dipindahkan ke vektor sementara. Hasil tidak dipindahkan kembali.
std::initializer_list<T>

Jika metode mengubah vektor sementara, maka perubahan tersebut tidak tercermin dalam parameter asli. Untuk mengamati perubahan, lewati IVector<T>.

Alternatif untuk parameter peta

winrt::param::map<K, V> menyederhanakan penerusan parameter sebagai IMap<K, V>. Selain IMap<K, V>, alternatif ini juga diterima:

Anda dapat lulus	Notes
std::map<K, V>&&	Isi dipindahkan ke peta sementara. Hasil tidak dipindahkan kembali.
std::unordered_map<K, V>&&	Isi dipindahkan ke peta sementara. Hasil tidak dipindahkan kembali.
std::initializer_list<std::pair<K, V>>

Jika metode mengubah peta sementara, maka perubahan tersebut tidak tercermin dalam parameter asli. Untuk mengamati perubahan, lewati IMap<K, V>.

Alternatif untuk parameter array

winrt::array_view<T> tidak berada dalam namespace winrt::param, tetapi digunakan untuk parameter yang berupa array bergaya C. Selain array_view<T> yang eksplisit, alternatif ini juga diterima:

Alternatif	Notes
{}	Array kosong.
U[]	Array gaya C, di mana U dapat dikonversi ke T, dan sizeof(U) == sizeof(T).
std::array<U, N>	Di mana U dapat dikonversi ke T, dan sizeof(U) == sizeof(T).
std::vector<U>	Di mana U dapat dikonversi ke T, dan sizeof(U) == sizeof(T).
{ begin, end }	begin dan end harus berjenis T*, mewakili rentang [begin, end).
std::initializer_list<T>
std::span<U, N>	Di mana U dapat dikonversi ke T, dan sizeof(U) == sizeof(T).

Lihat juga postingan blog Berbagai pola untuk meneruskan array gaya C melintasi batas ABI Windows Runtime.