如何：使用 WRL 处理事件

项目
10/17/2023

本文档演示如何使用 Windows 运行时 C++ 模板库 (WRL) 订阅和处理 Windows 运行时对象的事件。

有关创建该组件的实例并检索属性值的更基本示例，请参阅操作说明：激活和使用 Windows 运行时组件。

订阅和处理事件

以下步骤启动对象 ABI::Windows::System::Threading::IDeviceWatcher，并使用事件处理程序监视进度。通过接口 IDeviceWatcher，可以在添加、删除或更改设备时异步或在后台枚举设备并接收通知。 Callback 函数是此示例的重要组成部分，因为通过它可以指定处理后台操作结果的事件处理程序。之后提供了完整示例。

警告

尽管通常在通用 Windows 平台应用中使用 Windows 运行时 C++ 模板库，但此示例使用控制台应用进行演示。通用 Windows 平台应用中不可使用 wprintf_s 等函数。有关可在通用 Windows 平台应用中使用的类型和函数的详细信息，请参阅通用 Windows 平台应用中不支持的 CRT 函数和适用于 UWP 应用的 Win32 和 COM。

包括 (#include) 任何所需的 Windows 运行时、Windows 运行时 C++ 模板库或 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 声明枚举设备所需的类型。

我们建议您在 .cpp 文件中使用 using namespace 指令使代码更具可读性。

声明应用的局部变量。此示例保留枚举设备和注册令牌的数量计数，以便之后取消订阅事件。

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

初始化 Windows 运行时。

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

注意

此事件仅作为控制台应用的一部分进行演示。此示例使用该事件确保退出应用之前完成异步操作。在大多数应用中，你通常不会等待异步操作完成。

为 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 运行时使用完全限定名来标识类型。 RuntimeClass_Windows_Devices_Enumeration_DeviceInformation 参数是 Windows 运行时提供的字符串，其中包含所需的运行时类名称。

创建 IDeviceWatcher 对象。

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

使用 Callback 函数订阅 Added、EnumerationCompleted 和 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);
}

Added 事件处理程序递增枚举设备的计数。在找到 10 个设备后，它会停止枚举过程。

Stopped 事件处理程序删除事件处理程序并设置完成事件。

EnumerationCompleted 事件处理程序停止枚举过程。如果设备少于 10 个，我们将处理此事件。

提示

此示例使用 lambda 表达式定义回调。还可以使用函数对象（函子）、函数指针或 std::function 对象。有关 lambda 表达式的详细信息，请参阅 Lambda 表达式。

启动枚举过程。

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

等待枚举过程完成，然后输出消息。所有 ComPtr 和 RAII 对象都离开范围并自动释放。

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

以下是完整示例：

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

编译代码

若要编译代码，请复制代码并将其粘贴到 Visual Studio 项目中，或粘贴到一个名为 wrl-consume-events.cpp 的文件中，然后在 Visual Studio 命令提示符窗口中运行以下命令。

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

另请参阅

Windows 运行时 C++ 模板库 (WRL)

通过

如何：使用 WRL 处理事件

订阅和处理事件

编译代码

另请参阅

反馈

其他资源