Pasar parámetros a las API proyectadas

Para determinados tipos, C++/WinRT proporciona métodos alternativos para pasar un parámetro a una API proyectada. Estas clases que aceptan parámetros se encuentran en el espacio de nombres winrt::param. Solo el código generado por C++/WinRT debe usar estas clases; no los use en sus propias funciones y métodos.

Important

No debería usar usted mismo los tipos del espacio de nombres winrt::param. Son para beneficio de la proyección.

Algunas de estas alternativas distinguen entre llamadas sincrónicas y asincrónicas. La versión de las llamadas asincrónicas normalmente toma posesión de los datos del parámetro para asegurarse de que los valores permanecen válidos y sin cambios hasta que se completa la llamada asincrónica. Sin embargo, tenga en cuenta que esta protección no se aplica a los cambios realizados en la colección desde otro hilo. Evitarlo es su responsabilidad.

Alternativas para parámetros de cadena

winrt::param::hstring simplifica pasar parámetros como winrt::hstring. Además de winrt::hstring, estas alternativas también se aceptan:

Alternativa Notes
{} Una cadena vacía.
std::wstring_view La vista debe ir seguida de un terminador NULL.
std::wstring
wchar_t const* Una cadena terminada en null.

No se puede pasar nullptr para representar la cadena vacía. En su lugar, use L"" o {}.

El compilador sabe cómo evaluar wcslen en literales de texto en tiempo de compilación. Por lo tanto, para literales, L"Name"sv y L"Name" son equivalentes.

Tenga en cuenta que los objetos std::wstring_view no terminan en null, pero C++/WinRT requiere que el carácter después del final de la vista sea null. Si se pasa un std::wstring_view no terminado en nulo, el proceso finalizará.

Alternativas para parámetros iterables

winrt::param::iterable<T> y winrt::param::async_iterable<T> simplifican el paso de parámetros de tipo IIterable<T>.

Las colecciones de Windows Runtime IVector<T> e IVectorView<T> ya son compatibles con IIterable<T>. Las colecciones de Windows Runtime IMap<K, V> e IMapView<K, V> ya son compatibles con IIterable<IKeyValuePair<K, V>>.

Además de IIterable<T>, también se aceptan las siguientes alternativas. Tenga en cuenta que algunas alternativas solo están disponibles para métodos sincrónicos.

Alternativa Sincronización Async Notes
std::vector<T> const& Yes No
std::vector<T>&& Yes Yes Los contenidos se mueven a un iterable temporal.
std::initializer_list<T> Yes Yes La versión asincrónica copia los elementos.
std::initializer_list<U> Yes No U debe ser convertible a T.
{ begin, end } Yes No begin y end deben ser iteradores hacia delante y *begin deben ser convertibles a T.

El iterador doble funciona más generalmente en el caso de que tenga una colección que no se ajuste a ninguno de los escenarios anteriores, siempre que pueda iterar sobre él y generar cosas que se pueden convertir en T. Por ejemplo, puede tener un IVector<U> o std::vector<U>, donde U se puede convertir a T.

En el ejemplo siguiente, el método SetStorageItems espera un IIterable<IStorageItem>. El patrón de iterador doble nos permite pasar otros tipos de colecciones.

// 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

Para el caso de IIterable<IKeyValuePair<K, V>>, se aceptan las siguientes alternativas. Tenga en cuenta que algunas alternativas solo están disponibles para métodos sincrónicos.

Alternativa Sincronización Async Notes
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes Los contenidos se trasladan a un iterable temporal.
std::unordered_map<K, V> const& Yes No
std::unordered_map<K, V>&& Yes Yes Los contenidos se mueven a un iterable temporal.
std::initializer_list<std::pair<K, V>> Yes Yes La versión asincrónica copia la lista en un iterable temporal.
{ begin, end } Yes No begin y end deben ser iteradores hacia delante, y begin->first deben begin->second ser convertibles a K y V, respectivamente.

Alternativas para los parámetros de vista vectorial

winrt::param::vector_view<T> y winrt::param::async_vector_view<T> simplifican el paso de parámetros como IVectorView<T>.

Puedes llamar a IVector<T>::GetView para obtener un IVectorView<T> de un IVector<T>.

Además de IVectorView<T>, también se aceptan las siguientes alternativas. Tenga en cuenta que algunas alternativas solo están disponibles para métodos sincrónicos.

Alternativa Sincronización Async Notes
std::vector<T> const& Yes No
std::vector<T>&& Yes Yes El contenido se traslada a una vista temporal.
std::initializer_list<T> Yes Yes La versión asincrónica copia la lista en una vista temporal.
{ begin, end } Yes No begin y end deben ser iteradores hacia delante y *begin deben ser convertibles a T.

De nuevo, la versión con dos iteradores se puede usar para crear vistas de vector a partir de elementos que no encajan en ninguna alternativa existente. La vista temporal es más eficiente si los iteradores begin y end son iteradores de acceso aleatorio.

Alternativas para los parámetros de la vista de mapa

winrt::param::map_view<T> y winrt::param::async_map_view<T> simplifican la transferencia de parámetros como IMapView<T>.

Puedes llamar a IMap<K, V>::GetView para obtener un IMapView<K, V> desde un IMap<K, V>.

Además de IMapView<K, V>, también se aceptan las siguientes alternativas. Tenga en cuenta que algunas alternativas solo están disponibles para métodos sincrónicos.

Alternativa Sincronización Async Notes
std::map<K, V> const& Yes No
std::map<K, V>&& Yes Yes El contenido se traslada a una vista temporal.
std::unordered_map<K, V> const& Yes No
std::unordered_map<K, V>&& Yes Yes El contenido se traslada a una vista temporal.
std::initializer_list<std::pair<K, V>> Yes Yes El contenido se copia en una vista temporal. Es posible que las claves no estén duplicadas.

Alternativas para parámetros vectoriales

winrt::param::vector<T> simplifica el paso de parámetros como IVector<T>. Además de IVector<T>, estas alternativas también se aceptan:

Alternativa Notes
std::vector<T>&& El contenido se mueve a un vector temporal. Los resultados no se mueven de nuevo.
std::initializer_list<T>

Si el método muta el vector temporal, esos cambios no se reflejan en los parámetros originales. Para observar los cambios, pase un IVector<T>.

Alternativas para los parámetros de mapa

winrt::param::map<K, V> simplifica la tarea de pasar parámetros como IMap<K, V>. Además de IMap<K, V>, estas alternativas también se aceptan:

Puede pasar Notes
std::map<K, V>&& El contenido se mueve a un mapa temporal. Los resultados no se mueven de nuevo.
std::unordered_map<K, V>&& El contenido se mueve a un mapa temporal. Los resultados no se mueven de nuevo.
std::initializer_list<std::pair<K, V>>

Si el método muta el mapa temporal, esos cambios no se reflejan en los parámetros originales. Para observar los cambios, pase un IMap<K, V>.

Alternativas para los parámetros de matriz

winrt::array_view<T> no está en el espacio de nombres winrt::param, pero se usa para parámetros que son matrices al estilo de C. Además de un array_view<T> explícito, estas alternativas también se aceptan:

Alternativa Notes
{} Matriz vacía.
U[] Matriz de estilo C, donde U se puede convertir a T y sizeof(U) == sizeof(T).
std::array<U, N> Donde U se puede convertir a T y sizeof(U) == sizeof(T).
std::vector<U> Donde U se puede convertir a T y sizeof(U) == sizeof(T).
{ begin, end } begin y end deben ser de tipo T*, que representa el intervalo [begin, end).
std::initializer_list<T>
std::span<U, N> Donde U se puede convertir a T y sizeof(U) == sizeof(T).

Consulte también la entrada de blog Los distintos patrones para pasar matrices de estilo C a través del límite de ABI de Windows Runtime.

  • Last updated on