Função WdfRegistryCreateKey (wdfregistry.h)

Artigo
02/27/2024

[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 do 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 do 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 for NULL, a chave especificada por KeyName 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 de tipo ACCESS_MASK 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 Abrindo um identificador para um objeto Registry-Key. Seu 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 WDF_OBJECT_ATTRIBUTES que contém atributos fornecidos pelo driver para o novo objeto registry-key. 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.

Retornar valor

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 Erros de criação de objeto de estrutura.

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

Comentários

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

Por padrão, o pai do novo objeto de chave do Registro é o objeto de driver de estrutura que o método WdfDriverCreate cria. Você pode usar o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES para especificar um pai diferente. A estrutura exclui o objeto registry-key quando exclui o objeto pai. Se o driver não alterar o pai padrão, o driver deverá excluir o objeto registry-key quando terminar de usar o objeto ; caso contrário, o objeto registry-key permanecerá até que o gerenciador 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 registry-key permanecerá até que o gerenciador de E/S descarregue o driver. Como alternativa, o driver pode chamar WdfObjectDelete para excluir o objeto registry-key.

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

Exemplos

O exemplo de código a seguir abre a chave de software de um driver e, em seguida, cria e abre a chave do registro myKeyStr , 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
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfregistry.h (include Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)