Cómo: Controlar eventos mediante WRL

Artículo
04/03/2023

En este documento se muestra cómo usar la biblioteca de plantillas de Windows Runtime C++ (WRL) para suscribirse a los eventos de un objeto de Windows Runtime y controlarlo.

Para obtener un ejemplo más básico que crea una instancia de un componente y recupera un valor de propiedad, vea Cómo: Activar y usar un componente de Windows Runtime.

Subscripción a eventos y control de estos

Los pasos siguientes inician un objeto ABI::Windows::System::Threading::IDeviceWatcher y usan controladores de eventos para supervisar el progreso. La interfaz IDeviceWatcher permite enumerar los dispositivos de forma asincrónica, o en segundo plano, y recibir notificaciones cuando se agregan, quitan o cambian los dispositivos. La función Callback es una parte importante de este ejemplo porque permite especificar controladores de eventos que procesan los resultados de la operación en segundo plano. A continuación se muestra el ejemplo completo.

Advertencia

Aunque normalmente se utiliza la biblioteca de plantillas de Windows Runtime C++ en una aplicación de la Plataforma universal de Windows, este ejemplo utiliza una aplicación de consola a modo de ilustración. Funciones como wprintf_s no están disponibles en una aplicación de Plataforma universal de Windows. Para más información sobre los tipos y funciones que puede utilizar en una aplicación para Plataforma universal de Windows, consulte Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows y Win32 y COM para aplicaciones para UWP.

Incluya (#include) cualquier encabezado requerido de Windows Runtime, la biblioteca de plantillas de Windows Runtime C++ o la Biblioteca estándar de 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 declara los tipos necesarios para enumerar los dispositivos.

Se recomienda que use la directiva using namespace en el archivo .cpp para que el código sea más legible.

Declare las variables locales para la aplicación. Este ejemplo mantiene el recuento del número de dispositivos enumerados y los tokens de registro que le permiten cancelar posteriormente la suscripción de los eventos.

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

Inicialice Windows Runtime.

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

Cree un objeto Event que sincronice la finalización del proceso de enumeración con la aplicación principal.

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

Este evento es para demostración solo como parte de una aplicación de consola. En este ejemplo se usa el evento para asegurarse de que se completa una operación asincrónica antes de que se cierre la aplicación. En la mayoría de las aplicaciones, normalmente no espera a que se completen las operaciones asincrónicas.

Cree un generador de activación para la interfaz 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 nombres completos para identificar tipos. El parámetro RuntimeClass_Windows_Devices_Enumeration_DeviceInformation es una cadena proporcionada por Windows Runtime y contiene el nombre de clase del entorno de ejecución necesario.

Cree el objeto IDeviceWatcher.

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

Use la Callback función para suscribirse a los eventos Added, EnumerationCompleted y 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);
}

El controlador de eventos Added incrementa el recuento de dispositivos enumerados. Detiene el proceso de enumeración después de que se encuentren diez dispositivos.

El controlador de eventos Stopped quita los controladores de eventos y establece el evento de finalización.

El controlador de eventos EnumerationCompleted detiene el proceso de enumeración. Tratamos este evento en caso de que haya menos de diez dispositivos.

Sugerencia

En este ejemplo se utiliza una expresión lambda para definir las llamadas de devolución. También puede usar objetos de función (functors), punteros de función u objetos std::function . Para obtener más información sobre las expresiones lambda, vea Expresiones lambda.

Inicie el proceso de enumeración.

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

Espere a que se complete el proceso de enumeración y, a continuación, imprima un mensaje. Todos los objetos ComPtr y RAII salen del ámbito y se liberan automáticamente.

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

A continuación se incluye el ejemplo 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.
*/

Compilar el código

Para compilar el código, cópielo y péguelo en un proyecto de Visual Studio, o en un archivo denominado wrl-consume-events.cpp. A continuación, ejecute el comando siguiente en una ventana del símbolo del sistema de Visual Studio.

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

Consulte también

Biblioteca de plantillas C++ de Windows en tiempo de ejecución (WRL)

Cómo: Controlar eventos mediante WRL

Subscripción a eventos y control de estos

Compilar el código

Consulte también

Comentarios

Comentarios

Recursos adicionales