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

Статья
11/20/2024

Функция SetupDiGetCustomDeviceProperty извлекает указанное пользовательское свойство устройства из реестра.

Синтаксис

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCWSTR           CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

Параметры

[in] DeviceInfoSet

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

[in] DeviceInfoData

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

[in] CustomPropertyName

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

[in] Flags

Значение флага, указывающее, как должны быть возвращены запрошенные сведения. Флаг может быть нулевым или одним из следующих:

DICUSTOMDEVPROP_MERGE_MULTISZ

Если задано, функция извлекает значения свойств для конкретного экземпляра устройства и значения свойств для конкретного идентификатора оборудования, сцепленные как строку с REG_MULTI_SZ типами. (Дополнительные сведения см. в разделе примечания на этой справочной странице.)

[out, optional] PropertyRegDataType

Указатель на переменную типа DWORD, которая получает тип данных извлеченного свойства. Тип данных указывается как одна из REG_ префиксированных констант, представляющих типы данных реестра. Этот параметр является необязательным и может быть null.

[out] PropertyBuffer

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

[in] PropertyBufferSize

Размер в байтах буфера PropertyBuffer .

[out, optional] RequiredSize

Указатель на переменную типа DWORD, которая получает размер буфера в байтах, которая требуется для получения запрошенных сведений. Этот параметр является необязательным и может быть null. Если этот параметр указан, SetupDiGetCustomDeviceProperty возвращает требуемый размер независимо от того, достаточно ли размер буфера PropertyBuffer достаточно велик, чтобы получить запрошенные сведения.

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

Если операция выполнена успешно, SetupDiGetCustomDeviceProper ty возвращает TRUE. В противном случае функция возвращает FALSE и ошибку журнала можно получить с помощью вызова GetLastError. Если буфер PropertyBuffer недостаточно велик для получения запрошенной информации, SetupDiGetCustomDeviceProper ty возвращает FALSE и последующий вызов getLastError возвращает ERROR_INSUFFICIENT_BUFFER.

Замечания

SetupDiGetCustomDeviceProperty получает свойства устройства, связанные с одним экземпляром устройства или всеми устройствами, соответствующими определенному идентификатору оборудования. (Сведения об идентификаторах оборудования см. в строках идентификации устройств).

Поставщики могут задать свойства для экземпляра устройства с помощью директив INF AddReg INF AddReg в разделах INF DDInstall.HW и указав корневой каталог реестра HKR HKR.

Только система может задать свойства для аппаратных идентификаторов. Система предоставляет свойство Icon для некоторых аппаратных идентификаторов.

Функция сначала проверяет, существует ли указанное свойство для указанного экземпляра устройства. Если да, возвращается значение свойства. Если нет, функция проверяет, существует ли свойство для всех устройств, соответствующих идентификатору оборудования указанного экземпляра устройства. Если да, возвращается значение свойства. Если DICUSTOMDEVPROP_MERGE_MULTISZ задан в Flags, функция возвращает значения свойств, связанные как с экземпляром устройства, так и с идентификатором оборудования, если они существуют.

Заметка

Заголовок setupapi.h определяет SetupDiGetCustomDeviceProperty в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Windows XP и более поздних версиях Windows.
целевая платформа	Настольный
заголовка	setupapi.h (include Setupapi.h)
библиотеки	Setupapi.lib
DLL	Setupapi.dll