Tipos de datos de C++ estándar y C++/WinRTStandard C++ data types and C++/WinRT

Con C++/WinRT, puedes llamar a las API de Windows Runtime con tipos de datos C++ estándar, incluidos algunos tipos de datos de la biblioteca estándar de C++.With C++/WinRT, you can call Windows Runtime APIs using Standard C++ data types, including some C++ Standard Library data types. Puedes pasar cadenas estándar a las API (consulta Control de cadenas en C++/WinRT) y puedes pasar contenedores estándar y listas de inicializadores a las API que esperan una colección semánticamente equivalente.You can pass standard strings to APIs (see String handling in C++/WinRT), and you can pass initializer lists and standard containers to APIs that expect a semantically equivalent collection.

Consulta también Pasar parámetros a los límites de la ABI.Also see Passing parameters into the ABI boundary.

Listas de inicializadores estándaresStandard initializer lists

Una lista de inicializadores (std::initializer_list) es una construcción de la biblioteca estándar de C++.An initializer list (std::initializer_list) is a C++ Standard Library construct. Puedes usar las listas de inicializadores cuando llames a algunos constructores y métodos de Windows Runtime.You can use initializer lists when you call certain Windows Runtime constructors and methods. Por ejemplo, puedes llamar a DataWriter::WriteBytes con una lista.For example, you can call DataWriter::WriteBytes with one.

#include <winrt/Windows.Storage.Streams.h>

using namespace winrt::Windows::Storage::Streams;

int main()
{
    winrt::init_apartment();

    InMemoryRandomAccessStream stream;
    DataWriter dataWriter{stream};
    dataWriter.WriteBytes({ 99, 98, 97 }); // the initializer list is converted to a winrt::array_view before being passed to WriteBytes.
}

Hay dos piezas implicadas en este trabajo.There are two pieces involved in making this work. En primer lugar, el método DataWriter::WriteBytes toma un parámetro de tipo winrt::array_view.First, the DataWriter::WriteBytes method takes a parameter of type winrt::array_view.

void WriteBytes(winrt::array_view<uint8_t const> value) const

winrt::array_view es un tipo C++/WinRT personalizado que representa de forma segura una serie contigua de valores (definida en la biblioteca base de C++/WinRT, que es %WindowsSdkDir%Include\<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h).winrt::array_view is a custom C++/WinRT type that safely represents a contiguous series of values (it is defined in the C++/WinRT base library, which is %WindowsSdkDir%Include\<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h).

En segundo lugar, winrt::array_view tiene un constructor de listas de inicializadores.Second, winrt::array_view has an initializer-list constructor.

template <typename T> winrt::array_view(std::initializer_list<T> value) noexcept

En muchos casos, puedes elegir si quieres tener en cuenta winrt::array_view o no en tu programación.In many cases, you can choose whether or not to be aware of winrt::array_view in your programming. Si eliges no tenerla en cuenta, no tendrás ningún código que cambiar si aparece un tipo equivalente en la biblioteca estándar de C++.If you choose not to be aware of it then you won't have any code to change if and when an equivalent type appears in the C++ Standard Library.

Puedes pasar una lista de inicializadores a una API de Windows Runtime que espera un parámetro de colección.You can pass an initializer list to a Windows Runtime API that expects a collection parameter. Toma StorageItemContentProperties::RetrievePropertiesAsync como ejemplo.Take StorageItemContentProperties::RetrievePropertiesAsync for example.

IAsyncOperation<IMap<winrt::hstring, IInspectable>> StorageItemContentProperties::RetrievePropertiesAsync(IIterable<winrt::hstring> propertiesToRetrieve) const;

Puedes llamar a dicha API con una lista de inicializadores como esta.You can call that API with an initializer list like this.

IAsyncAction retrieve_properties_async(StorageFile const& storageFile)
{
    auto properties{ co_await storageFile.Properties().RetrievePropertiesAsync({ L"System.ItemUrl" }) };
}

Aquí funcionan dos factores.Two factors are at work here. En primer lugar, el destinatario construye un std:: vector desde la lista de inicializadores (este destinatario es asincrónico, lo que quiere decir que puede y debe poseer dicho objeto).First, the callee constructs a std::vector from the initializer list (this callee is asynchronous, so it's able to own that object, which it must). En segundo lugar, C++/WinRT enlaza std:: vector de forma transparente (y sin introducir copias) como un parámetro de la colección de Windows Runtime.Second, C++/WinRT transparently (and without introducing copies) binds std::vector as a Windows Runtime collection parameter.

Matrices y vectores estándaresStandard arrays and vectors

winrt::array_view también tiene los constructores de conversión de std::vector y std::array.winrt::array_view also has conversion constructors from std::vector and std::array.

template <typename C, size_type N> winrt::array_view(std::array<C, N>& value) noexcept
template <typename C> winrt::array_view(std::vector<C>& vectorValue) noexcept

Por lo tanto, en lugar de ello podrías llamar a DataWriter::WriteBytes con un std:: vector.So, you could instead call DataWriter::WriteBytes with a std::vector.

std::vector<byte> theVector{ 99, 98, 97 };
dataWriter.WriteBytes(theVector); // theVector is converted to a winrt::array_view before being passed to WriteBytes.

O con un std::array.Or with a std::array.

std::array<byte, 3> theArray{ 99, 98, 97 };
dataWriter.WriteBytes(theArray); // theArray is converted to a winrt::array_view before being passed to WriteBytes.

C++/WinRT enlaza std:: vector como un parámetro de la colección de Windows Runtime.C++/WinRT binds std::vector as a Windows Runtime collection parameter. Por lo tanto, puedes pasar un std:: vector<winrt::hstring> , y se convertirá a la colección adecuada de Windows Runtime de winrt::hstring.So, you can pass a std::vector<winrt::hstring>, and it will be converted to the appropriate Windows Runtime collection of winrt::hstring. Hay un detalle adicional que hay que tener en cuenta si el destinatario es asincrónico.There's an extra detail to bear in mind if the callee is asynchronous. Debido a los detalles de implementación de ese caso, tendrás que proporcionar un rvalue, por lo que debes proporcionar una copia o un movimiento del vector.Due to the implementation details of that case, you'll need to provide an rvalue, so you must provide a copy or a move of the vector. En el ejemplo de código siguiente, movemos la propiedad del vector al objeto de tipo de parámetro aceptado por el destinatario asincrónico. Después, tenemos cuidado de no acceder a vecH después de moverla.In the code example below, we move ownership of the vector to the object of the parameter type accepted by the async callee (and then we're careful not to access vecH again after moving it). Si quieres saber más sobre rvalues, consulta Categorías de valor y referencias a ellas.If you want to know more about rvalues, see Value categories, and references to them.

IAsyncAction retrieve_properties_async(StorageFile const storageFile, std::vector<winrt::hstring> vecH)
{
    auto properties{ co_await storageFile.Properties().RetrievePropertiesAsync(std::move(vecH)) };
}

Pero no puedes pasar un std:: vector<std:: wstring> donde se espera una colección de Windows Runtime.But you can't pass a std::vector<std::wstring> where a Windows Runtime collection is expected. Esto se debe a que, al haber convertido a la colección adecuada de Windows Runtime de std:: wstring, el lenguaje de C++ no forzará el o los parámetro/s de tipo de dicha colección.This is because, having converted to the appropriate Windows Runtime collection of std::wstring, the C++ language won't then coerce that collection's type parameter(s). Por lo tanto, no se compilará el siguiente ejemplo de código (y la solución es pasar un std::vector<winrt::hstring> en su lugar, como se muestra arriba).Consequently, the following code example won't compile (and the solution is to pass a std::vector<winrt::hstring> instead, as shown above).

IAsyncAction retrieve_properties_async(StorageFile const& storageFile, std::vector<std::wstring> const& vecW)
{
    auto properties{ co_await storageFile.Properties().RetrievePropertiesAsync(std::move(vecW)) }; // error! Can't convert from vector of wstring to async_iterable of hstring.
}

Matrices sin procesar e intervalos de punteroRaw arrays, and pointer ranges

Teniendo en cuenta que podría existir un tipo equivalente en el futuro en la biblioteca estándar de C++, también puedes trabajar directamente con winrt::array_view si así lo decides o lo necesitas.Bearing in mind the caveat that an equivalent type may exist in the future in the C++ Standard Library, you can also work directly with winrt::array_view if you choose to, or need to.

winrt::array_view tiene los constructores de conversión de una matriz sin procesar y de un intervalo de T* (punteros para el tipo de elemento).winrt::array_view has conversion constructors from a raw array, and from a range of T* (pointers to the element type).

using namespace winrt;
...
byte theRawArray[]{ 99, 98, 97 };
array_view<byte const> fromRawArray{ theRawArray };
dataWriter.WriteBytes(fromRawArray); // the winrt::array_view is passed to WriteBytes.

array_view<byte const> fromRange{ theArray.data(), theArray.data() + 2 }; // just the first two elements.
dataWriter.WriteBytes(fromRange); // the winrt::array_view is passed to WriteBytes.

Funciones y operadores de winrt::array_viewwinrt::array_view functions and operators

Se ha implementado una gran cantidad de constructores, operadores, funciones e iteradores para winrt::array_view.A host of constructors, operators, functions, and iterators are implemented for winrt::array_view. winrt::array_view es un intervalo, así que puedes usarlo con for basado en intervalos o con std::for_each.A winrt::array_view is a range, so you can use it with range-based for, or with std::for_each.

Para obtener más ejemplos e información, consulta el tema de referencia de API winrt::array_view.For more examples and info, see the winrt::array_view API reference topic.

IVector<T> y construcciones de iteración estándarIVector<T> and standard iteration constructs

SyndicationFeed.Items es un ejemplo de una API de Windows Runtime que devuelve una colección del tipo IVector<T> (proyectada en C++/WinRT como winrt::Windows::Foundation::Collections::IVector<T> ).SyndicationFeed.Items is an example of a Windows Runtime API that returns a collection of type IVector<T> (projected into C++/WinRT as winrt::Windows::Foundation::Collections::IVector<T>). Puedes usar este tipo con construcciones de iteración estándar, como for basado en intervalos.You can use this type with standard iteration constructs, such as range-based for.

// main.cpp
#include "pch.h"
#include <winrt/Windows.Web.Syndication.h>
#include <iostream>

using namespace winrt;
using namespace Windows::Web::Syndication;

void PrintFeed(SyndicationFeed const& syndicationFeed)
{
    for (SyndicationItem const& syndicationItem : syndicationFeed.Items())
    {
        std::wcout << syndicationItem.Title().Text().c_str() << std::endl;
    }
}

Corrutinas de C++ con las API asincrónicas de Windows RuntimeC++ coroutines with asynchronous Windows Runtime APIs

Puedes seguir usando la biblioteca de patrones paralelos (PPL) al llamar a las API asincrónicas de Windows Runtime.You can continue to use the Parallel Patterns Library (PPL) when calling asynchronous Windows Runtime APIs. Sin embargo, en muchos casos, las corrutinas de C++ son un modo eficiente y fácil de interactuar con objetos asincrónicos.However, in many cases, C++ coroutines provide an efficient and more easily-coded idiom for interacting with asynchronous objects. Para obtener más información y ejemplos de código, consulta Operaciones simultáneas y asincrónicas con C++/WinRT.For more info, and code examples, see Concurrency and asynchronous operations with C++/WinRT.

API importantesImportant APIs