Types de données C++ standard et C++/WinRTStandard C++ data types and C++/WinRT

Avec C++/WinRT, vous pouvez appeler des API Windows Runtime à l’aide de types de données C++ standard, y compris certains types de données de la bibliothèque C++ standard.With C++/WinRT, you can call Windows Runtime APIs using Standard C++ data types, including some C++ Standard Library data types. Vous pouvez passer des chaînes standard aux API (consultez Gestion des chaînes en C++/WinRT), et passer des listes d’initialiseurs et des conteneurs standard aux API qui attendent une collection sémantiquement équivalente.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.

Consultez également Passage de paramètres à la frontière ABI.Also see Passing parameters into the ABI boundary.

Listes d’initialiseurs standardStandard initializer lists

Une liste d’initialiseurs (std::initializer_list) est une construction de la bibliothèque C++ standard.An initializer list (std::initializer_list) is a C++ Standard Library construct. Vous pouvez utiliser des listes d’initialiseurs lorsque vous appelez certains constructeurs et méthodes Windows Runtime.You can use initializer lists when you call certain Windows Runtime constructors and methods. Par exemple, vous pouvez appeler DataWriter::WriteBytes avec une telle liste.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.
}

Il existe deux éléments impliqués dans cette tâche.There are two pieces involved in making this work. Tout d’abord, la méthode DataWriter::WriteBytes prend un paramètre de type 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 est un type personnalisé C++/WinRT qui représente en toute sécurité une série contiguë de valeurs (définie dans la bibliothèque de base C++/WinRT, à savoir %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).

Deuxièmement, winrt::array_view possède un constructeur initialiseur-liste.Second, winrt::array_view has an initializer-list constructor.

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

Dans de nombreux cas, vous pouvez choisir ou non de prendre en compte winrt::array_view dans votre programmation.In many cases, you can choose whether or not to be aware of winrt::array_view in your programming. Si vous choisissez de ne pas le prendre en compte, vous ne devrez changer aucun code si un type équivalent s’affiche dans la bibliothèque C++ standard.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.

Vous pouvez transmettre une liste d’initialiseurs à une API Windows Runtime qui attend un paramètre de collection.You can pass an initializer list to a Windows Runtime API that expects a collection parameter. Prenons StorageItemContentProperties::RetrievePropertiesAsync comme exemple.Take StorageItemContentProperties::RetrievePropertiesAsync for example.

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

Vous pouvez appeler cette API avec une liste d’initialiseurs comme suit.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" }) };
}

Deux facteurs sont impliqués ici.Two factors are at work here. Tout d’abord, l’appelé construit un std::vector à partir de la liste d’initialiseurs (cet appelé est asynchrone, donc il peut être - et doit être - le propriétaire de cet objet).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). Deuxièmement, C++/WinRT lie de manière transparente (et sans créer de copies) std::vector comme un paramètre de collection Windows Runtime.Second, C++/WinRT transparently (and without introducing copies) binds std::vector as a Windows Runtime collection parameter.

Vecteurs et tableaux standardStandard arrays and vectors

winrt::array_view a également des constructeurs de conversion à partir de std::vector et 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

Par conséquent, vous pouvez appeler à la place DataWriter::WriteBytes avec 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.

Ou avec 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 lie std::vector comme un paramètre de collection Windows Runtime.C++/WinRT binds std::vector as a Windows Runtime collection parameter. Par conséquent, vous pouvez transmettre un std::vector<winrt::hstring> , et il sera converti dans la collection Windows Runtime appropriée 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. Il existe des informations supplémentaires à prendre en compte si l’appelé est asynchrone.There's an extra detail to bear in mind if the callee is asynchronous. En raison des détails d’implémentation de ce cas, vous devez fournir un rvalue et donc une copie ou un déplacement du vecteur.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. Dans l’exemple de code ci-dessous, nous passons la propriété du vecteur à l’objet du type de paramètre accepté par l’appelé asynchrone (en veillant à ne pas accéder à nouveau à vecH après l’avoir déplacé).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). Pour en savoir plus sur rvalues, consultez Catégories de valeurs et références.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)) };
}

Mais vous ne pouvez pas transmettre un std::vector<std::wstring> là où une collection Windows Runtime est attendue.But you can't pass a std::vector<std::wstring> where a Windows Runtime collection is expected. Cela est dû au fait que, la collection Windows Runtime appropriée de std::wstring ayant été convertie, le langage C++ ne forcera pas le ou les paramètres de type de cette collection.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). Par conséquent, l’exemple de code suivant ne sera pas compilé (et la solution consiste à passer un std::vector<winrt::hstring> à la place, comme indiqué ci-dessus).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.
}

Tableaux bruts et plages de pointeursRaw arrays, and pointer ranges

En gardant en tête qu’un type équivalent peut exister dans l’avenir dans la bibliothèque C++ standard, vous pouvez également travailler directement avec winrt::array_view, par choix ou par nécessité.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 a des constructeurs de conversion à partir d’un tableau brut et d’une plage de T* (pointeurs vers le type d’élément).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.

Opérateurs et fonctions winrt::array_viewwinrt::array_view functions and operators

Une série de constructeurs, d’opérateurs, de fonctions et d’itérateurs sont implémentés pour winrt::array_view.A host of constructors, operators, functions, and iterators are implemented for winrt::array_view. Un winrt::array_view étant une plage, vous pouvez l’utiliser avec for basé sur les plages ou avec std::for_each.A winrt::array_view is a range, so you can use it with range-based for, or with std::for_each.

Pour plus d’exemples et d’informations, consultez la rubrique sur les informations de référence sur les API winrt::array_view.For more examples and info, see the winrt::array_view API reference topic.

IVector<T> et constructions d’itération standardIVector<T> and standard iteration constructs

SyndicationFeed.Items est un exemple d’API Windows Runtime qui retourne une collection de type IVector<T> (projeté dans C++/WinRT comme 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>). Vous pouvez utiliser ce type avec des constructions d’itération standard, par exemple des for basés sur les plages.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;
    }
}

Coroutines C++ avec des API Windows Runtime asynchronesC++ coroutines with asynchronous Windows Runtime APIs

Vous pouvez continuer à utiliser la Bibliothèque de modèles parallèles (PPL) lors de l’appel aux API Windows Runtime asynchrones.You can continue to use the Parallel Patterns Library (PPL) when calling asynchronous Windows Runtime APIs. Toutefois, dans de nombreux cas, les coroutines C++ fournissent un idiome efficace et plus facilement codé pour interagir avec les objets asynchrones.However, in many cases, C++ coroutines provide an efficient and more easily-coded idiom for interacting with asynchronous objects. Pour plus d’informations et des exemples de code, voir Opérations concurrentes et asynchrones avec C++/WinRT.For more info, and code examples, see Concurrency and asynchronous operations with C++/WinRT.

API importantesImportant APIs