Procedura: gestire eventi mediante WRL

Articolo
10/12/2023

Questo documento illustra come usare la libreria di modelli C++ di Windows Runtime (WRL) per sottoscrivere e gestire gli eventi di un oggetto Windows Runtime.

Per un esempio più semplice che crea un'istanza di tale componente e recupera un valore della proprietà, vedi Procedura: Attivare e usare un componente Windows Runtime.

Sottoscrizione e gestione di eventi

I passaggi seguenti avviano un ABI::Windows::System::Threading::IDeviceWatcher oggetto e usano gestori eventi per monitorare lo stato di avanzamento. L'interfaccia IDeviceWatcher consente di enumerare i dispositivi in modo asincrono o in background e ricevere notifiche quando i dispositivi vengono aggiunti, rimossi o modificati. La funzione callback è una parte importante di questo esempio perché consente di specificare gestori eventi che elaborano i risultati dell'operazione in background. L'esempio completo segue.

Avviso

Anche se in genere usi la libreria modelli C++ di Windows Runtime in un'app piattaforma UWP (Universal Windows Platform), questo esempio usa un'app console per l'illustrazione. Le funzioni, wprintf_s ad esempio, non sono disponibili da un'app piattaforma UWP (Universal Windows Platform). Per altre informazioni sui tipi e le funzioni che puoi usare in un'app piattaforma UWP (Universal Windows Platform), vedi Funzioni CRT non supportate nelle app piattaforma UWP (Universal Windows Platform) e Win32 e COM per le app UWP.

Includere (#include) tutte le intestazioni della libreria di modelli di Windows Runtime, Windows Runtime C++ o della libreria standard C++.
```
#include <Windows.Devices.Enumeration.h>
#include <wrl/event.h>
#include <stdio.h>

using namespace ABI::Windows::Devices::Enumeration;
using namespace ABI::Windows::Foundation;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;
```
Windows.Devices.Enumeration.h dichiara i tipi necessari per enumerare i dispositivi.

Si consiglia di utilizzare la direttiva using namespace nel file con estensione cpp per rendere il codice più leggibile.

Dichiarare le variabili locali per l'app. Questo esempio contiene il conteggio del numero di dispositivi enumerati e token di registrazione che lo consentono di annullare successivamente la sottoscrizione agli eventi.

// Counts the number of enumerated devices.
unsigned int deviceCount = 0;

// Event registration tokens that enable us to later unsubscribe from events.
EventRegistrationToken addedToken;
EventRegistrationToken stoppedToken;
EventRegistrationToken enumCompletedToken;

Inizializzare Windows Runtime.

// Initialize the Windows Runtime.
RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
if (FAILED(initialize))
{
    return PrintError(__LINE__, initialize);
}

Creare un oggetto Event che sincronizza il completamento del processo di enumerazione con l'app principale.

// Create an event that is set after device enumeration completes. We later use this event to wait for the timer to complete. 
// This event is for demonstration only in a console app. In most apps, you typically don't wait for async operations to complete.
Event enumerationCompleted(CreateEventEx(nullptr, nullptr, CREATE_EVENT_MANUAL_RESET, WRITE_OWNER | EVENT_ALL_ACCESS));
HRESULT hr = enumerationCompleted.IsValid() ? S_OK : HRESULT_FROM_WIN32(GetLastError());
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Nota

Questo evento è destinato alla dimostrazione solo come parte di un'app console. In questo esempio viene usato l'evento per assicurarsi che un'operazione asincrona venga completata prima che l'app venga chiusa. Nella maggior parte delle app, in genere non si attende il completamento delle operazioni asincrone.

Creare una factory di attivazione per l'interfaccia IDeviceWatcher .

// Get the activation factory for the IDeviceWatcher interface.
ComPtr<IDeviceInformationStatics> watcherFactory;
hr = ABI::Windows::Foundation::GetActivationFactory(HStringReference(RuntimeClass_Windows_Devices_Enumeration_DeviceInformation).Get(), &watcherFactory);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Windows Runtime usa nomi completi per identificare i tipi. Il RuntimeClass_Windows_Devices_Enumeration_DeviceInformation parametro è una stringa fornita da Windows Runtime e contiene il nome della classe di runtime richiesto.

Creare l'oggetto IDeviceWatcher.

// Create a IDeviceWatcher object from the factory.
ComPtr<IDeviceWatcher> watcher;
hr = watcherFactory->CreateWatcher(&watcher);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Usare la Callback funzione per sottoscrivere gli Addedeventi , EnumerationCompletede Stopped .

// Subscribe to the Added event.
hr = watcher->add_Added(Callback<AddedHandler>([&deviceCount](IDeviceWatcher* watcher, IDeviceInformation*) -> HRESULT
{
    // Print a message and increment the device count.
    // When we reach 10 devices, stop enumerating devices.
    wprintf_s(L"Added device...\n");
    deviceCount++;
    if (deviceCount == 10)
    {
        return watcher->Stop();
    }
    return S_OK;

}).Get(), &addedToken);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

hr = watcher->add_Stopped(Callback<StoppedHandler>([=, &enumerationCompleted](IDeviceWatcher* watcher, IInspectable*) -> HRESULT
{
    wprintf_s(L"Device enumeration stopped.\nRemoving event handlers...");

    // Unsubscribe from the events. This is shown for demonstration.
    // The need to remove event handlers depends on the requirements of 
    // your app. For instance, if you only need to handle an event for 
    // a short period of time, you might remove the event handler when you
    // no longer need it. If you handle an event for the duration of the app,
    // you might not need to explicitly remove it.
    HRESULT hr1 = watcher->remove_Added(addedToken);
    HRESULT hr2 = watcher->remove_Stopped(stoppedToken);
    HRESULT hr3 = watcher->remove_EnumerationCompleted(enumCompletedToken);

    // Set the completion event and return.
    SetEvent(enumerationCompleted.Get());

    return FAILED(hr1) ? hr1 : FAILED(hr2) ? hr2 : hr3;

}).Get(), &stoppedToken);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

// Subscribe to the EnumerationCompleted event.
hr = watcher->add_EnumerationCompleted(Callback<EnumerationCompletedHandler>([](IDeviceWatcher* watcher, IInspectable*) -> HRESULT
{
    wprintf_s(L"Enumeration completed.\n");

    return watcher->Stop();

}).Get(), &enumCompletedToken);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Il Added gestore eventi incrementa il numero di dispositivi enumerati. Arresta il processo di enumerazione dopo la ricerca di dieci dispositivi.

Il Stopped gestore eventi rimuove i gestori eventi e imposta l'evento di completamento.

Il EnumerationCompleted gestore eventi arresta il processo di enumerazione. Questo evento viene gestito nel caso in cui siano presenti meno di dieci dispositivi.

Suggerimento

In questo esempio viene usata un'espressione lambda per definire i callback. È anche possibile usare oggetti funzione (funtori), puntatori a funzione o oggetti std::function . Per altre informazioni sulle espressioni lambda, vedere Espressioni lambda in C++.

Avviare il processo di enumerazione.

wprintf_s(L"Starting device enumeration...\n");
hr = watcher->Start();
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Attendere il completamento del processo di enumerazione e quindi stampare un messaggio. Tutti gli oggetti ComPtr e RAII lasciano l'ambito e vengono rilasciati automaticamente.

// Wait for the operation to complete.
WaitForSingleObjectEx(enumerationCompleted.Get(), INFINITE, FALSE);

wprintf_s(L"Enumerated %u devices.\n", deviceCount);

// All smart pointers and RAII objects go out of scope here.

Ecco l'esempio completo:

// wrl-consume-events.cpp
// compile with: runtimeobject.lib
#include <Windows.Devices.Enumeration.h>
#include <wrl/event.h>
#include <stdio.h>

using namespace ABI::Windows::Devices::Enumeration;
using namespace ABI::Windows::Foundation;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;

// Prints an error string for the provided source code line and HRESULT
// value and returns the HRESULT value as an int.
int PrintError(unsigned int line, HRESULT hr)
{
    wprintf_s(L"ERROR: Line:%d HRESULT: 0x%X\n", line, hr);
    return hr;
}

int wmain()
{
    // Type define the event handler types to make the code more readable.
    typedef __FITypedEventHandler_2_Windows__CDevices__CEnumeration__CDeviceWatcher_Windows__CDevices__CEnumeration__CDeviceInformation AddedHandler;
    typedef __FITypedEventHandler_2_Windows__CDevices__CEnumeration__CDeviceWatcher_IInspectable EnumerationCompletedHandler;
    typedef __FITypedEventHandler_2_Windows__CDevices__CEnumeration__CDeviceWatcher_IInspectable StoppedHandler;

    // Counts the number of enumerated devices.
    unsigned int deviceCount = 0;

    // Event registration tokens that enable us to later unsubscribe from events.
    EventRegistrationToken addedToken;
    EventRegistrationToken stoppedToken;
    EventRegistrationToken enumCompletedToken;

    // Initialize the Windows Runtime.
    RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
    if (FAILED(initialize))
    {
        return PrintError(__LINE__, initialize);
    }

    // Create an event that is set after device enumeration completes. We later use this event to wait for the timer to complete. 
    // This event is for demonstration only in a console app. In most apps, you typically don't wait for async operations to complete.
    Event enumerationCompleted(CreateEventEx(nullptr, nullptr, CREATE_EVENT_MANUAL_RESET, WRITE_OWNER | EVENT_ALL_ACCESS));
    HRESULT hr = enumerationCompleted.IsValid() ? S_OK : HRESULT_FROM_WIN32(GetLastError());
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Get the activation factory for the IDeviceWatcher interface.
    ComPtr<IDeviceInformationStatics> watcherFactory;
    hr = ABI::Windows::Foundation::GetActivationFactory(HStringReference(RuntimeClass_Windows_Devices_Enumeration_DeviceInformation).Get(), &watcherFactory);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Create a IDeviceWatcher object from the factory.
    ComPtr<IDeviceWatcher> watcher;
    hr = watcherFactory->CreateWatcher(&watcher);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Subscribe to the Added event.
    hr = watcher->add_Added(Callback<AddedHandler>([&deviceCount](IDeviceWatcher* watcher, IDeviceInformation*) -> HRESULT
    {
        // Print a message and increment the device count.
        // When we reach 10 devices, stop enumerating devices.
        wprintf_s(L"Added device...\n");
        deviceCount++;
        if (deviceCount == 10)
        {
            return watcher->Stop();
        }
        return S_OK;

    }).Get(), &addedToken);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    hr = watcher->add_Stopped(Callback<StoppedHandler>([=, &enumerationCompleted](IDeviceWatcher* watcher, IInspectable*) -> HRESULT
    {
        wprintf_s(L"Device enumeration stopped.\nRemoving event handlers...");

        // Unsubscribe from the events. This is shown for demonstration.
        // The need to remove event handlers depends on the requirements of 
        // your app. For instance, if you only need to handle an event for 
        // a short period of time, you might remove the event handler when you
        // no longer need it. If you handle an event for the duration of the app,
        // you might not need to explicitly remove it.
        HRESULT hr1 = watcher->remove_Added(addedToken);
        HRESULT hr2 = watcher->remove_Stopped(stoppedToken);
        HRESULT hr3 = watcher->remove_EnumerationCompleted(enumCompletedToken);

        // Set the completion event and return.
        SetEvent(enumerationCompleted.Get());

        return FAILED(hr1) ? hr1 : FAILED(hr2) ? hr2 : hr3;

    }).Get(), &stoppedToken);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Subscribe to the EnumerationCompleted event.
    hr = watcher->add_EnumerationCompleted(Callback<EnumerationCompletedHandler>([](IDeviceWatcher* watcher, IInspectable*) -> HRESULT
    {
        wprintf_s(L"Enumeration completed.\n");

        return watcher->Stop();

    }).Get(), &enumCompletedToken);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    wprintf_s(L"Starting device enumeration...\n");
    hr = watcher->Start();
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Wait for the operation to complete.
    WaitForSingleObjectEx(enumerationCompleted.Get(), INFINITE, FALSE);

    wprintf_s(L"Enumerated %u devices.\n", deviceCount);

    // All smart pointers and RAII objects go out of scope here.
}
/*
Sample output:
Starting device enumeration...
Added device...
Added device...
Added device...
Added device...
Added device...
Added device...
Added device...
Added device...
Added device...
Added device...
Device enumeration stopped.
Removing event handlers...
Enumerated 10 devices.
*/

Compilazione del codice

Per compilare il codice, copiarlo e incollarlo in un progetto di Visual Studio oppure incollarlo in un file denominato wrl-consume-events.cpp e quindi eseguire il comando seguente in una finestra del prompt dei comandi di Visual Studio.

cl.exe wrl-consume-events.cpp runtimeobject.lib

Vedi anche

Libreria modelli C++ per Windows Runtime

Procedura: gestire eventi mediante WRL

Sottoscrizione e gestione di eventi

Compilazione del codice

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive