Récupération des événements de service pris en charge

L’application WpdServicesApiSample inclut du code qui montre comment une application peut récupérer les événements pris en charge par un service Contacts donné en appelant des méthodes sur les interfaces suivantes.

Lorsque l’utilisateur choisit l’option « 4 » sur la ligne de commande, l’application appelle la méthode ListSupportedEvents qui se trouve dans le module ServiceCapabilities.cpp.

Notez qu’avant de récupérer la liste des événements, l’exemple d’application ouvre un service Contacts sur un appareil connecté.

Dans WPD, un événement est décrit par son nom, ses options et ses paramètres. Le nom de l’événement est une chaîne compatible avec les scripts, par exemple , « MyCustomEvent ». Les options d’événement indiquent si un événement donné est diffusé à tous les clients et si cet événement prend en charge la lecture automatique. Les attributs des paramètres d’événement incluent propertyKEY et VARTYPE d’un paramètre donné.

Quatre méthodes du module ServiceCapabilities.cpp prennent en charge la récupération des événements pris en charge pour le service Contacts donné : ListSupportedEvents, DisplayEvent, DisplayEventOptions et DisplayEventParameters. La méthode ListSupportedEvents récupère le nombre d’événements pris en charge et l’identificateur GUID pour chaque événement. La méthode DisplayEvent affiche le nom ou le GUID de l’événement, puis appelle DisplayEventOptions et DisplayEventParameters pour afficher les données liées à l’événement.

La méthode ListSupportedEvents appelle la méthode IPortableDeviceService::Capabilities pour récupérer une interface IPortableDeviceServiceCapabilities . À l’aide de cette interface, il récupère les événements pris en charge en appelant la méthode IPortableDeviceServiceCapabilities::GetSupportedEvents . La méthode GetSupportedEvents récupère les GUID de chaque événement pris en charge par le service et copie ces GUID dans un objet IPortableDevicePropVariantCollection .

Le code suivant illustre la récupération des événements de service pris en charge.

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

Une fois que la méthode ListSupportedEvents a récupéré les GUID représentant chaque événement pris en charge par le service donné, elle appelle la méthode DisplayEvent pour récupérer des données spécifiques à l’événement. Ces données incluent le nom de l’événement, ses options (diffusion ou lecture automatique), les GUID de paramètre, les types de paramètres, etc.

La méthode DisplayEvent appelle la méthode IPortableDeviceServiceCapabilities::GetEventAttributes pour récupérer une collection d’attributs pour l’événement donné. Il appelle ensuite la méthode IPortableDeviceValues::GetStringValue et demande que le pilote retourne un nom convivial pour l’événement donné. Ensuite, DisplayEvent appelle IPortableDeviceValues::GetIPortableDeviceValuesValuesValue pour récupérer les options d’événement. Enfin, DisplayEvent appelle IPortableDeviceValues::GetIPortableDeviceKeyCollectionValue pour récupérer la liste des paramètres d’événement. Il transmet les données retournées par ces méthodes aux fonctions d’assistance DisplayEventOptions et DisplayEventParameters , qui affichent les options et les informations de paramètre pour l’événement donné.

Le code suivant utilise la méthode 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;
    }
}

La fonction d’assistance DisplayEventOptions reçoit un objet IPortableDeviceValues qui contient les données d’option de l’événement. Il appelle ensuite la méthode IPortableDeviceValues::GetBoolValue pour récupérer les données d’options. À l’aide de ces données, il affiche une chaîne indiquant si les options de diffusion et de lecture automatique sont prises en charge.

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

Rubriques connexes

IPortableDeviceKeyCollection

IPortableDeviceService

IPortableDeviceServiceCapabilities

IPortableDeviceValues

WpdServicesApiSample