Поделиться через


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

[Относится к 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.

Комментарии

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

По умолчанию родительским объектом нового объекта реестра является объект драйвера платформы, создаваемый методом 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)

См. также раздел

ACCESS_MASK

RtlInitUnicodeString

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfDeviceOpenRegistryKey

WdfDriverCreate

WdfDriverOpenParametersRegistryKey

WdfFdoInitOpenRegistryKey

WdfRegistryOpenKey

ZwCreateKey