Передача параметров в проецируемые API

Статья
11/16/2023

Для определенных типов C++/WinRT предоставляет альтернативные методы для передачи параметра в проецируемый API. Эти классы, принимающие параметры, помещаются в пространство имен winrt::p aram . Для использования этих классов следует использовать только созданный код C++/WinRT; Не используйте их в собственных функциях и методах.

Важно!

Не следует использовать типы в пространстве имен winrt::param самостоятельно. Они используются для проецирования.

Некоторые из этих альтернативных различий между синхронными и асинхронными вызовами. Версия асинхронных вызовов обычно владеет данными параметра, чтобы гарантировать, что значения остаются допустимыми и неизменными до завершения асинхронного вызова. Обратите внимание, что эта защита не распространяется на изменения коллекции из другого потока. Обеспечение защиты — это ваша задача.

Альтернативные варианты строковых параметров

winrt::p aram::hstring упрощает передачу параметров в виде winrt::hstring. Помимо winrt::hstring, эти альтернативные варианты также принимаются:

Альтернатива	Примечания.
`{}`	Пустая строка.
std::wstring_view	За представлением должен следовать терминатор NULL.
std::wstring
wchar_t const*	Строка с нулевым символом в конце.

Невозможно передать nullptr пустую строку. Используйте L"" или {}.

Компилятор знает, как обработать wcslen в строковых литералах во время компиляции. То есть для литералов L"Name"sv и L"Name" — это эквиваленты.

Обратите внимание, что объекты std::wstring_view не завершаются значением NULL, но C++/WinRT требует, чтобы символ после окончания представления был null. Если вы передадите объект std::wstring_view без нулевого символа в конце, процесс будет завершен.

Альтернативные варианты для итерируемых параметров

winrt::p aram::iterable T> и winrt::p aram::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	Асинхронная	Примечания.
std::vector<T> const&	Да	Нет
std::vector<T>&&>	Да	Да	Содержимое перемещается во временное итерируемое содержимое.
std::initializer_list<T>	Да	Да	Асинхронная версия копирует элементы.
std::initializer_list<U>	Да	Нет	Необходимо, чтобы U можно было преобразовать в T.
`{ begin, end }`	Да	Нет	`begin`итераторы `end` должны быть перенаправными итераторами и `*begin` должны быть преобразованы в T.

Двойный итератор работает чаще всего в случае, когда у вас есть коллекция, которая не соответствует любому из приведенных выше сценариев, если вы можете выполнить итерацию по нему и создать вещи, которые можно преобразовать в T. Например, у вас может быть IVector<U> или std::vector<U>, где U преобразуется в T.

В следующем примере метод Set служба хранилища Items ожидает IIterable<I служба хранилища Item>. Шаблон двойного итератора позволяет передавать другие типы коллекций.

// 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	Асинхронная	Примечания.
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`итераторы `endbegin->second` должны быть переадресованы и `begin->first` должны быть преобразованы в K и V соответственно.

Альтернативные варианты для параметров представления векторов

winrt::p aram::vector_view T> и winrt::p<aram::<async_vector_view T> упрощают передачу параметров в виде IVectorView<T>.

Вы можете вызвать IVector T>::GetView, чтобы получить IVectorView<<T> из IVector<T>.

Помимо IVectorView<T>, также принимаются следующие альтернативные варианты. Обратите внимание, что некоторые альтернативные варианты доступны только для синхронных методов.

Альтернатива	Sync	Асинхронная	Примечания.
std::vector<T> const&	Да	Нет
std::vector<T>&&>	Да	Да	Содержимое перемещается во временное представление.
std::initializer_list<T>	Да	Да	Асинхронная версия копирует список во временное представление.
`{ begin, end }`	Да	Нет	`begin`итераторы `end` должны быть перенаправными итераторами и `*begin` должны быть преобразованы в T.

Опять же, версию двойного итератора можно использовать для создания векторных представлений из вещей, которые не соответствуют существующей альтернативе. Временное представление более эффективно, если begin итераторы end являются итераторами случайного доступа.

Альтернативные варианты для параметров представления карты

winrt::p aram::map_view T> и winrt::p aram::async_map_view<<T> упрощают передачу параметров в виде IMapView<T>.

Вы можете вызвать IMap K, V>::GetView, чтобы получить IMapView<K, V из IMap<<K, V>>.

Помимо IMapView<K, V> также принимаются следующие альтернативные варианты. Обратите внимание, что некоторые альтернативные варианты доступны только для синхронных методов.

Альтернатива	Sync	Асинхронная	Примечания.
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::p aram::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::p<aram, но используется для параметров, которые являются массивами стилей C. Помимо явного array_view<T>, эти альтернативные варианты также принимаются:

Альтернатива	Примечания.
`{}`	Пустой массив.
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` должен иметь тип T*, представляющий диапазон [`begin`, `end`).
std::initializer_list<T>
std::span<U, N>	Где U преобразуется в T и `sizeof(U) == sizeof(T)`.

Кроме того, см. запись блога о разных шаблонах передачи массивов в стиле языка C через границы среды выполнения Windows ABI.