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

Статья
02/27/2024

[Применимо к KMDF и UMDF]

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

Синтаксис

NTSTATUS WdfRegistryOpenKey(
  [in, optional] WDFKEY                 ParentKey,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [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, optional] KeyAttributes

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

[out] Key

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

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

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

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

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

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

Чтобы получить дескриптор объекта раздела реестра, который представляет родительский ключ, драйвер может вызвать WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKey или WdfFdoInitOpenRegistryKey.

Формат строки, указанный в параметре KeyName , зависит от того, является ли вызывающий объект драйвером KMDF или драйвером UMDF. Например, чтобы открыть следующий путь:

HKLM\System\CurrentControlSet\Control

Драйвер может использовать эту условную логику:

#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\" 
#endif

После завершения работы драйвера с разделом реестра, который открывается с помощью WdfRegistryOpenKey, драйвер должен вызвать WdfRegistryClose.

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

Примеры

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

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"MySubKey"
                         );
    status = WdfRegistryOpenKey(
                                hKey,
                                &myKeyStr,
                                KEY_READ,
                                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)