Функция SetupDiGetDevicePropertyW (setupapi.h)

Статья
08/26/2023

Функция SetupDiGetDeviceProperty извлекает свойство экземпляра устройства.

Синтаксис

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
);

Параметры

[in] DeviceInfoSet

Дескриптор набора сведений об устройстве , содержащего экземпляр устройства, для которого требуется получить свойство экземпляра устройства.

[in] DeviceInfoData

Указатель на структуру SP_DEVINFO_DATA , представляющую экземпляр устройства, для которого требуется получить свойство экземпляра устройства.

[in] PropertyKey

Указатель на структуру DEVPROPKEY , представляющую ключ свойства устройства запрошенного свойства экземпляра устройства.

[out] PropertyType

Указатель на переменную типа DEVPROPTYPE, которая получает идентификатор типа property-data-type запрошенного свойства экземпляра устройства, где идентификатор property-data-type представляет собой побитовое ЗНАЧЕНИЕ OR между идентификатором типа базовых данных и модификатором property-data-type( при изменении типа base-data).

[out, optional] PropertyBuffer

Указатель на буфер, получающий свойство запрошенного экземпляра устройства. SetupDiGetDeviceProperty извлекает запрошенное свойство, только если буфер достаточно велик для хранения всех данных значения свойства. Указатель может иметь значение NULL. Если для указателя задано значение NULL и указан параметр RequiredSize , setupDiGetDeviceProperty возвращает размер свойства в байтах в *RequiredSize.

[in] PropertyBufferSize

Размер буфера PropertyBuffer (в байтах). Если свойство PropertyBuffer имеет значение NULL, свойство PropertyBufferSize должно быть равно нулю.

[out, optional] RequiredSize

Указатель на переменную типа DWORD, которая получает размер (в байтах) свойства экземпляра устройства при извлечении свойства или требуемый размер буфера, если буфер недостаточно велик. Для этого указателя можно задать значение NULL.

[in] Flags

Этот параметр должен иметь нулевое значение.

Возвращаемое значение

SetupDiGetDeviceProperty возвращает значение TRUE в случае успешного выполнения. В противном случае возвращается значение FALSE, а зарегистрированную ошибку можно получить, вызвав Метод GetLastError.

В следующей таблице приведены некоторые из наиболее распространенных кодов ошибок, которые эта функция может записывать в журнал.

Код возврата	Описание
ERROR_INVALID_FLAGS	Значение Flags не равно нулю.
ERROR_INVALID_HANDLE	Недопустимый набор сведений об устройстве, указанный в DevInfoSet .
ERROR_INVALID_PARAMETER	Указанный параметр недопустим. Одна из возможных ситуаций заключается в том, что элемент сведений об устройстве недопустим.
ERROR_INVALID_REG_PROPERTY	Недопустимый ключ свойства, предоставляемый PropertyKey .
ERROR_INVALID_DATA	Неуказаемое внутреннее значение данных было недопустимым.
ERROR_INVALID_USER_BUFFER	Недопустимый буфер пользователя. Возможно, свойство PropertyBuffer имеет значение NULL , а PropertBufferSize не равно нулю.
ERROR_NO_SUCH_DEVINST	Экземпляр устройства, указанный в DevInfoData , не существует.
ERROR_INSUFFICIENT_BUFFER	Буфер PropertyBuffer слишком мал, чтобы вместить запрошенное значение свойства, или внутренний буфер данных, переданный в системный вызов, слишком мал.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно системной памяти для завершения операции.
ERROR_NOT_FOUND	Запрошенное свойство устройства не существует.
ERROR_ACCESS_DENIED	Вызывающий объект не имеет прав администратора.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows Vista и более поздних версиях Windows.
Целевая платформа	DesktopДля универсального вызова CM_Get_DevNode_Property
Верхняя часть	setupapi.h (включая SetupAPI.h)
Библиотека	SetupAPI.lib
DLL	SetupAPI.dll
Набор API	ext-ms-win-setupapi-classinstallers-l1-1-0 (появилось в Windows 8)

См. также раздел

SetupDiGetDevicePropertyKeys

SetupDiSetDeviceProperty

Share via