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

Статья
03/01/2024

Функция setupDiCreateDevRegKey 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

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

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

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

Замечания

Вызывающий объект SetupDiCreateDevRegKey должен быть членом группы "Администраторы".

Закройте дескриптор, возвращенный из SetupDiCreateDevRegKey, вызвав RegCloseKey.

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

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

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

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

Заметка

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

Требования

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