擷取支援的服務事件

發行項
06/12/2023

WpdServicesApiSample 應用程式包含程式碼，示範應用程式如何藉由在下列介面上呼叫方法來擷取指定連絡人服務支援的事件。

介面	描述
IPortableDeviceService	用來擷取 IPortableDeviceServiceCapabilities 介面來存取支援的事件。
IPortableDeviceServiceCapabilities	提供支援事件和事件屬性的存取權。
IPortableDevicePropVariantCollection	包含支援事件的清單。
IPortableDeviceValues	包含指定事件的屬性。

當使用者在命令列選擇選項「4」時，應用程式會叫用 ServiceCapabilities.cpp 模組中找到的 ListSupportedEvents 方法。

請注意，在擷取事件清單之前，範例應用程式會在連線的裝置上開啟連絡人服務。

在 WPD 中，事件的名稱、選項和參數會加以描述。事件名稱是腳本易記字串，例如「MyCustomEvent」。事件選項會指出指定的事件是否廣播給所有用戶端，以及該事件是否支援自動執行。事件參數屬性包含指定參數的 PROPERTYKEY 和 VARTYPE。

ServiceCapabilities.cpp 模組中的四種方法支援擷取指定連絡人服務的支援事件：ListSupportedEvents、DisplayEvent、DisplayEventOptions和DisplayEventParameters。 ListSupportedEvents方法會擷取每個事件的支援事件計數和 GUID 識別碼。 DisplayEvent方法會顯示事件名稱或 GUID，然後呼叫DisplayEventOptions和DisplayEventParameters來顯示事件相關資料。

ListSupportedEvents方法會叫用IPortableDeviceService：：Capabilities方法來擷取IPortableDeviceServiceCapabilities介面。使用此介面，它會呼叫 IPortableDeviceServiceCapabilities：：GetSupportedEvents 方法來擷取支援的事件。 GetSupportedEvents方法會擷取服務所支援之每個事件的 GUID，並將這些 GUID 複製到IPortableDevicePropVariantCollection物件中。

下列程式碼說明擷取支援的服務事件。

// List all supported events on the service
void ListSupportedEvents(
    IPortableDeviceService* pService)
{
    HRESULT hr          = S_OK;
    DWORD   dwNumEvents = 0;
    CComPtr<IPortableDeviceServiceCapabilities>     pCapabilities;
    CComPtr<IPortableDevicePropVariantCollection>   pEvents;

    if (pService == NULL)
    {
        printf("! A NULL IPortableDeviceService interface pointer was received\n");
        return;
    }

    // Get an IPortableDeviceServiceCapabilities interface from the IPortableDeviceService interface to
    // access the service capabilities-specific methods.
    hr = pService->Capabilities(&pCapabilities);
    if (FAILED(hr))
    {
        printf("! Failed to get IPortableDeviceServiceCapabilities from IPortableDeviceService, hr = 0x%lx\n",hr);
    }

    // Get all events supported by the service.
    if (SUCCEEDED(hr))
    {
        hr = pCapabilities->GetSupportedEvents(&pEvents);
        if (FAILED(hr))
        {
            printf("! Failed to get supported events from the service, hr = 0x%lx\n",hr);
        }
    }

    // Get the number of supported events found on the service.
    if (SUCCEEDED(hr))
    {
        hr = pEvents->GetCount(&dwNumEvents);
        if (FAILED(hr))
        {
            printf("! Failed to get number of supported events, hr = 0x%lx\n",hr);
        }
    }

    printf("\n%d Supported Events Found on the service\n\n", dwNumEvents);

    // Loop through each event and display it
    if (SUCCEEDED(hr))
    {
        for (DWORD dwIndex = 0; dwIndex < dwNumEvents; dwIndex++)
        {
            PROPVARIANT pv = {0};
            PropVariantInit(&pv);
            hr = pEvents->GetAt(dwIndex, &pv);

            if (SUCCEEDED(hr))
            {
                // We have an event.  It is assumed that
                // events are returned as VT_CLSID VarTypes.
                if (pv.puuid != NULL)
                {
                    DisplayEvent(pCapabilities, *pv.puuid);
                    printf("\n");
                }
            }

            PropVariantClear(&pv);
        }
    }
}

當 ListSupportedEvents方法擷取代表指定服務所支援之每個事件的 GUID 之後，它會叫用DisplayEvent方法來擷取事件特定資料。此資料包括事件名稱、其選項 (廣播或自動執行) 、參數 GUID、參數類型等等。

DisplayEvent方法會叫用IPortableDeviceServiceCapabilities：：GetEventAttributes方法，以擷取指定事件的屬性集合。然後它會呼叫 IPortableDeviceValues：：GetStringValue 方法，並要求驅動程式傳回指定事件的使用者易記名稱。接下來， DisplayEvent 會呼叫 IPortableDeviceValues：：GetIPortableDeviceValuesValue 來擷取事件選項。最後，DisplayEvent 會呼叫 IPortableDeviceValues：：GetIPortableDeviceKeyCollectionValue 來擷取事件參數清單。它會將這些方法傳回的資料傳遞至 DisplayEventOptions 和 DisplayEventParameters 協助程式函式，以轉譯指定事件的選項和參數資訊。

下列程式碼使用 DisplayEvent 方法。

// Display basic information about an event
void DisplayEvent(
    IPortableDeviceServiceCapabilities* pCapabilities,
    REFGUID                             Event)
{
    CComPtr<IPortableDeviceValues> pAttributes;

    // Get the event attributes which describe the event
    HRESULT hr = pCapabilities->GetEventAttributes(Event, &pAttributes);
    if (FAILED(hr))
    {
        printf("! Failed to get the event attributes, hr = 0x%lx\n",hr);
    }

    if (SUCCEEDED(hr))
    {
        PWSTR pszFormatName = NULL;
        CComPtr<IPortableDeviceValues>          pOptions;
        CComPtr<IPortableDeviceKeyCollection>   pParameters;

        // Display the name of the event if it is available. Otherwise, fall back to displaying the GUID.
        hr = pAttributes->GetStringValue(WPD_EVENT_ATTRIBUTE_NAME, &pszFormatName);
        if (SUCCEEDED(hr))
        {
            printf("%ws\n", pszFormatName);
        }
        else
        {
            printf("%ws\n", (PWSTR)CGuidToString(Event));
        }       

        // Display the event options
        hr = pAttributes->GetIPortableDeviceValuesValue(WPD_EVENT_ATTRIBUTE_OPTIONS, &pOptions);
        if (SUCCEEDED(hr))
        {
            DisplayEventOptions(pOptions);
        }
        else
        {
            printf("! Failed to get the event options, hr = 0x%lx\n", hr);
        }       

        // Display the event parameters
        hr = pAttributes->GetIPortableDeviceKeyCollectionValue(WPD_EVENT_ATTRIBUTE_PARAMETERS, &pParameters);
        if (SUCCEEDED(hr))
        {
            DisplayEventParameters(pCapabilities, Event, pParameters);
        }
        else
        {
            printf("! Failed to get the event parameters, hr = 0x%lx\n", hr);
        }       
        
        CoTaskMemFree(pszFormatName);
        pszFormatName = NULL;
    }
}

DisplayEventOptions協助程式函式會接收包含事件選項資料的IPortableDeviceValues物件。然後它會呼叫 IPortableDeviceValues：：GetBoolValue 方法來擷取選項資料。使用此資料，它會轉譯字串，指出是否支援廣播和自動播放選項。

// Display the basic event options.
void DisplayEventOptions(
    IPortableDeviceValues* pOptions)
{
    printf("\tEvent Options:\n");
    // Read the WPD_EVENT_OPTION_IS_BROADCAST_EVENT value to see if the event is
    // a broadcast event. If the read fails, assume FALSE
    BOOL  bIsBroadcastEvent = FALSE;
    pOptions->GetBoolValue(WPD_EVENT_OPTION_IS_BROADCAST_EVENT, &bIsBroadcastEvent);
    printf("\tWPD_EVENT_OPTION_IS_BROADCAST_EVENT = %ws\n",bIsBroadcastEvent ? L"TRUE" : L"FALSE");
}

IPortableDeviceKeyCollection
IPortableDeviceService
IPortableDeviceServiceCapabilities
IPortableDeviceValues
WpdServicesApiSample

擷取支援的服務事件

意見反應

意見反應

其他資源

擷取支援的服務事件

相關主題

意見反應

意見反應

其他資源