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

  • Статья

Функция 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
 Вызывающий объект не имеет прав администратора.

Комментарии

SetupDiGetDeviceProperty является частью единой модели свойств устройства.

SetupAPI поддерживает только версию в Юникоде SetupDiGetDeviceProperty.

Чтобы получить ключи свойств устройства, которые представляют свойства устройства, заданные для экземпляра устройства, вызовите SetupDiGetDevicePropertyKeys.

Чтобы задать свойство экземпляра устройства, вызовите SetupDiSetDeviceProperty.

Требования

Требование Значение
Минимальная версия клиента Доступно в 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