サポートされているサービス イベントの取得

WpdServicesApiSample アプリケーションには、アプリケーションが次のインターフェイスでメソッドを呼び出すことによって、特定の Contacts サービスでサポートされるイベントを取得する方法を示すコードが含まれています。

ユーザーがコマンド ラインでオプション "4" を選択すると、アプリケーションは ServiceCapabilities.cpp モジュールにある ListSupportedEvents メソッドを呼び出します。

イベントの一覧を取得する前に、サンプル アプリケーションは接続されているデバイスで連絡先サービスを開きます。

WPD では、イベントは名前、オプション、およびパラメーターによって記述されます。 イベント名は、"MyCustomEvent" など、スクリプトに適した文字列です。 イベント オプションは、特定のイベントがすべてのクライアントにブロードキャストされるかどうか、およびそのイベントが自動再生をサポートしているかどうかを示します。 イベント パラメーター属性には、指定されたパラメーターの PROPERTYKEY と VARTYPE が含まれます。

ServiceCapabilities.cpp モジュールの 4 つのメソッドは、指定された連絡先サービスでサポートされているイベントの取得をサポート しています。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