Edit

Retrieving the Functional Categories Supported by a Device

  • Article

Windows Portable Devices may support one or more functional categories. These categories are described in the following table.

Category Description
Audio capture The device can be used to record audio.
Rendering information The device provides data describing the media files that it is capable of rendering.
Short message service (SMS) The device supports text messaging.
Still image capture The device can be used to capture still images.
Storage The device can be used to store files.

 

The ListFunctionalCategories function in the DeviceCapabilities.cpp module demonstrates the retrieval of functional categories for a selected device.

Your application can retrieve the functional categories supported by a device by using the interfaces described in the following table.

Interface Description
IPortableDeviceCapabilities Interface Provides access to the functional-category retrieval methods.
IPortableDevicePropVariantCollection Interface Used to enumerate and store functional-category data.

 

The first task accomplished by the sample application is the retrieval of an IPortableDeviceCapabilities object, which is used to retrieve the functional categories on the selected device.

HRESULT hr = S_OK;
CComPtr<IPortableDeviceCapabilities>            pCapabilities;
CComPtr<IPortableDevicePropVariantCollection>   pCategories;
DWORD dwNumCategories = 0;

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

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

// Get all functional categories supported by the device.
if (SUCCEEDED(hr))
{
    hr = pCapabilities->GetFunctionalCategories(&pCategories);
    if (FAILED(hr))
    {
        printf("! Failed to get functional categories from the device, hr = 0x%lx\n",hr);
    }
}

The retrieved categories are stored in an IPortableDevicePropVariantCollection object.

The next step is the enumeration and display of the supported categories. The first step that the sample application accomplishes is to retrieve the count of supported categories. It then uses this count to iterate through the IPortableDevicePropVariantCollection object that contains the supported categories.

if (SUCCEEDED(hr))
{
    hr = pCategories->GetCount(&dwNumCategories);
    if (FAILED(hr))
    {
        printf("! Failed to get number of functional categories, hr = 0x%lx\n",hr);
    }
}

printf("\n%d Functional Categories Found on the device\n\n", dwNumCategories);

// Loop through each functional category and display its name
if (SUCCEEDED(hr))
{
    for (DWORD dwIndex = 0; dwIndex < dwNumCategories; dwIndex++)
    {
        PROPVARIANT pv = {0};
        PropVariantInit(&pv);
        hr = pCategories->GetAt(dwIndex, &pv);
        if (SUCCEEDED(hr))
        {
            // We have a functional category.  It is assumed that
            // functional categories are returned as VT_CLSID
            // VarTypes.

            if (pv.puuid != NULL)
            {
                // Display the functional category name
                DisplayFunctionalCategory(*pv.puuid);
                printf("\n");
            }
        }

        PropVariantClear(&pv);
    }
}

IPortableDevice Interface

IPortableDeviceCapabilities Interface

IPortableDevicePropVariantCollection Interface

Programming Guide