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

Статья
03/15/2023

Функция SetupDiGetClassPropertyEx извлекает свойство класса для класса установки устройства или класса интерфейса устройства на локальном или удаленном компьютере.

Синтаксис

WINSETUPAPI BOOL SetupDiGetClassPropertyExW(
  [in]            const GUID       *ClassGuid,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags,
  [in, optional]  PCWSTR           MachineName,
                  PVOID            Reserved
);

Параметры

[in] ClassGuid

Указатель на GUID, идентифицирующий класс настройки устройства или класс интерфейса устройства, для которого извлекается свойство устройства для класса устройства. Сведения об указании типа класса см. в параметре Flags .

[in] PropertyKey

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

[out] PropertyType

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

[out, optional] PropertyBuffer

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

[in] PropertyBufferSize

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

[out, optional] RequiredSize

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

[in] Flags

Одно из следующих значений, которое указывает, является ли класс классом настройки устройства или классом интерфейса устройства:

DICLASSPROP_INSTALLER

ClassGuid указывает класс настройки устройства. Этот флаг нельзя использовать с DICLASSPROP_INTERFACE.

DICLASSPROP_INTERFACE

ClassGuid указывает класс интерфейса устройства. Этот флаг нельзя использовать с DICLASSPROP_INSTALLER.

[in, optional] MachineName

Указатель на строку, завершающуюся значением NULL, которая содержит UNC-имя компьютера, включая префикс "\". Для указателя можно задать значение NULL. Если machineName имеет значение NULL, SetupDiGetClassPropertyEx извлекает запрошенное свойство класса устройства с локального компьютера.

Внимание!

Использование этой функции для доступа к удаленным компьютерам не поддерживается, начиная с Windows 8 и Windows Server 2012, так как эта функция была удалена.

Reserved

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

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

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

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

Код возврата	Описание
ERROR_INVALID_FLAGS	Значение Flags не равно нулю.
ERROR_INVALID_CLASS	Недопустимый класс настройки устройства, указанный в ClassGuid . Эта ошибка может возникать только в том случае, если указан флаг DICLASSPROP_INSTALLER.
ERROR_INVALID_PARAMETER	Недопустимый неуказаемый параметр.
ERROR_INVALID_REG_PROPERTY	Ключ свойства, предоставленный PropertyKey , недопустим.
ERROR_INVALID_REFERENCE_STRING	Недопустимая строка ссылки на интерфейс устройства. Эта ошибка может быть возвращена, если указан флаг DICLASSPROP_INTERFACE.
ERROR_INVALID_DATA	Неопределенное значение внутренних данных было недопустимым.
ERROR_INVALID_USER_BUFFER	Недопустимый буфер пользователя. Один из возможных вариантов заключается в том, что СвойствоBuffer имеет значение NULL, а PropertyBufferSize не равно нулю.
ERROR_INVALID_MACHINENAME	Недопустимое имя компьютера, указанное в параметре MachineName .
ERROR_NO_SUCH_INTERFACE_CLASS	Класс интерфейса устройства, указанный в ClassGuid , не существует. Эта ошибка может возникнуть только в том случае, если указан флаг DICLASSPROP_INTERFACE.
ERROR_INSUFFICIENT_BUFFER	Внутренний буфер данных, переданный в системный вызов, был слишком мал.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно системной памяти для завершения операции.
ERROR_NOT_FOUND	Запрошенное свойство устройства не существует.
ERROR_ACCESS_DENIED	Вызывающий объект не имеет прав администратора.

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

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

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

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows Vista и более поздних версиях Windows.
Целевая платформа	DesktopДля универсального, вызовите CM_Get_Class_Property_ExW
Верхняя часть	setupapi.h (включая Setupapi.h)
Библиотека	Setupapi.lib