SetupDiGetDevicePropertyW function (setupapi.h)

Article
10/13/2021

The SetupDiGetDeviceProperty function retrieves a device instance property.

Syntax

WINSETUPAPI BOOL SetupDiGetDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags
);

Parameters

[in] DeviceInfoSet

A handle to a device information set that contains a device instance for which to retrieve a device instance property.

[in] DeviceInfoData

A pointer to the SP_DEVINFO_DATA structure that represents the device instance for which to retrieve a device instance property.

[in] PropertyKey

A pointer to a DEVPROPKEY structure that represents the device property key of the requested device instance property.

[out] PropertyType

A pointer to a DEVPROPTYPE-typed variable that receives the property-data-type identifier of the requested device instance property, where the property-data-type identifier is the bitwise OR between a base-data-type identifier and, if the base-data type is modified, a property-data-type modifier.

[out, optional] PropertyBuffer

A pointer to a buffer that receives the requested device instance property. SetupDiGetDeviceProperty retrieves the requested property only if the buffer is large enough to hold all the property value data. The pointer can be NULL. If the pointer is set to NULL and RequiredSize is supplied, SetupDiGetDeviceProperty returns the size of the property, in bytes, in *RequiredSize.

[in] PropertyBufferSize

The size, in bytes, of the PropertyBuffer buffer. If PropertyBuffer is set to NULL, PropertyBufferSize must be set to zero.

[out, optional] RequiredSize

A pointer to a DWORD-typed variable that receives the size, in bytes, of either the device instance property if the property is retrieved or the required buffer size if the buffer is not large enough. This pointer can be set to NULL.

[in] Flags

This parameter must be set to zero.

Return value

SetupDiGetDeviceProperty 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_REG_PROPERTY	The property key that is supplied by PropertyKey is not valid.
ERROR_INVALID_DATA	An unspecified internal data value was not valid.
ERROR_INVALID_USER_BUFFER	A user buffer is not valid. One possibility is that PropertyBuffer is NULL and PropertBufferSize is not zero.
ERROR_NO_SUCH_DEVINST	The device instance that is specified by DevInfoData does not exist.
ERROR_INSUFFICIENT_BUFFER	The PropertyBuffer buffer is too small to hold the requested property value, or an internal data buffer that was passed to a system call was too small.
ERROR_NOT_ENOUGH_MEMORY	There was not enough system memory available to complete the operation.
ERROR_NOT_FOUND	The requested device property does not exist.
ERROR_ACCESS_DENIED	The caller does not have Administrator privileges.

Remarks

SetupDiGetDeviceProperty is part of the unified device property model.

SetupAPI supports only a Unicode version of SetupDiGetDeviceProperty.

To obtain the device property keys that represent the device properties that are set for a device instance, call SetupDiGetDevicePropertyKeys.

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
Header	setupapi.h (include SetupAPI.h)
Library	SetupAPI.lib
DLL	SetupAPI.dll
API set	ext-ms-win-setupapi-classinstallers-l1-1-0 (introduced in Windows 8)