Функция WdfRegistryCreateKey (wdfregistry.h)

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfRegistryCreateKey создает и открывает указанный раздел реестра или просто открывает раздел, если он уже существует, и создает объект раздела реестра платформы, представляющий раздел реестра.

Синтаксис

NTSTATUS WdfRegistryCreateKey(
  [in, optional]  WDFKEY                 ParentKey,
  [in]            PCUNICODE_STRING       KeyName,
  [in]            ACCESS_MASK            DesiredAccess,
  [in]            ULONG                  CreateOptions,
  [out, optional] PULONG                 CreateDisposition,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]           WDFKEY                 *Key
);

Параметры

[in, optional] ParentKey

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

[in] KeyName

Указатель на структуру UNICODE_STRING , содержащую имя открываемого ключа. Имя ключа может содержать сведения о пути. Если parentKey имеет значение NULL, keyName должен указать полный путь к разделу реестра.

[in] DesiredAccess

Значение типа ACCESS_MASK, указывающее права доступа, запрашиваемые драйвером для указанного раздела реестра. Список прав доступа, которые драйверы обычно используют для разделов реестра, см. в разделе Открытие дескриптора для объекта Registry-Key. Драйвер должен запрашивать только те типы доступа, которые ему нужны. Например, драйвер не должен запрашивать KEY_ALL_ACCESS, если он будет читать только раздел реестра.

[in] CreateOptions

Один или несколько флагов. Сведения об этих флагах см. в параметре CreateOptions или ZwCreateKey.

[out, optional] CreateDisposition

Указатель на расположение, которое получает REG_CREATED_NEW_KEY при создании нового ключа или REG_OPENED_EXISTING_KEY, если открыт существующий ключ. Эти значения определены в Wdm.h. Этот указатель является необязательным и может иметь значение NULL.

[in, optional] KeyAttributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES , содержащую предоставленные драйвером атрибуты для нового объекта раздела реестра. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[out] Key

Указатель на расположение, которое получает дескриптор нового объекта раздела реестра.

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

WdfRegistryCreateKey возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае метод может вернуть одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryCreateKey не был вызван в IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Указан недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Не удалось выделить объект раздела реестра.
STATUS_ACCESS_DENIED	Система отклонила указанные права доступа.
STATUS_OBJECT_NAME_NOT_FOUND	Указанный раздел реестра не существует.

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

Этот метод также может возвращать другие значения NTSTATUS.

По умолчанию родительским объектом нового объекта реестра является объект драйвера платформы, создаваемый методом WdfDriverCreate . Для указания другого родительского элемента можно использовать элемент ParentObjectструктуры WDF_OBJECT_ATTRIBUTES . Платформа удаляет объект раздела реестра при удалении родительского объекта. Если драйвер не изменяет родительский объект по умолчанию, драйвер должен удалить объект раздела реестра после завершения работы с объектом . В противном случае объект раздела реестра будет оставаться до тех пор, пока диспетчер ввода-вывода не выгрузит драйвер.

Если драйвер не изменяет родительский объект по умолчанию, драйвер должен вызвать WdfRegistryClose после завершения использования объекта . В противном случае объект раздела реестра будет оставаться до тех пор, пока диспетчер ввода-вывода не выгрузит драйвер. Кроме того, драйвер может вызвать WdfObjectDelete , чтобы удалить объект раздела реестра.

Дополнительные сведения об объектах раздела реестра см. в статье Использование реестра в Framework-Based Drivers.

Примеры

В следующем примере кода открывается программный ключ драйвера, а затем создается и открывается раздел реестра myKeyStr , который находится под программным ключом драйвера.

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING  myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"myKeyStr"
                         );
    status = WdfRegistryCreateKey(
                                  hKey,
                                  &myKeyStr,
                                  KEY_READ,
                                  REG_OPTION_NON_VOLATILE,
                                  NULL,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &subkey
                                  );
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfregistry.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)