如何：使用 WRL 處理事件

本檔說明如何使用 Windows 執行階段 C++ 樣板庫 （WRL）訂閱及處理Windows 執行階段物件的事件。

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

訂閱和處理事件

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

警告

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

1. 包含 （ #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 指示詞，讓程式碼更容易閱讀。

2. 宣告應用程式的區域變數。 此範例會保留列舉裝置數目和註冊權杖的計數，以便稍後取消訂閱事件。

   // 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. 初始化Windows 執行階段。

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

4. 建立 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);
   }
   

   注意

   此事件僅供作為主控台應用程式的一部分進行示範。 此範例會使用 事件來確保非同步作業在應用程式結束之前完成。 在大部分的應用程式中，您通常不會等待非同步作業完成。

5. 建立 介面的 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 執行階段所提供的字串，並包含必要的執行時間類別名稱。

6. IDeviceWatcher建立 物件。

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

7. 使用 函式 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 運算式。

8. 啟動列舉程式。

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

9. 等候列舉程式完成，然後列印訊息。 所有 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)