Função WdfRegistryCreateKey (wdfregistry.h)

Artigo
03/22/2025

[Aplica-se a KMDF e UMDF]

O método WdfRegistryCreateKey cria e abre uma chave do Registro especificada ou apenas abre a chave se ela já existir e cria um objeto de chave de registro da estrutura que representa a chave do Registro.

Sintaxe

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
);

Parâmetros

[in, optional] ParentKey

Um identificador para um objeto de chave de registro da estrutura. Esse objeto representa uma chave do Registro pai que o driver abriu. Esse parâmetro é opcional e pode ser NULL. Se o parâmetro não estiver NULL, a chave que KeyName especificar deverá residir sob essa chave pai no Registro. Para obter mais informações sobre essa chave pai, consulte a seção Comentários.

[in] KeyName

Um ponteiro para uma estrutura UNICODE_STRING que contém o nome da chave a ser aberta. O nome da chave pode incluir informações de caminho. Se ParentKey for NULL, KeyName deverá especificar um caminho completo para uma chave do Registro.

[in] DesiredAccess

Um valor ACCESS_MASKdigitado que especifica os direitos de acesso que o driver está solicitando para a chave do Registro especificada. Para obter uma lista de direitos de acesso que os drivers normalmente usam para chaves do Registro, consulte Abrir um identificador para um objeto Registry-Key. O driver deve solicitar apenas os tipos de acesso necessários. Por exemplo, o driver não deve solicitar KEY_ALL_ACCESS se ele lerá apenas a chave do Registro.

[in] CreateOptions

Um ou mais sinalizadores. Para obter informações sobre esses sinalizadores, consulte o parâmetro CreateOptions ou ZwCreateKey .

[out, optional] CreateDisposition

Um ponteiro para um local que recebe REG_CREATED_NEW_KEY se uma nova chave for criada ou REG_OPENED_EXISTING_KEY se uma chave existente for aberta. Esses valores são definidos em Wdm.h. Esse ponteiro é opcional e pode ser NULL.

[in, optional] KeyAttributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES que contém atributos fornecidos pelo driver para o novo objeto de chave do Registro. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] Key

Um ponteiro para um local que recebe um identificador para o novo objeto de chave do Registro.

Valor de retorno

WdfRegistryCreateKey retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryCreateKey não foi chamado em IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar um objeto de chave do Registro.
STATUS_ACCESS_DENIED	O sistema negou os direitos de acesso especificados.
STATUS_OBJECT_NAME_NOT_FOUND	A chave do Registro especificada não existe.

Para obter uma lista de outros valores retornados que o método WdfRegistryCreateKey pode retornar, consulte Framework Object Creation Errors.

Esse método também pode retornar outros valores NTSTATUS .

Observações

Para obter um identificador para um objeto de chave do Registro que representa uma chave pai, seu driver pode chamar WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKeyou WdfFdoInitOpenRegistryKey.

Por padrão, o pai do novo objeto de chave do Registro é o objeto de driver da estrutura que o método WdfDriverCreate cria. Você pode usar o ParentObject membro da estrutura WDF_OBJECT_ATTRIBUTES para especificar um pai diferente. A estrutura exclui o objeto de chave do Registro quando exclui o objeto pai. Se o driver não alterar o pai padrão, o driver deverá excluir o objeto de chave do Registro quando terminar de usar o objeto; caso contrário, o objeto de chave do Registro permanecerá até que o gerente de E/S descarregue o driver.

Se o driver não alterar o pai padrão, o driver deverá chamar WdfRegistryClose quando terminar de usar o objeto; caso contrário, o objeto de chave do Registro permanecerá até que o gerente de E/S descarregue o driver. Como alternativa, o driver pode chamar WdfObjectDelete para excluir o objeto de chave do Registro.

Para obter mais informações sobre objetos de chave do Registro, consulte Usando o Registro em Framework-Based Drivers.

Exemplos

O exemplo de código a seguir abre a chave de software de um driver e, em seguida, cria e abre o myKeyStr chave do Registro, que está localizada sob a chave de software do driver.

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
                                  );
}

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
versão mínima do UMDF	2.0
cabeçalho	wdfregistry.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)