매개 변수를 ABI 경계로 전달Passing parameters into the ABI boundary

winrt::param 네임스페이스의 형식을 사용하여 C++/WinRT는 일반적인 경우에 대한 자동 변환을 제공하여 매개 변수를 ABI 경계에 전달하는 것을 단순화합니다.With the types in the winrt::param namespace, C++/WinRT simplifies passing parameters into the ABI boundary by providing automatic conversions for common cases. 문자열 처리표준 C++ 데이터 형식 및 C++/WinRT에서 자세한 내용과 코드 예제를 볼 수 있습니다.You can see more details, and code examples, in String handling and Standard C++ data types and C++/WinRT.

중요

winrt::param 네임스페이스에서 형식을 직접 사용하지 않도록 해야 합니다.You shouldn't use the types in the winrt::param namespace yourself. 이는 프로젝션의 이점을 위한 것입니다.They're for the benefit of the projection.

많은 형식이 동기 버전과 비동기 버전으로 제공됩니다.Many types come in both synchronous and asynchronous versions. C++/WinRT는 매개 변수가 동기 메서드에 전달되는 경우에는 동기 버전을 사용하고 매개 변수가 비동기 메서드에 전달되는 경우에는 비동기 버전을 사용합니다.C++/WinRT uses the synchronous version when you're passing a parameter to a synchronous method; it uses the asynchronous version when you're passing a parameter to an asynchronous method. 비동기 버전에서는 작업이 완료되기 전에 호출자가 컬렉션을 변경하기 어렵게 하기 위해 추가적인 단계를 수행합니다.The asynchronous version takes extra steps to make it harder for the caller to mutate the collection before the operation has completed. 그러나 어떠한 변형도 다른 스레드에서 컬렉션이 변경되는 것을 막지는 못합니다.Note, however, that none of the variants protect against the collection being mutated from another thread. 이를 방지하는 것은 사용자의 책임입니다.Preventing that is your responsibility.

문자열 매개 변수String parameters

winrt::param::hstringHSTRING을 사용하는 API로의 매개 변수 전달을 간소화합니다.winrt::param::hstring simplifies passing parameters to APIs that take HSTRING.

전달할 수 있는 형식Types that you can pass 참고Notes
{} 빈 문자열을 전달합니다.Passes empty string.
winrt::hstringwinrt::hstring
std::wstring_viewstd::wstring_view 리터럴의 경우 L"Name"sv를 작성할 수 있습니다.For literals, you can write L"Name"sv. 보기는 끝 부분 뒤에 null 종결자가 있어야 합니다.The view must have a null terminator after the end.
std::wstringstd::wstring -
wchar_t const*wchar_t const* null로 끝나는 문자열입니다.A null-terminated string.

nullptr은 허용되지 않습니다.nullptr is not allowed. 대신 {}를 사용하세요.Use {} instead.

컴파일러는 컴파일 시 문자열 리터럴에서 wcslen을 평가하는 방법을 알고 있습니다.The compiler knows how to evaluate wcslen on string literals at compile time. 따라서 리터럴의 경우 L"Name"svL"Name"은 동일합니다.So, for literals, L"Name"sv and L"Name" are equivalent.

std::wstring_view 개체는 null로 끝나지 않지만 C++WinRT에서는 문자열 끝의 뒤에 오는 문자가 null이어야 합니다.Note that std::wstring_view objects are not null terminated, but C++/WinRT requires that the character after the end of the string be a null. null로 끝나지 않는 std::wstring_view를 전달하면 프로세스가 종료됩니다.If you pass a non-null-terminated std::wstring_view, then the process will terminate.

반복 가능한 매개 변수Iterable parameters

winrt::param::iterable<T>winrt::param::async_iterable<T>IIterable<T> 를 사용하는 API로의 매개 변수 전달을 간소화합니다.winrt::param::iterable<T> and winrt::param::async_iterable<T> simplify passing parameters to APIs that take IIterable<T>.

Windows 런타임 컬렉션은 이미 IIterable입니다.Windows Runtime collections are already IIterable.

전달할 수 있는 형식Types that you can pass SyncSync AsyncAsync 참고Notes
nullptr Yes Yes 기본 메서드에서 nullptr을 지원하는지 확인해야 합니다.You must verify that the underlying method supports nullptr.
IIterable<T>IIterable<T> Yes Yes 또는 모든 항목을 변환할 수 있습니다.Or anything convertible to it.
std::vector<T> const&std::vector<T> const& Yes 아니오No
std::vector<T>&&std::vector<T>&& Yes Yes 변경되지 않도록 콘텐츠가 반복자로 이동됩니다.Contents are moved into the iterator to prevent mutation.
std::initializer_list<T>std::initializer_list<T> Yes Yes 비동기 버전은 항목을 복사합니다.The async version copies the items.
std::initializer_list<U>std::initializer_list<U> Yes 아니오No UT로 변환할 수 있어야 합니다.U must be convertible to T.
{ ForwardIt begin, ForwardIt end } Yes 아니오No *beginT로 변환할 수 있어야 합니다.*begin must be convertible to T.

UT로 변환할 수 있는 경우에도 IIterable<U>std::vector<U> 는 허용되지 않습니다. std::vector<U> 의 경우, 이중 반복자 버전을 사용할 수 있습니다(자세한 내용은 아래 참조).Note that IIterable<U> and std::vector<U> are not permitted, even if U is convertible to T. For std::vector<U>, you can use the double-iterator version (more details below).

경우에 따라서는 사용자가 가진 개체가 실제로 사용자가 원하는 IIterable을 구현할 수 있습니다.In some cases, the object that you have may actually implement the IIterable that you want. 예를 들어 FileOpenPicker.PickMultipleFilesAsync에 의해 생성된 IVectorView<StorageFile>IIterable 을 구현합니다.For example, the IVectorView<StorageFile> produced by FileOpenPicker.PickMultipleFilesAsync implements IIterable. 또한 IIterable 도 구현하지만 사용자가 명시적으로 요청해야 합니다.But it also implements IIterable; you just have to ask for it explicitly.

IVectorView<StorageFile> pickedFiles{ co_await filePicker.PickMultipleFilesAsync() };
requestData.SetStorageItems(storageItems.as<IIterable<IStorageItem>>());

다른 경우에는 이중 반복자 버전을 사용할 수 있습니다.In other cases, you can use the double-iterator version.

std::vector<StorageFile> storageFiles;
requestData.SetStorageItems({ storageFiles.begin(), storageFiles.end() });

이중 반복자는 전체를 반복하여 T로 변환할 수 있는 항목을 생성할 수 있을 때 일반적으로 위의 어떤 시나리오에도 맞지 않는 컬렉션이 있는 경우 더 잘 작동합니다. 위에서는 파생된 형식의 한 벡터에 대해 반복하기 위해 사용했습니다.The double-iterator works more generally for the case where you have a collection that doesn't fit any of the scenarios above, as long as you can iterate over it and produce things that can be converted to T. We used it above to iterate over a vector of derived types. 여기서는 파생된 형식의 벡터 외 항목에 대해 반복하기 위해 사용됩니다.Here, we use it to iterate over a non-vector of derived types.

std::array<StorageFile, 3> storageFiles;
requestData.SetStorageItems(storageFiles); // This doesn't work.
requestData.SetStorageItems({ storageFiles.begin(), storageFiles.end() }); // But this works.

IIterator<T>.GetMany(T[]) 의 구현은 반복자가 RandomAcessIt인 경우 더 효율적입니다.The implementation of IIterator<T>.GetMany(T[]) is more efficient if the iterator is a RandomAcessIt. 그렇지 않으면 해당 범위에 대해 여러 번 전달할 수 있습니다.Otherwise, it makes several passes over the range.

전달할 수 있는 형식Types that you can pass SyncSync AsyncAsync 참고Notes
nullptr Yes Yes 기본 메서드에서 nullptr을 지원하는지 확인해야 합니다.You must verify that the underlying method supports nullptr.
IIterable<IKeyValuePair<K, V>>IIterable<IKeyValuePair<K, V>> Yes Yes 또는 모든 항목을 변환할 수 있습니다.Or anything convertible to it.
std::map<K, V> const&std::map<K, V> const& Yes 아니오No
std::map<K, V>&&std::map<K, V>&& Yes Yes 변경되지 않도록 콘텐츠가 반복자로 이동됩니다.Contents are moved into the iterator to prevent mutation.
std::unordered_map<K, V> const&std::unordered_map<K, V> const& Yes 아니오No
std::unordered_map<K, V>&&std::unordered_map<K, V>&& Yes Yes 변경되지 않도록 콘텐츠가 반복자로 이동됩니다.Contents are moved into the iterator to prevent mutation.
std::initializer_list<std::pair<K, V>>std::initializer_list<std::pair<K, V>> Yes Yes 형식 KV는 정확하게 일치해야 합니다.Types K and V must match exactly. 키는 중복될 수 없습니다.Keys may not be duplicated. 비동기 버전은 항목을 복사합니다.The async version copies the items.
{ ForwardIt begin, ForwardIt end } Yes 아니오No begin->firstbegin->second를 각각 KV로 변환할 수 있어야 합니다.begin->first and begin->second must be convertible to K and V, respectively.

벡터 보기 매개 변수Vector view parameters

winrt::param::vector_view<T>winrt::param::async_vector_view<T>IVectorView<T> 를 사용하는 API로의 매개 변수 전달을 간소화합니다.winrt::param::vector_view<T> and winrt::param::async_vector_view<T> simplify passing parameters to APIs that take IVectorView<T>.

IVector<T>.GetView를 사용하면 IVector에서 IVectorView를 가져올 수 있습니다.You can use IVector<T>.GetView to get an IVectorView from an IVector.

전달할 수 있는 형식Types that you can pass SyncSync AsyncAsync 참고Notes
nullptr Yes Yes 기본 메서드에서 nullptr을 지원하는지 확인해야 합니다.You must verify that the underlying method supports nullptr.
IVectorView<T>IVectorView<T> Yes Yes 또는 모든 항목을 변환할 수 있습니다.Or anything convertible to it.
std::vector<T>const&std::vector<T>const& Yes 아니오No
std::vector<T>&&std::vector<T>&& Yes Yes 변경되지 않도록 콘텐츠가 보기로 이동됩니다.Contents are moved into the view to prevent mutation.
std::initializer_list<T>std::initializer_list<T> Yes Yes 형식은 정확하게 일치해야 합니다.Type must match exactly. 비동기 버전은 항목을 복사합니다.The async version copies the items.
{ ForwardIt begin, ForwardIt end } Yes 아니오No *beginT로 변환할 수 있어야 합니다.*begin must be convertible to T.

이중 반복자 버전은 직접 전달하기 위한 요구 사항에 맞지 않는 벡터 보기를 만드는 데 사용할 수 있습니다.The double-iterator version can be used to create vector views out of things that don't fit the requirements for being passed directly. 하지만 벡터는 직접 액세스를 지원하므로 RandomAcessIter를 전달하는 것이 좋습니다.Note, however, that since vectors support random access, we recommend that you pass a RandomAcessIter.

맵 보기 매개 변수Map view parameters

winrt::param::map_view<T>winrt::param::async_map_view<T>IMapView<T> 를 사용하는 API로의 매개 변수 전달을 간소화합니다.winrt::param::map_view<T> and winrt::param::async_map_view<T> simplify passing parameters to APIs that take IMapView<T>.

IMap::GetView를 사용하면 IMap에서 IMapView를 가져올 수 있습니다.You can use IMap::GetView to get an IMapView from an IMap.

전달할 수 있는 형식Types that you can pass SyncSync AsyncAsync 참고Notes
nullptr Yes Yes 기본 메서드에서 nullptr을 지원하는지 확인해야 합니다.You must verify that the underlying method supports nullptr.
IMapView<K, V>IMapView<K, V> Yes Yes 또는 모든 항목을 변환할 수 있습니다.Or anything convertible to it.
std::map<K, V> const&std::map<K, V> const& Yes 아니오No
std::map<K, V>&&std::map<K, V>&& Yes Yes 변경되지 않도록 콘텐츠가 보기로 이동됩니다.Contents are moved into the view to prevent mutation.
std::unordered_map<K, V> const&std::unordered_map<K, V> const& Yes 아니오No
std::unordered_map<K, V>&&std::unordered_map<K, V>&& Yes Yes 변경되지 않도록 콘텐츠가 보기로 이동됩니다.Contents are moved into the view to prevent mutation.
std::initializer_list<std::pair<K, V>>std::initializer_list<std::pair<K, V>> Yes Yes 동기 및 비동기 버전에서 모두 항목을 복사합니다.Both sync and async versions copy the items. 키를 중복할 수 없습니다.You may not duplicate keys.

벡터 매개 변수Vector parameters

winrt::param::vector<T>IVector<T> 를 사용하는 API로의 매개 변수 전달을 간소화합니다.winrt::param::vector<T> simplifies passing parameters to APIs that take IVector<T>.

전달할 수 있는 형식Types that you can pass 참고Notes
nullptr 기본 메서드에서 nullptr을 지원하는지 확인해야 합니다.You must verify that the underlying method supports nullptr.
IVector<T>IVector<T> 또는 모든 항목을 변환할 수 있습니다.Or anything convertible to it.
std::vector<T>&&std::vector<T>&& 변경되지 않도록 콘텐츠가 매개 변수로 이동됩니다.Contents are moved into the parameter to prevent mutation. 결과가 다시 이동되지는 않습니다.Results are not moved back.
std::initializer_list<T>std::initializer_list<T> 변경되지 않도록 콘텐츠가 매개 변수로 복사됩니다.Contents are copied into the parameter to prevent mutation.

메서드에서 벡터를 변경하는 경우 변경을 확인하는 유일한 방법은 IVector를 직접 전달하는 것입니다.If the method mutates the vector, then the only way to observe the mutation is to pass an IVector directly. std::vector를 전달하면 메서드에서 복사본을 변경하며 원본은 변경하지 않습니다.If you pass a std::vector, then the method mutates the copy and not the original.

맵 매개 변수Map parameters

winrt::param::map<T>IMap<T> 를 사용하는 API로의 매개 변수 전달을 간소화합니다.winrt::param::map<T> simplifies passing parameters to APIs that take IMap<T>.

전달할 수 있는 형식Types that you can pass 참고Notes
nullptr 기본 메서드에서 nullptr을 지원하는지 확인해야 합니다.You must verify that the underlying method supports nullptr.
IMap<T>IMap<T> 또는 모든 항목을 변환할 수 있습니다.Or anything convertible to it.
std::map<K, V>&&std::map<K, V>&& 변경되지 않도록 콘텐츠가 매개 변수로 이동됩니다.Contents are moved into the parameter to prevent mutation. 결과가 다시 이동되지는 않습니다.Results are not moved back.
std::unordered_map<K, V>&&std::unordered_map<K, V>&& 변경되지 않도록 콘텐츠가 매개 변수로 이동됩니다.Contents are moved into the parameter to prevent mutation. 결과가 다시 이동되지는 않습니다.Results are not moved back.
std::initializer_list<std::pair<K, V>>std::initializer_list<std::pair<K, V>> 변경되지 않도록 콘텐츠가 매개 변수로 복사됩니다.Contents are copied into the parameter to prevent mutation.

메서드에서 맵을 변경하는 경우 변경을 확인하는 유일한 방법은 IMap을 직접 전달하는 것입니다.If the method mutates the map, then the only way to observe the mutation is to pass an IMap directly. std::map 또는 std::unordered_map을 전달하면 메서드에서 복사본을 변경하며 원본은 변경하지 않습니다.If you pass a std::map or std::unordered_map, then the method mutates the copy and not the original.

배열 매개 변수Array parameters

winrt::array_view<T>winrt::param 네임스페이스에 없지만 C 스타일 배열(호환 배열)에 해당하는 매개 변수에 사용됩니다.The winrt::array_view<T> is not in the winrt::param namespace, but it is used for parameters that are C-style arrays—also known as conformant arrays.

전달할 수 있는 형식Types that you can pass 참고Notes
{} 빈 배열입니다.An empty array.
arrayarray C와 호환되는 배열(즉, C array[N];)이며 여기서 CTsizeof(C) == sizeof(T)로 변환 가능합니다.A conformant array of C (that is, C array[N];), where C is convertible to T, and sizeof(C) == sizeof(T).
std::array<C, N>std::array<C, N> C의 C++ std::array이며 여기서 CTsizeof(C) == sizeof(T)로 변환 가능합니다.A C++ std::array of C, where C is convertible to T, and sizeof(C) == sizeof(T).
std::vectorstd::vector C의 C++ std::vector이며 여기서 CTsizeof(C) == sizeof(T)로 변환 가능합니다.A C++ std::vector of C, where C is convertible to T, and sizeof(C) == sizeof(T).
{ T*, T* } 포인터의 쌍은 범위 [시작, 종료]를 나타냅니다.A pair of pointers represent the range [begin, end).
std::initializer_list<T>std::initializer_list<T>