如何：使用 WRL 處理事件

發行項
08/03/2024

本文件說明如何使用 Windows 執行階段 C++ 範本連結庫（WRL）來訂閱及處理 Windows 執行階段物件的事件。

如需建立該元件實例並擷取屬性值的更基本範例，請參閱如何：啟動和使用 Windows 執行階段元件。

訂閱和處理事件

下列步驟會 ABI::Windows::System::Threading::IDeviceWatcher 啟動物件，並使用事件處理程式來監視進度。介面 IDeviceWatcher 可讓您以異步方式或背景列舉裝置，並在新增、移除或變更裝置時接收通知。 Callback 函式是此範例的重要部分，因為它可讓函式指定事件處理程式來處理背景作業的結果。完整的范例如下。

警告

雖然您通常會在通用 Windows 平台應用程式中使用 Windows 執行階段 C++ 範本連結庫，但此範例會使用控制台應用程式來說明。這類wprintf_s函式無法從通用 Windows 平台應用程式取得。如需您可以在通用 Windows 平台應用程式中使用之類型和函式的詳細資訊，請參閱通用 Windows 平台應用程式和適用於 UWP 應用程式的 Win32 和 COM 中不支援的 CRT 函式。

包含（#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);
}

建立 Event 物件，將列舉程式的完成同步處理至主要應用程式。

// 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事件處理程式會遞增列舉裝置的計數。在找到十個裝置之後，它會停止列舉程式。

Stopped事件處理程式會移除事件處理程式，並設定完成事件。

EnumerationCompleted事件處理程式會停止列舉進程。如果裝置少於十個，我們會處理此事件。

提示

此範例會使用 Lambda 表達式來定義回呼。您也可以使用函式物件（functors）、函式指標或 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 處理事件

訂閱和處理事件

編譯程式碼

另請參閱

意見反應

其他資源