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

Статья
08/26/2023

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

Синтаксис

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

Параметры

[in] ClassGuid

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

[in] PropertyKey

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

[in] PropertyType

Значение типа DEVPROPTYPE, представляющее идентификатор property-data-type для свойства класса. Дополнительные сведения об идентификаторе property-data-type см. в разделе Примечания далее в этом разделе.

[in, optional] PropertyBuffer

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

[in] PropertyBufferSize

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

[in] Flags

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

DICLASSPROP_INSTALLER

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

DICLASSPROP_INTERFACE

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

[in, optional] MachineName

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

Внимание!

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

Reserved

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

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

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

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

Код возврата	Описание
ERROR_INVALID_FLAGS	Недопустимое значение Flags .
ERROR_INVALID_CLASS	Недопустимый класс настройки устройства, указанный в ClassGuid . Эта ошибка может возникать только в том случае, если указан флаг DICLASSPROP_INSTALLER.
ERROR_INVALID_REFERENCE_STRING	Недопустимая строка ссылки на интерфейс устройства. Эта ошибка может возникнуть только в том случае, если указан флаг DICLASSPROP_INTERFACE.
ERROR_INVALID_REG_PROPERTY	Ключ свойства, предоставленный PropertyKey , недопустим.
ERROR_INVALID_DATA	Неопределенное значение внутренних данных было недопустимым. Эта ошибка может быть зарегистрирована, если значение ClassGuid не является допустимым идентификатором GUID или значение свойства не соответствует типу свойства, заданному свойством PropertyType.
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, а чтобы получить свойство класса устройства на удаленном компьютере, вызовите метод SetupDiGetClassPropertyEx.

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

Требования

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