프로젝팅된 API에 매개 변수 전달

  • 아티클

특정 형식의 경우 C++/WinRT는 프로젝팅된 API에 매개 변수를 전달하는 대안 메서드를 제공합니다. 이러한 매개 변수 수락 클래스는 winrt::param 네임스페이스에 배치됩니다. C++/WinRT에서 생성된 코드만 이러한 클래스를 사용해야 합니다. 사용자 고유의 함수 및 메서드에서 사용하지 마세요.

Important

winrt::param 네임스페이스에서 형식을 직접 사용하지 않도록 해야 합니다. 이는 프로젝션의 이점을 위한 것입니다.

이러한 대안 중 일부는 동기 호출과 비동기 호출을 구분합니다. 비동기 호출 버전은 일반적으로 매개 변수 데이터의 소유권을 가져와 비동기 호출이 완료될 때까지 값이 유효성을 유지하고 변경되지 않게 합니다. 그러나 이 보호는 다른 스레드에 있는 컬렉션의 변경 내용까지 적용되지는 않습니다. 이를 방지하는 것은 사용자의 책임입니다.

문자열 매개 변수에 대한 대안

winrt::param::hstring은 winrt::hstring로 매개 변수를 전달하는 것을 간소화합니다. winrt::hstring 외에 다음 대안도 허용됩니다.

대체 주의
{} 빈 문자열입니다.
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를 전달하면 프로세스가 종료됩니다.

반복 가능한 매개 변수에 대한 대안

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> 외에 다음 대안도 허용됩니다. 일부 대안은 동기 메서드에만 사용할 수 있습니다.

대체 동기화 Async 주의
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로 변환할 수 있습니다.

다음 예제에서 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>>의 경우 다음 대안이 허용됩니다. 일부 대안은 동기 메서드에만 사용할 수 있습니다.

대체 동기화 Async 주의
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> 외에 다음 대안도 허용됩니다. 일부 대안은 동기 메서드에만 사용할 수 있습니다.

대체 동기화 Async 주의
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> 외에 다음 대안도 허용됩니다. 일부 대안은 동기 메서드에만 사용할 수 있습니다.

대체 동기화 Async 주의
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::param::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로 변환할 수 있는 C 스타일 배열 및 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).

또한 Windows 런타임 ABI 경계에서 C 스타일 배열을 전달하는 다양한 패턴 블로그 게시물도 참조하세요.