How to: Handle Events Using WRL

 

The latest version of this topic can be found at How to: Handle Events Using WRL.

This document shows how to use the Windows Runtime C++ Template Library (WRL) to subscribe to and handle the events of a Windows Runtime object.

For a more basic example that creates an instance of that component and retrieves a property value, see How to: Activate and Use a Windows Runtime Component.

Subscribing to and Handling Events

The following steps start an ABI::Windows::System::Threading::IDeviceWatcher object and use event handlers to monitor progress. The IDeviceWatcher interface enables you to enumerate devices asynchronously, or in the background, and receive notification when devices are added, removed, or changed. The Callback function is an important part of this example because it enables it to specify event handlers that process the results of the background operation. The complete example follows.

Warning

Although you typically use the WRL in a Windows 8.x Store app, this example uses a console app for illustration. Functions such as wprintf_s are not available from a Windows 8.x Store app. For more information about the types and functions that you can use in a Windows 8.x Store app, see CRT functions not supported with /ZW and Win32 and COM for Windows Store apps.

1. Include (#include) any required Windows Runtime, WRL, or standard C++ library headers.

   #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 declares the types that are required to enumerate devices.

   We recommend that you utilize the using namespace directive in your .cpp file to make the code more readable.

2. Declare the local variables for the app. This example holds count of the number of enumerated devices and registration tokens that enable it to later unsubscribe from events.

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

3. Initialize the Windows Runtime.

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

4. Create an Event object that synchronizes the completion of the enumeration process to the main app.

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

   Note

   This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don’t wait for async operations to complete.

5. Create an activation factory for the IDeviceWatcher interface.

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

   The Windows Runtime uses fully-qualified names to identify types. The RuntimeClass_Windows_Devices_Enumeration_DeviceInformation parameter is a string that's provided by the Windows Runtime and contains the required runtime class name.

6. Create the IDeviceWatcher object.

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

7. Use the Callback function to subscribe to the Added, EnumerationCompleted, and Stopped events.

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

   The Added event handler increments the count of enumerated devices. It stops the enumeration process after ten devices are found.

   The Stopped event handler removes the event handlers and sets the completion event.

   The EnumerationCompleted event handler stops the enumeration process. We handle this event in case there are fewer than ten devices.

   Tip

   This example uses a lambda expression to define the callbacks. You can also use function objects (functors), function pointers, or std::function objects. For more information about lambda expressions, see Lambda Expressions.

8. Start the enumeration process.

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

9. Wait for the enumeration process to complete and then print a message. All ComPtr and RAII objects leave scope and are released automatically.

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

Here is the complete example:

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

Compiling the Code

To compile the code, copy it and then paste it in a Visual Studio project, or paste it in a file that is named wrl-consume-events.cpp and then run the following command in a Visual Studio Command Prompt window.

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

See Also

Windows Runtime C++ Template Library (WRL)