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

Статья
03/01/2024

Функция SetupDiCreateDevRegKey создает раздел реестра для сведений о конфигурации устройства и возвращает дескриптор для ключа.

Синтаксис

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

Параметры

[in] DeviceInfoSet

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

[in] DeviceInfoData

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

[in] Scope

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

DICS_FLAG_GLOBAL

Создайте ключ для хранения сведений о глобальной конфигурации. Эти сведения не относятся к конкретному профилю оборудования. В операционных системах на основе NT создается ключ, который коренится в HKEY_LOCAL_MACHINE. Точный открытый ключ зависит от значения параметра KeyType .

DICS_FLAG_CONFIGSPECIFIC

Создайте ключ для хранения сведений о конфигурации для конкретного профиля оборудования. Этот ключ коренится в одной из ветвей аппаратного профиля, а не в HKEY_LOCAL_MACHINE.

[in] HwProfile

Профиль оборудования, для которого создается ключ, если для HwProfileFlags задано значение SPDICS_FLAG_CONFIGSPECIFIC. Если HwProfile имеет значение 0, создается ключ для текущего профиля оборудования. Если HwProfileFlags SPDICS_FLAG_GLOBAL, HwProfile игнорируется.

[in] KeyType

Тип создаваемого раздела хранилища реестра. Может иметь одно из следующих значений:

DIREG_DEV

Создайте аппаратный ключ для устройства.

DIREG_DRV

Создайте программный ключ для устройства.

[in, optional] InfHandle

Дескриптор открытого INF-файла, содержащего раздел INF DDInstall , который должен быть выполнен для только что созданного ключа. Этот параметр является необязательным и может иметь значение NULL. Если указан этот параметр, необходимо также указать InfSectionName .

[in, optional] InfSectionName

Имя раздела INF DDInstall в INF-файле, указанном в InfHandle. Этот раздел выполняется для только что созданного ключа. Этот параметр является необязательным и может иметь значение NULL. Если указан этот параметр, необходимо также указать InfHandle .

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

Если setupDiCreateDevRegKey завершается успешно, функция возвращает дескриптор указанного раздела реестра, в котором можно хранить и извлекать данные конфигурации для конкретного устройства. Если SetupDiCreateDevRegKey завершается сбоем, функция возвращает INVALID_HANDLE_VALUE. Вызовите Метод GetLastError , чтобы получить расширенные сведения об ошибке.

Если указанный ключ уже существует, SetupDiCreateDevRegKey возвращает дескриптор этого ключа. В противном случае SetupDiCreateDevRegKey создает указанный ключ и возвращает дескриптор новому ключу. Для Windows Server 2003 и более поздних версий Windows дескриптор ключа имеет только KEY_READ и KEY_WRITE доступ. В предыдущих версиях Windows этот дескриптор имеет KEY_ALL_ACCESS доступ.

Указанный экземпляр устройства должен быть зарегистрирован перед вызовом SetupDiCreateDevRegKey . Однако обратите внимание, что операционная система автоматически регистрирует экземпляры устройств PnP. Сведения о регистрации экземпляров устройств, отличных от PnP, см. в разделе SetupDiRegisterDeviceInfo.

Для установок, использующих файлы макета (указанные в записи LayoutFile в разделе Версия INF), файл макета должен быть открыт вызовом SetupOpenAppendInfFile (описан в документации по Microsoft Windows SDK) перед вызовом SetupDiCreateDevRegKey.

Если предоставленный набор сведений об устройстве содержит элементы сведений об устройстве для удаленной системы, а также указаны InfHandle и InfSectionName , запрос на создание завершится ошибкой, а последующий вызов GetLastError вернет ERROR_REMOTE_REQUEST_UNSUPPORTED.

Примечание

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

Требования

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