C++-Standarddatentypen und C++/WinRTStandard C++ data types and C++/WinRT

Mit C++/WinRT kannst du Windows-Runtime-APIs unter Verwendung von C++-Standarddatentypen aufrufen (einschließlich einiger Datentypen der C++-Standardbibliothek).With C++/WinRT, you can call Windows Runtime APIs using Standard C++ data types, including some C++ Standard Library data types. Du kannst Standardzeichenfolgen an APIs übergeben (siehe Behandeln von Zeichenfolgen in C++/WinRT) sowie Initialisierungslisten und Standardcontainer an APIs übergeben, die eine semantisch äquivalente Sammlung erwarten.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.

Siehe auch Übergabe von Parametern in die ABI-Grenze.Also see Passing parameters into the ABI boundary.

StandardinitialisierungslistenStandard initializer lists

Eine Initialisierungsliste (std::initializer_list) ist ein Konstrukt der C++-Standardbibliothek.An initializer list (std::initializer_list) is a C++ Standard Library construct. Initialisierungslisten können beim Aufrufen bestimmter Windows-Runtime-Konstruktoren und -Methoden verwendet werden –You can use initializer lists when you call certain Windows Runtime constructors and methods. etwa beim Aufrufen von DataWriter::WriteBytes.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.
}

Damit das funktioniert, müssen zwei Voraussetzungen erfüllt sein.There are two pieces involved in making this work. Erstens: Die Methode DataWriter::WriteBytes akzeptiert einen Parameter vom Typ 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 ist ein benutzerdefinierter C++/WinRT-Typ, der auf sichere Weise eine zusammenhängende Reihe von Werten darstellt und in der C++/WinRT-Basisbibliothek definiert ist: %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).

Zweitens: winrt::array_view verfügt über einen Initialisierungslisten-Konstruktor.Second, winrt::array_view has an initializer-list constructor.

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

In vielen Fällen kannst du wählen, ob du winrt::array_view in deiner Programmierung berücksichtigen möchtest.In many cases, you can choose whether or not to be aware of winrt::array_view in your programming. Falls du dich dagegen entscheidest, musst du keinerlei Codeänderungen vornehmen, wenn in der C++-Standardbibliothek ein äquivalenter Typ auftaucht.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.

Du kannst eine Initialisierungsliste an eine Windows-Runtime-API übergeben, die einen Sammlungsparameter erwartet.You can pass an initializer list to a Windows Runtime API that expects a collection parameter. Nehmen wir zum Beispiel StorageItemContentProperties::RetrievePropertiesAsync:Take StorageItemContentProperties::RetrievePropertiesAsync for example.

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

Diese API kannst du mit einer Initialisierungsliste wie der folgenden aufrufen: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" }) };
}

Hier spielen zwei Faktoren eine Rolle.Two factors are at work here. Erstens: Der Aufgerufene konstruiert auf der Grundlage der Initialisierungsliste einen Standardvektor (std::vector). (Dieser Aufgerufene ist asynchron und kann daher das Objekt besitzen, was in diesem Fall erforderlich ist.)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). Zweitens: C++/WinRT bindet std::vector transparent (und ohne Kopien) als Windows-Runtime-Sammlungsparameter.Second, C++/WinRT transparently (and without introducing copies) binds std::vector as a Windows Runtime collection parameter.

Standardarrays und -vektorenStandard arrays and vectors

winrt::array_view verfügt auch über Konvertierungskonstruktoren für std::vector und 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

Du könntest also stattdessen DataWriter::WriteBytes mit einem Standardvektor (std::vector) aufrufen.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.

Oder mit einem Standardarray (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 bindet std::vector als Windows-Runtime-Sammlungsparameter.C++/WinRT binds std::vector as a Windows Runtime collection parameter. Du kannst also std::vector<winrt::hstring> übergeben, und es wird in die entsprechende Windows-Runtime-Sammlung winrt::hstring konvertiert.So, you can pass a std::vector<winrt::hstring>, and it will be converted to the appropriate Windows Runtime collection of winrt::hstring. Bei einem asynchronen Aufgerufenen ist noch ein weiteres Detail zu beachten.There's an extra detail to bear in mind if the callee is asynchronous. Die Implementierungsdetails dieses Falls machen die Angabe eines R-Werts (rvalue) erforderlich. Du musst also eine Kopie oder Verschiebung des Vektors angeben.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. Im folgenden Codebeispiel übertragen wir den Besitz des Vektors auf das Objekt des Parametertyps, der von dem asynchronen Aufgerufenen akzeptiert wird (und achten anschließend sorgfältig darauf, nach der Verschiebung nicht erneut auf vecH zuzugreifen).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). Weitere Informationen zu R-Werten findest du unter Value categories, and references to them (Wertekategorien und entsprechende Verweise).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)) };
}

std::vector<std::wstring> kann jedoch nicht übergeben werden, wenn eine Windows-Runtime-Sammlung erwartet wird.But you can't pass a std::vector<std::wstring> where a Windows Runtime collection is expected. Das liegt daran, dass C++ die Typparameter dieser Sammlung nicht erzwingt, nachdem sie in die entsprechende Windows-Runtime-Sammlung std::wstring konvertiert wurde.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). Das folgende Codebeispiel lässt sich daher nur kompilieren, wenn stattdessen std::vector<winrt::hstring> übergeben wird, wie oben gezeigt: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.
}

Unformatierte Arrays und ZeigerbereicheRaw arrays, and pointer ranges

Da die Möglichkeit besteht, dass die C++-Standardbibliothek später einmal einen äquivalenten Typ enthält, kannst du auf Wunsch oder bei Bedarf auch direkt mit winrt::array_view arbeiten.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 verfügt über Konvertierungskonstruktoren für ein unformatiertes Array sowie für einen Bereich von T* (Zeiger auf den Elementtyp).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.

Funktionen und Operatoren für „winrt::array_view“winrt::array_view functions and operators

Für winrt::array_view wurde eine Vielzahl von Konstruktoren, Operatoren, Funktionen und Iteratoren implementiert.A host of constructors, operators, functions, and iterators are implemented for winrt::array_view. Da es sich bei winrt::array_view sich um einen Bereich handelt, kann das Element mit for (bereichsbasiert) oder mit std::for_each verwendet werden.A winrt::array_view is a range, so you can use it with range-based for, or with std::for_each.

Weitere Beispiele und Informationen findest du im API-Referenzthema für winrt::array_view.For more examples and info, see the winrt::array_view API reference topic.

IVector<T> und StandarditerationskonstrukteIVector<T> and standard iteration constructs

SyndicationFeed.Items ist ein Beispiel für eine Windows-Runtime-API, die eine Sammlung vom Typ IVector<T> zurückgibt (projiziert in C++/WinRT als 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>). Dieser Typ kann mit Standarditerationskonstrukten wie for (bereichsbasiert) verwendet werden.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;
    }
}

C++-Coroutinen mit asynchronen Windows-Runtime-APIsC++ coroutines with asynchronous Windows Runtime APIs

Zum Aufrufen asynchroner Windows-Runtime-APIs kann weiterhin die Parallel Patterns Library (PPL) verwendet werden.You can continue to use the Parallel Patterns Library (PPL) when calling asynchronous Windows Runtime APIs. In vielen Fällen bieten C++-Coroutinen allerdings eine effiziente und einfacher zu programmierende Alternative für die Interaktion mit asynchronen Objekten.However, in many cases, C++ coroutines provide an efficient and more easily-coded idiom for interacting with asynchronous objects. Weitere Informationen und Codebeispiele findest du unter Parallelität und asynchrone Vorgänge mit C++/WinRT.For more info, and code examples, see Concurrency and asynchronous operations with C++/WinRT.

Wichtige APIsImportant APIs