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.

Penting

Anda tidak boleh menggunakan jenis di namespace winrt::p aram sendiri. Mereka untuk kepentingan 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, perhatikan bahwa perlindungan ini tidak meluas ke perubahan pada koleksi dari utas lain. Mencegah itu adalah tanggung jawab Anda.

Alternatif untuk parameter string

winrt::p aram::hstring menyederhanakan parameter passing sebagai winrt::hstring. Selain winrt::hstring, alternatif ini juga diterima:

Alternatif	Catatan
{}	Untai kosong.
std::wstring_view	Tampilan harus diikuti oleh terminator null.
std::wstring
wchar_t const*	String null-terminated.

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

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

Perhatikan bahwa objek std::wstring_view tidak dihentikan null, tetapi C++/WinRT mengharuskan karakter setelah akhir tampilan menjadi null. Jika Anda melewati std yang tidak dihentikan null::wstring_view, maka proses akan berakhir.

Alternatif untuk parameter yang dapat diulang

winrt::p aram::iterable T> and winrt::p aram::async_iterable<T> menyederhanakan parameter passing sebagai IIterable<T>.<

Windows Runtime koleksi IVector<T> dan IVectorView<T> sudah mendukung IIterable<T>. Windows Runtime koleksi IMap<K, V> dan IMapView<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	Catatan
std::vector<T> const&	Ya	Tidak
std::vector<T>&&	Ya	Ya	Konten dipindahkan ke iterable sementara.
std::initializer_list<T>	Ya	Ya	Versi asinkron menyalin item.
std::initializer_list<U>	Ya	Tidak	U harus dapat dikonversi ke T.
{ begin, end }	Ya	Tidak	begin dan end harus meneruskan iterator, 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 perulangan ganda memungkinkan kita melewati jenis koleksi lainnya.

// 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 kasus IKeyValuePair<K IIterable<, V>>, alternatif berikut diterima. Perhatikan bahwa beberapa alternatif hanya tersedia untuk metode sinkron.

Alternatif	Sinkronisasi	Asinkron	Catatan
std::map<K, V> const&	Ya	Tidak
std::map<K, V>&& &	Ya	Ya	Konten dipindahkan ke dalam iterable sementara.
std::unordered_map<K, V> const&	Ya	Tidak
std::unordered_map<K, V>&& &	Ya	Ya	Konten dipindahkan ke dalam iterable sementara.
std::initializer_list<std::p air<K, V>>	Ya	Ya	Versi asinkron menyalin daftar ke dalam iterable sementara.
{ begin, end }	Ya	Tidak	begin dan end harus meneruskan iterator, dan begin->first dan begin->second harus dikonversi ke K dan V, masing-masing.

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	Catatan
std::vector<T> const&	Ya	Tidak
std::vector<T>&&	Ya	Ya	Isi dipindahkan ke tampilan sementara.
std::initializer_list<T>	Ya	Ya	Versi asinkron menyalin daftar ke dalam tampilan sementara.
{ begin, end }	Ya	Tidak	begin dan end harus meneruskan iterator, 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 begin iterator dan end iterator adalah iterator akses acak.

Alternatif untuk parameter tampilan peta

winrt::p aram::map_view T> dan winrt::p aram::async_map_view<T> menyederhanakan parameter yang diteruskan 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	Catatan
std::map<K, V> const&	Ya	Tidak
std::map<K, V>&& &	Ya	Ya	Isi dipindahkan ke tampilan sementara.
std::unordered_map<K, V> const&	Ya	Tidak
std::unordered_map<K, V>&& &	Ya	Ya	Isi dipindahkan ke tampilan sementara.
std::initializer_list<std::p air<K, V>>	Ya	Ya	Isi disalin ke dalam tampilan sementara. Kunci mungkin tidak diduplikasi.

Alternatif untuk parameter vektor

winrt::p aram::vector<T> menyederhanakan parameter passing sebagai IVector<T>. Selain IVector<T>, alternatif ini juga diterima:

Alternatif	Catatan
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::p aram::map<K, V> menyederhanakan parameter passing sebagai IMap<K, V>. Selain IMap<K, V>, alternatif ini juga diterima:

Anda dapat lulus	Catatan
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::p air<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 ada di namespace winrt::p aram , tetapi digunakan untuk parameter yang merupakan array gaya C. Selain array_view<T> yang eksplisit, alternatif ini juga diterima:

Alternatif	Catatan
{}	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 posting blog Berbagai pola untuk melewati array gaya C di seluruh batas Windows Runtime ABI.