投影された API にパラメーターを渡す

C++/WinRT には、特定の型について、投影された API にパラメーターを渡すための代替メソッドが用意されています。 これらのパラメーター受け入れクラスは、winrt::param 名前空間に配置されます。 C++/WinRT で生成されたコードのみがこれらのクラスを使用するようにする必要があります。独自の関数やメソッドでは使用しないでください。

重要

winrt::param 名前空間内の型を自分では使用しないでください。 それらはプロジェクションのためのものです。

これらの代替の一部は、同期と非同期の呼び出しを区別します。 非同期呼び出しのバージョンは通常、パラメーター データの所有権を取得して、非同期呼び出しが完了するまで値が有効で変更されないまま維持されるようにします。 ただし、この保護は、別のスレッドからのコレクションへの変更には拡張されないことに注意してください。 その防止は、開発者が行う必要があります。

文字列パラメーターの代替

winrt::param::hstring は、パラメーターの引き渡しを winrt::hstring に簡素化します。 winrt::hstring に加えて、次の代替も受け入れられます。

代替手段	メモ
{}	空の文字列。
std::wstring_view	view の後に null 終端記号を付ける必要があります。
std::wstring
wchar_t const*	null で終わる文字列。

空の文字列を表すために nullptr を渡すことはできません。 代わりに、L"" または {} を使用します。

コンパイラでは、コンパイル時に文字列リテラルで wcslen を評価する方法が認識されています。 したがって、リテラルの場合、L"Name"sv と L"Name" は同等です。

std::wstring_view オブジェクトは null で終了しませんが、C++/WinRT は、view の末尾の後の文字が null であることを必要とします。 null で終了していない std::wstring_view を渡した場合、プロセスは終了します。

反復可能パラメーターの代替

winrt::param::iterable<T> と winrt::param::async_iterable<T> は、パラメーターの引き渡しを IIterable<T> に簡素化します。

Windows ランタイム コレクション IVector<T> と IVectorView<T> は既に IIterable<T> をサポートしています。 Windows ランタイム コレクション IMap<K, V> と IMapView<K, V> は既に IIterable<IKeyValuePair<K, V>> をサポートしています。

IIterable<T> に加えて、次の代替も受け入れられます。 一部の代替は、同期メソッドでのみ使用できます。

代替手段	同期	非同期	メモ
std::vector<T> const&	はい	いいえ
std::vector<T>&&	はい	はい	コンテンツは一時的な反復可能オブジェクトに移動されます。
std::initializer_list<T>	はい	はい	非同期バージョンは、項目をコピーします。
std::initializer_list<U>	はい	いいえ	U は T に変換できる必要があります。
{ begin, end }	はい	いいえ	begin と end は、前方反復子である必要があり、*begin は T に変換できる必要があります。

上記のどのシナリオにも適合しないコレクションがある場合、コレクションを反復処理して T に変換できるものを生成できるなら、二重反復子でさらに一般的に処理できます。たとえば、U を T に変換できる IVector<U> または std::vector<U> がある場合が考えられます。

次の例では、SetStorageItems メソッドは IIterable<IStorageItem> を予期します。 二重反復子パターンを使用すると、他の種類のコレクションを渡すことができます。

// 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>> の場合、次の代替が受け入れられます。 一部の代替は、同期メソッドでのみ使用できます。

代替手段	同期	非同期	メモ
std::map<K, V> const&	はい	いいえ
std::map<K, V>&&	はい	はい	コンテンツは一時的な反復可能オブジェクトに移動されます。
std::unordered_map<K, V> const&	はい	いいえ
std::unordered_map<K, V>&&	はい	はい	コンテンツは一時的な反復可能オブジェクトに移動されます。
std::initializer_list<std::pair<K, V>>	はい	はい	非同期バージョンでは、リストが一時的な反復可能オブジェクトにコピーされます。
{ begin, end }	はい	いいえ	begin と end は、前方反復子である必要があり、begin->first と begin->second は K と V にそれぞれ変換できる必要があります。

ベクトル ビュー パラメーターの代替

winrt::param::vector_view<T> と winrt::param::async_vector_view<T> は、パラメーターの引き渡しを IVectorView<T> に簡素化します。

IVector<T>.GetView を呼び出して、IVector<T> から IVectorView<T> を取得できます。

IVectorView<T> に加えて、次の代替も受け入れられます。 一部の代替は、同期メソッドでのみ使用できます。

代替手段	同期	非同期	メモ
std::vector<T> const&	はい	いいえ
std::vector<T>&&	はい	はい	コンテンツは一時的なビューに移動されます。
std::initializer_list<T>	はい	はい	非同期バージョンでは、リストが一時的なビューにコピーされます。
{ begin, end }	はい	いいえ	begin と end は、前方反復子である必要があり、*begin は T に変換できる必要があります。

ここでも、二重反復子バージョンを使用して、既存の代替に適合しないものからベクトル ビューを作成できます。 begin と end 反復子がランダム アクセス反復子の場合は、一時的なビューの方が効率的です。

マップ ビュー パラメーターの代替

winrt::param::map_view<T> と winrt::param::async_map_view<T> は、パラメーターの引き渡しを IMapView<T> に簡素化します。

IMap<K, V>::GetView を呼び出して、IMap<K, V> から IMapView<K, V> を取得できます。

IMapView<K, V> に加えて、次の代替も受け入れられます。 一部の代替は、同期メソッドでのみ使用できます。

代替手段	同期	非同期	メモ
std::map<K, V> const&	はい	いいえ
std::map<K, V>&&	はい	はい	コンテンツは一時的なビューに移動されます。
std::unordered_map<K, V> const&	はい	いいえ
std::unordered_map<K, V>&&	はい	はい	コンテンツは一時的なビューに移動されます。
std::initializer_list<std::pair<K, V>>	はい	はい	コンテンツは一時的なビューにコピーされます。 キーが重複することはできません。

ベクトル パラメーターの代替

winrt::param::vector<T> は、パラメーターの引き渡しを IVector<T> に簡素化します。 IVector<T> に加えて、次の代替も受け入れられます。

代替手段	メモ
std::vector<T>&&	コンテンツは一時的なベクトルに移動されます。 結果が元に戻されることはありません。
std::initializer_list<T>

メソッドが一時ベクトルを変更しても、それらの変更は元のパラメーターには反映されません。 変更を観測するには、IVector<T> を渡します。

マップ パラメーターの代替

winrt::p aram::map<K, V> は、パラメーターの受け渡しを IMap<K, V> に簡素化します。 IMap<K, V> に加えて、次の代替も受け入れられます。

渡すことができる内容	メモ
std::map<K, V>&&	コンテンツは一時的なマップに移動されます。 結果が元に戻されることはありません。
std::unordered_map<K, V>&&	コンテンツは一時的なマップに移動されます。 結果が元に戻されることはありません。
std::initializer_list<std::pair<K, V>>

メソッドが一時マップを変更しても、それらの変更は元のパラメーターには反映されません。 変更を観測するには、IMap<K, V> を渡します。

配列パラメーターの代替

winrt::array_view<T> は winrt::param 名前空間内にありませんが、C スタイルの配列であるパラメーターに使用されます。 明示的な array_view<T> に加えて、次の代替も受け入れられます。

代替手段	メモ
{}	空の配列です。
U[]	U を T に変換でき、sizeof(U) == sizeof(T) である C スタイルの配列です。
std::array<U, N>	ここで、U は T に変換でき、sizeof(U) == sizeof(T) です。
std::vector<U>	ここで、U は T に変換でき、sizeof(U) == sizeof(T) です。
{ begin, end }	begin と end は、範囲 [begin, end) を表す型 T* である必要があります。
std::initializer_list<T>
std::span<U, N>	ここで、U は T に変換でき、sizeof(U) == sizeof(T) です。

また、ブログ記事「Windows ランタイム ABI 境界全体で C スタイルの配列を渡すためのさまざまなパターン」も参照してください。