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

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

Important

winrt::param 名前空間の型は自分では使用しないでください。 これらは、プロジェクションの利点を得るためのものになります。

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

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

winrt::p aram::hstring は、 winrt::hstring としてパラメーターを渡すのを簡略化します。 winrt::hstring に加えて、次の代替方法も受け入れられます。

代替案 Notes
{} 空の文字列。
std::wstring_view ビューの後に null 終端記号を付ける必要があります。
std::wstring
wchar_t const* null で終わる文字列。

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

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

std::wstring_view オブジェクトは null で終わるのではなく、C++/WinRT ではビューの末尾の後の文字が null である必要があることに注意してください。 null で終了しない std::wstring_view を渡すと、プロセスは終了します。

iterable パラメーターの代替手段

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>に加えて、次の代替手段も受け入れられます。 一部の代替方法は、同期メソッドでのみ使用できます。

代替案 Sync 非同期 Notes
std::vector<T> const& Yes No
std::vector<T>&& Yes Yes コンテンツは一時的な iterable に移動されます。
std::initializer_list<T> Yes Yes 非同期バージョンでは、項目がコピーされます。
std::initializer_list<U> Yes No U は T に変換できる必要があります。
{ begin, end } Yes No begin endは前方反復子である必要があり、*beginは T に変換できる必要があります。

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

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

代替案 Sync 非同期 Notes
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes コンテンツは一時的な iterable に移動されます。
std::unordered_map<K, V> const& Yes No
std::unordered_map<K,V>&& Yes Yes コンテンツは一時的な iterable に移動されます。
std::initializer_list<std::pair<K, V>> Yes Yes 非同期バージョンでは、リストが一時的な iterable にコピーされます。
{ begin, end } Yes No 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> に加えて、次の代替方法も受け入れられます。 一部の代替方法は、同期メソッドでのみ使用できます。

代替案 Sync 非同期 Notes
std::vector<T> const& Yes No
std::vector<T>&& Yes Yes コンテンツは一時ビューに移動されます。
std::initializer_list<T> Yes Yes 非同期バージョンでは、リストが一時ビューにコピーされます。
{ begin, end } Yes No 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> に加えて、次の代替手段も受け入れられます。 一部の代替方法は、同期メソッドでのみ使用できます。

代替案 Sync 非同期 Notes
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes コンテンツは一時ビューに移動されます。
std::unordered_map<K, V> const& Yes No
std::unordered_map<K,V>&& Yes Yes コンテンツは一時ビューに移動されます。
std::initializer_list<std::pair<K, V>> Yes Yes コンテンツは一時ビューにコピーされます。 キーが重複していない可能性があります。

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

winrt::param::vector<T> により、パラメーターを IVector<T> として簡単に渡せるようになります。 IVector<T> に加えて、次の代替手段も受け入れられます。

代替案 Notes
std::vector<T>&& コンテンツは一時ベクターに移動されます。 結果は元に戻されません。
std::initializer_list<T>

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

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

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

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

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

配列パラメーターの代替手段

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

代替案 Notes
{} 空の配列。
U[] C スタイルの配列。 U は T に変換でき、 sizeof(U) == sizeof(T)。
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 型である必要があります。
std::initializer_list<T>
std::span<U, N> ここで、U は T に変換でき、sizeof(U) == sizeof(T)。

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

  • Last updated on