SetupDiGetDevicePropertyKeys function (setupapi.h)

Article
10/13/2021

The SetupDiGetDevicePropertyKeys function retrieves an array of the device property keys that represent the device properties that are set for a device instance.

Syntax

WINSETUPAPI BOOL SetupDiGetDevicePropertyKeys(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [out, optional] DEVPROPKEY       *PropertyKeyArray,
  [in]            DWORD            PropertyKeyCount,
  [out, optional] PDWORD           RequiredPropertyKeyCount,
  [in]            DWORD            Flags
);

Parameters

[in] DeviceInfoSet

A handle to a device information set. This device information set contains the device instance for which this function retrieves an array of device property keys. The property keys represent the device properties that are set for the device instance.

[in] DeviceInfoData

A pointer to an SP_DEVINFO_DATA structure that represents the device instance for which to retrieve the requested array of device property keys.

[out, optional] PropertyKeyArray

A pointer to a buffer that receives an array of DEVPROPKEY-typed values, where each value is a device property key that represents a device property that is set for the device instance. The pointer is optional and can be NULL. For more information, see the Remarks section later in this topic.

[in] PropertyKeyCount

The size, in DEVPROPKEY-typed values, of the PropertyKeyArray buffer. If PropertyKeyArray is set to NULL, PropertyKeyCount must be set to zero.

[out, optional] RequiredPropertyKeyCount

A pointer to a DWORD-typed variable that receives the number of requested device property keys. The pointer is optional and can be set to NULL.

[in] Flags

This parameter must be set to zero.

Return value

SetupDiGetDevicePropertyKeys returns TRUE if it is successful. Otherwise, it returns FALSE, and the logged error can be retrieved by calling GetLastError.

The following table includes some of the more common error codes that this function might log.

Return code	Description
ERROR_INVALID_FLAGS	The value of Flags is not zero.
ERROR_INVALID_HANDLE	The device information set that is specified by DevInfoSet is not valid.
ERROR_INVALID_PARAMETER	A supplied parameter is not valid. One possibility is that the device information element is not valid.
ERROR_INVALID_DATA	An internal data value is not valid.
ERROR_INVALID_USER_BUFFER	A user buffer is not valid. One possibility is that PropertyKeyArray is NULL and PropertKeyCount is not zero.
ERROR_NO_SUCH_DEVINST	The device instance that is specified by DevInfoData does not exist.
ERROR_INSUFFICIENT_BUFFER	The PropertyKeyArray buffer is too small to hold all the requested property keys.
ERROR_NOT_ENOUGH_MEMORY	There was not enough system memory available to complete the operation.

Remarks

SetupDiGetDevicePropertyKeys is part of the unified device property model.

If the ProperKeyArray buffer is not large enough to hold all the requested property keys, SetupDiGetDevicePropertyKeys does not retrieve any property keys and returns ERROR_INSUFFICIENT_BUFFER. If the caller supplied a RequiredPropertyKeyCount pointer, SetupDiGetDevicePropertyKeys sets the value of *RequiredPropertyKeyCount to the required size, in DEVPROPKEY-typed values, of the PropertyKeyArray buffer.

To retrieve a device instance property, call SetupDiGetDeviceProperty, and to set a device instance property, call SetupDiSetDeviceProperty.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of Windows.
Target Platform	DesktopFor universal, call CM_Get_DevNode_Property_Keys
Header	setupapi.h (include Setupapi.h)
Library	Setupapi.lib
DLL	Setupapi.dll