Função ZwCreateKey (wdm.h)

Artigo
08/08/2023

A rotina ZwCreateKey cria uma nova chave do Registro ou abre uma existente.

Sintaxe

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Parâmetros

[out] KeyHandle

Ponteiro para uma variável HANDLE que recebe um identificador para a chave.

[in] DesiredAccess

Especifica um valor ACCESS_MASK que determina o acesso solicitado ao objeto . Além dos direitos de acesso definidos para todos os tipos de objetos (consulte ACCESS_MASK), o chamador pode especificar um ou mais dos seguintes direitos de acesso, que são específicos para diretórios de objeto:

Sinalizador DesiredAccess	Permite que o chamador faça isso
KEY_QUERY_VALUE	Ler valores de chave.
KEY_SET_VALUE	Gravar valores de chave.
KEY_CREATE_SUB_KEY	Crie subchaves para a chave.
KEY_ENUMERATE_SUB_KEYS	Leia as subchaves da chave.
KEY_CREATE_LINK	Crie um link simbólico para a chave. Esse sinalizador não é usado por drivers intermediários e de dispositivo.
KEY_NOTIFY	Peça para receber notificação quando o nome, o valor ou os atributos da chave forem alterados. Para obter mais informações, consulte ZwNotifyChangeKey.

O chamador também pode especificar uma das seguintes constantes, que combina vários sinalizadores ACCESS_MASK.

Constante	Consiste nesses sinalizadores de ACCESS_MASK
KEY_READ	STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS e KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE, KEY_SET_VALUE e KEY_CREATE_SUB_KEY
KEY_EXECUTE	O mesmo que KEY_READ.
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY e KEY_CREATE_LINK

[in] ObjectAttributes

Ponteiro para uma estrutura OBJECT_ATTRIBUTES que especifica o nome do objeto e outros atributos. Use InitializeObjectAttributes para inicializar essa estrutura. Se o chamador não estiver em execução em um contexto de thread do sistema, ele deverá definir o atributo OBJ_KERNEL_HANDLE quando chamar InitializeObjectAttributes.

TitleIndex

Os drivers intermediários e de dispositivo definem esse parâmetro como zero.

[in, optional] Class

Ponteiro para uma cadeia de caracteres Unicode que contém a classe de objeto da chave. Essas informações são usadas pelo gerenciador de configurações.

[in] CreateOptions

Especifica as opções a serem aplicadas ao criar ou abrir uma chave, especificadas como uma combinação compatível dos sinalizadores a seguir.

Sinalizador CreateOptions	Descrição
REG_OPTION_VOLATILE	A chave não é preservada quando o sistema é reinicializado.
REG_OPTION_NON_VOLATILE	A chave é preservada quando o sistema é reinicializado.
REG_OPTION_CREATE_LINK	A chave recém-criada é um link simbólico. Esse sinalizador não é usado por drivers intermediários e de dispositivo.
REG_OPTION_BACKUP_RESTORE	A chave deve ser criada ou aberta com privilégios especiais que permitem operações de backup e restauração. Esse sinalizador não é usado por drivers intermediários e de dispositivo.

[out, optional] Disposition

Ponteiro para uma variável que recebe um valor que indica se uma nova chave foi criada ou uma existente aberta.

Valor de disposição	Descrição
REG_CREATED_NEW_KEY	Uma nova chave foi criada.
REG_OPENED_EXISTING_KEY	Uma chave existente foi aberta.

Retornar valor

ZwCreateKey retorna STATUS_SUCCESS com êxito ou o código de erro NTSTATUS apropriado em caso de falha.

Comentários

ZwCreateKey fornece um identificador que o chamador pode usar para manipular uma chave do Registro. Para obter mais informações, consulte Usando o Registro em um Driver.

Depois que o identificador apontado por KeyHandle não estiver mais em uso, o driver deverá chamar ZwClose para fechá-lo.

Há duas maneiras alternativas de especificar o nome do arquivo a ser criado ou aberto com ZwCreateKey:

Como um nome de caminho totalmente qualificado, fornecido no membro ObjectName da entrada ObjectAttributes. Os nomes de caminho das chaves do Registro começam com \Registry.
Como pathname relativo a outra chave do Registro, representada pelo identificador no membro RootDirectory do ObjectAttributes de entrada.

Se a chave especificada por ObjectAttributes não existir, a rotina tentará criar a chave. Para que essa tentativa seja bem-sucedida, a nova chave deve ser uma subchave direta da chave que é referenciada por RootDirectory e a chave à qual RootDirectory se refere deve ter sido aberta para acesso KEY_CREATE_SUB_KEY.

Se a chave especificada já existir, ela será aberta e seu valor não será afetado de forma alguma.

Os atributos de segurança especificados por ObjectAttributes quando uma chave é criada determinam se o DesiredAccess especificado é concedido em chamadas subsequentes para ZwCreateKey e ZwOpenKey.

Se o chamador não estiver em execução em um contexto de thread do sistema, ele deverá garantir que todos os identificadores que ele cria sejam identificadores privados. Caso contrário, o identificador pode ser acessado pelo processo em cujo contexto o driver está em execução. Para obter mais informações, consulte Identificadores de objeto.

Para obter mais informações sobre como trabalhar com chaves do Registro, consulte Usando o Registro em um Driver.

Se a chamada para essa função ocorrer no modo de usuário, você deverá usar o nome "NtCreateKey" em vez de "ZwCreateKey".

A rotina NtCreateKey no kernel do Windows não é diretamente acessível para drivers no modo kernel.

Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)