Retrieving Properties for a Single Object

After your application retrieves an object identifier (see the Enumerating Content topic) for a given object, it can retrieve descriptive information about that object by calling methods in the IPortableDeviceProperties interface and the IPortableDeviceKeyCollection interface.

The IPortableDeviceProperties::GetValues method retrieves a list of specified properties for a given object. (Your application could also call the GetValues method and specify a NULL value for the pKeys parameter to retrieve all properties for a given object; however, the performance of this method may be significantly slower when retrieving all properties.)

Before your application calls GetValues, however, it needs to identify the properties to retrieve by setting corresponding keys in an IPortableDeviceKeyCollection object. Your application will identify the properties of interest by calling the IPortableDeviceKeyCollection::Add method and supplying a PROPERTYKEY value that identifies each property that it will retrieve.

The ReadContentProperties function in the ContentProperties.cpp module of the sample application demonstrates how the five properties were retrieved for a selected object. The following table describes each of these properties and their corresponding REFPROPERTYKEY value.

Property	Description	PROPERTYKEY
Parent-object identifier	A string that specifies the identifier for the given object's parent.	WPD_OBJECT_PARENT_ID
Object name	A string that specifies the name of the given object.	WPD_OBJECT_NAME
Persistent unique identifier	A string that specifies a unique identifier for the given object. (This identifier is persistent across sessions, unlike the object identifier.)	WPD_OBJECT_PERSISTENT_UNIQUE_ID
Object format	A globally unique identifier (GUID) that specifies the format of the file corresponding to a given object.	WPD_OBJECT_FORMAT
Object content type	A GUID that specifies the type of content associated with a given object.	WPD_OBJECT_CONTENT_TYPE

 

The following excerpt from the ReadContentProperties function demonstrates how the sample application used the IPortableDeviceKeyCollection interface and the IPortableDeviceKeyCollection::Add method to identify the properties it would retrieve.

hr = CoCreateInstance(CLSID_PortableDeviceKeyCollection,
                      NULL,
                      CLSCTX_INPROC_SERVER,
                      IID_PPV_ARGS(&pPropertiesToRead));
if (SUCCEEDED(hr))
{
    // 4) Populate the IPortableDeviceKeyCollection with the keys we wish to read.
    // NOTE: We are not handling any special error cases here so we can proceed with
    // adding as many of the target properties as we can.
    if (pPropertiesToRead != NULL)
    {
        HRESULT hrTemp = S_OK;
        hrTemp = pPropertiesToRead->Add(WPD_OBJECT_PARENT_ID);
        if (FAILED(hrTemp))
        {
            printf("! Failed to add WPD_OBJECT_PARENT_ID to IPortableDeviceKeyCollection, hr= 0x%lx\n", hrTemp);
        }

        hrTemp = pPropertiesToRead->Add(WPD_OBJECT_NAME);
        if (FAILED(hrTemp))
        {
            printf("! Failed to add WPD_OBJECT_NAME to IPortableDeviceKeyCollection, hr= 0x%lx\n", hrTemp);
        }

        hrTemp = pPropertiesToRead->Add(WPD_OBJECT_PERSISTENT_UNIQUE_ID);
        if (FAILED(hrTemp))
        {
            printf("! Failed to add WPD_OBJECT_PERSISTENT_UNIQUE_ID to IPortableDeviceKeyCollection, hr= 0x%lx\n", hrTemp);
        }

        hrTemp = pPropertiesToRead->Add(WPD_OBJECT_FORMAT);
        if (FAILED(hrTemp))
        {
            printf("! Failed to add WPD_OBJECT_FORMAT to IPortableDeviceKeyCollection, hr= 0x%lx\n", hrTemp);
        }

        hrTemp = pPropertiesToRead->Add(WPD_OBJECT_CONTENT_TYPE);
        if (FAILED(hrTemp))
        {
            printf("! Failed to add WPD_OBJECT_CONTENT_TYPE to IPortableDeviceKeyCollection, hr= 0x%lx\n", hrTemp);
        }
    }
}

Once the sample application set the appropriate keys, it called the IPortableDeviceProperties::GetValues method to retrieve the specified values for the given object.

if (SUCCEEDED(hr))
{
    hr = pProperties->GetValues(szSelection,         // The object whose properties we are reading
                                pPropertiesToRead,   // The properties we want to read
                                &pObjectProperties); // Driver supplied property values for the specified object
    if (FAILED(hr))
    {
        printf("! Failed to get all properties for object '%ws', hr= 0x%lx\n", szSelection, hr);
    }
}

Related topics

IPortableDevice Interface

IPortableDeviceKeyCollection Interface

IPortableDeviceProperties Interface

Programming Guide