Função ZwCreateKey (wdm.h)
A rotina de
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 objetos:
O chamador também pode especificar uma das seguintes constantes, que combina vários sinalizadores de 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 de Disposição | Descrição |
|---|---|
| REG_CREATED_NEW_KEY | Uma nova chave foi criada. |
| REG_OPENED_EXISTING_KEY | Uma chave existente foi aberta. |
Valor de retorno
ZwCreateKey retorna STATUS_SUCCESS com êxito ou o código de erro NTSTATUS apropriado sobre falha.
Observações
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 pelo 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 ObjectName membro do objectAttributes de entrada. Os nomes de caminho das chaves do Registro começam com \Registry.
Como nome de caminho em relação a outra chave do Registro, representada pelo identificador no membro
RootDirectory da de entrada ObjectAttributes .
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
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 Object Handles.
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 está diretamente acessível aos drivers no modo kernel.
Para chamadas de drivers no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de 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 de serviços do sistema nativo.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino |
Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de 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) |
Consulte também
usando versões Nt e Zw das rotinas de serviços do sistema nativo