Edit

IPortableDevicePropertiesBulk::QueueGetValuesByObjectFormat method (portabledeviceapi.h)

  • Article

The QueueGetValuesByObjectFormat interface queues a request for properties of objects of a specific format on a device.

Syntax

HRESULT QueueGetValuesByObjectFormat(
  [in]  REFGUID                               pguidObjectFormat,
  [in]  LPCWSTR                               pszParentObjectID,
  [in]  const DWORD                           dwDepth,
  [in]  IPortableDeviceKeyCollection          *pKeys,
  [in]  IPortableDevicePropertiesBulkCallback *pCallback,
  [out] GUID                                  *pContext
);

Parameters

[in] pguidObjectFormat

Pointer to a GUID that specifies the object format. Only objects of this type are queried.

[in] pszParentObjectID

Pointer to a null-terminated string that contains the object ID of the parent object where the search should begin. To search all the objects on a device, specify WPD_DEVICE_OBJECT_ID.

[in] dwDepth

The maximum depth to search below the parent, where 1 means immediate children only. It is acceptable for this number to be greater than the actual number of levels. To search to any depth, specify 0xFFFFFFFF

[in] pKeys

Pointer to an IPortableDeviceKeyCollection interface that contains the properties to retrieve. For a list of properties that are defined by Windows Portable Devices, see Properties and Attributes. Specify NULL to indicate all properties from the specified format.

[in] pCallback

Pointer to an application-implemented IPortableDevicePropertiesBulkCallback interface that will receive the information as it is retrieved.

[out] pContext

Pointer to a GUID that will be used to start, cancel, or identify the request in IPortableDevicePropertiesBulkCallback callbacks, if implemented.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code Description
S_OK
 The operation was queued successfully.

Remarks

If you specify WPD_OBJECT_FORMAT_ALL for the pguidObjectFormat parameter, this method will return properties for all objects on the device.

If the pszParentObjectID parameter is set to an empty string (""), the method will perform a search that is dependent on the dwDepth parameter as described in the following table.

dwDepth Method returns
0 No results
1 Values for the specified device only.
2 Values for the specified device and all functional objects found on that device.
 

If the pszParentObjectID parameter is set to WPD_DEVICE_OBJECT_ID, the method will perform a search that is dependent on the dwDepth parameter as described in the following table.

dwDepth Method returns
0 Values for the specified device only.
1 Values for the specified device and all functional objects found on that device.
 

The queued request is not started until the application calls Start. For more information on how to use this method, see IPortableDevicePropertiesBulk Interface.

Due to performance issues, some devices may not return a comprehensive list of properties when the pKeys parameter is NULL.

Requirements

Requirement Value
Target Platform Windows
Header portabledeviceapi.h
Library PortableDeviceGUIDs.lib

See also

IPortableDevicePropertiesBulk Interface