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

Статья
08/26/2023

Функция SetupDiGetClassPropertyKeysEx извлекает массив ключей свойств устройства, представляющих свойства устройства, заданные для класса установки устройства или класса интерфейса устройства на локальном или удаленном компьютере.

Синтаксис

WINSETUPAPI BOOL SetupDiGetClassPropertyKeysExW(
  [in]            const GUID *ClassGuid,
  [out, optional] DEVPROPKEY *PropertyKeyArray,
  [in]            DWORD      PropertyKeyCount,
  [out, optional] PDWORD     RequiredPropertyKeyCount,
  [in]            DWORD      Flags,
  [in, optional]  PCWSTR     MachineName,
                  PVOID      Reserved
);

Параметры

[in] ClassGuid

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

[out, optional] PropertyKeyArray

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

[in] PropertyKeyCount

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

[out, optional] RequiredPropertyKeyCount

Указатель на переменную типа DWORD, которая получает количество запрошенных ключей свойств. Указатель является необязательным и может иметь значение NULL.

[in] Flags

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

DICLASSPROP_INSTALLER

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

DICLASSPROP_INTERFACE

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

[in, optional] MachineName

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

Внимание!

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

Reserved

Для этого параметра необходимо задать значение NULL.

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

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

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

Код возврата	Описание
ERROR_INVALID_FLAGS	Недопустимое значение Flags .
ERROR_INVALID_CLASS	Если указан флаг DICLASSPROP_INSTALLER, этот код ошибки указывает на то, что класс установки устройства, указанный в ClassGuid , не существует.
ERROR_INVALID_REFERENCE_STRING	Недопустимая строка для интерфейса устройства, указанного классом ClassGuild . Эта ошибка может быть возвращена при указании флага DICLASSPROP_INTERFACE.
ERROR_INVALID_DATA	Недопустимое значение данных. Одна из возможных вариантов заключается в том, что значение ClassGuid недопустимо.
ERROR_INVALID_PARAMETER	Неуказаемый параметр недопустим.
ERROR_INVALID_USER_BUFFER	Недопустимый буфер пользователя. Одна из возможных вариантов заключается в том, что PropertyKeyArray имеет значение NULL, а PropertKeyCount не равно нулю.
ERROR_INVALID_MACHINENAME	Недопустимое имя компьютера, указанное в параметре MachineName .
ERROR_NO_SUCH_INTERFACE_CLASS	Если указан флаг DICLASSPROP_INTERFACE, этот код ошибки указывает на то, что класс интерфейса устройства, указанный в ClassGuid , не существует.
ERROR_INSUFFICENT_BUFFER	Буфер PropertyKeyArray недостаточно велик, чтобы вместить все ключи свойств, или внутренний буфер данных, переданный в системный вызов, был слишком мал.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно системной памяти для завершения операции.
ERROR_ACCESS_DENIED	Вызывающий объект не имеет прав администратора.

Если буфер PropertyKeyArray недостаточно велик для хранения всех запрошенных ключей свойств, SetupDiGetClassPropertyKeysEx не получает ключи свойств и возвращает ERROR_INSUFFICIENT_BUFFER. Если вызывающий объект предоставил указатель RequiredPropertyKeyCount, SetupDiGetClassPropertyKeysEx устанавливает значение *RequiredPropertyKeyCount в значениях типа DEVPROPKEY буфера PropertyKeyArray.

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

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

Требования

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

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

SetupDiGetClassPropertyEx

SetupDiGetClassPropertyKeys

SetupDiSetClassPropertyEx

Поделиться через