Abrufen von unterstützten Dienstereignissen

Die WpdServicesApiSample-Anwendung enthält Code, der veranschaulicht, wie eine Anwendung die von einem bestimmten Kontaktdienst unterstützten Ereignisse abrufen kann, indem Methoden auf den folgenden Schnittstellen aufgerufen werden.

Schnittstelle Beschreibung
IPortableDeviceService Wird verwendet, um die IPortableDeviceServiceCapabilities-Schnittstelle abzurufen, um auf die unterstützten Ereignisse zuzugreifen.
IPortableDeviceServiceCapabilities Bietet Zugriff auf die unterstützten Ereignisse und Ereignisattribute.
IPortableDevicePropVariantCollection Enthält die Liste der unterstützten Ereignisse.
IPortableDeviceValues Enthält die Attribute für ein bestimmtes Ereignis.

 

Wenn der Benutzer die Option "4" in der Befehlszeile wählt, ruft die Anwendung die ListSupportedEvents-Methode auf, die im ServiceCapabilities.cpp-Modul gefunden wird.

Beachten Sie, dass die Beispielanwendung vor dem Abrufen der Liste der Ereignisse einen Kontaktdienst auf einem verbundenen Gerät öffnet.

In WPD wird ein Ereignis durch seinen Namen, optionen und Parameter beschrieben. Der Ereignisname ist eine skriptfreundliche Zeichenfolge, z. B. "MyCustomEvent". Die Ereignisoptionen geben an, ob ein bestimmtes Ereignis an alle Clients übertragen wird und ob dieses Ereignis die automatische Wiedergabe unterstützt. Die Ereignisparameterattribute umfassen die PROPERTYKEY- und VARTYPE-Eigenschaften eines bestimmten Parameters.

Vier Methoden im ServiceCapabilities.cpp-Modul unterstützen den Abruf von unterstützten Ereignissen für den angegebenen Kontaktdienst: ListSupportedEvents, DisplayEventOptions und DisplayEventParameters. Die ListSupportedEvents-Methode ruft eine Anzahl von unterstützten Ereignissen und den GUID-Bezeichner für jedes Ereignis ab. Die DisplayEvent-Methode zeigt den Ereignisnamen oder die GUID an, und ruft dann DisplayEventOptions und DisplayEventParameters auf, um die ereignisbezogenen Daten anzuzeigen.

Die ListSupportedEvents-Methode ruft die IPortableDeviceService::Capabilities-Methode auf, um eine IPortableDeviceServiceCapabilities-Schnittstelle abzurufen. Mithilfe dieser Schnittstelle ruft sie die unterstützten Ereignisse ab, indem sie die IPortableDeviceServiceCapabilities::GetSupportedEvents-Methode aufrufen. Die GetSupportedEvents-Methode ruft die GUIDs für jedes Ereignis ab, das vom Dienst unterstützt wird, und kopiert diese GUIDs in ein IPortableDevicePropVariantCollection-Objekt .

Der folgende Code veranschaulicht das Abrufen von unterstützten Dienstereignissen.

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

Nachdem die ListSupportedEvents-Methode die GUIDs abgerufen hat, die jedes ereignis darstellen, das vom angegebenen Dienst unterstützt wird, wird die DisplayEvent-Methode aufgerufen, um ereignisspezifische Daten abzurufen. Diese Daten umfassen den Ereignisnamen, seine Optionen (Übertragung oder automatische Wiedergabe), Parameter-GUIDs, Parametertypen usw.

Die DisplayEvent-Methode ruft die IPortableDeviceServiceCapabilities::GetEventAttributes-Methode auf, um eine Auflistung von Attributen für das angegebene Ereignis abzurufen. Anschließend wird die IPortableDeviceValues::GetStringValue-Methode aufgerufen und fordert an, dass der Treiber einen benutzerdefinierten Namen für das angegebene Ereignis zurückgibt. Als Nächstes ruft DisplayEvent die IPortableDeviceValues::GetIPortableDeviceValuesValueValuevalue auf, um die Ereignisoptionen abzurufen. Schließlich ruft DisplayEvent die IPortableDeviceValues::GetIPortableDeviceKeyCollectionValue auf, um die Liste der Ereignisparameter abzurufen. Es übergibt die von diesen Methoden zurückgegebenen Daten an die DisplayEventOptions- und displayEventParameters-Hilfsfunktionen, die die Optionen und Parameterinformationen für das angegebene Ereignis rendern.

Der folgende Code verwendet die DisplayEvent-Methode .

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

Die Hilfsfunktion "DisplayEventOptions" empfängt ein IPortableDeviceValues-Objekt , das die Optionsdaten des Ereignisses enthält. Anschließend wird die IPortableDeviceValues::GetBoolValue-Methode aufgerufen, um die Optionsdaten abzurufen. Mithilfe dieser Daten wird eine Zeichenfolge gerendert, die angibt, ob die Übertragungs- und Automatischwiedergabeoptionen unterstützt werden.

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