Função ZwCreateKeyTransacted (wdm.h)

Artigo
08/08/2023

A rotina ZwCreateKeyTransacted cria uma nova chave do Registro ou abre uma existente e associa a chave a uma transação.

Sintaxe

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

Parâmetros

[out] KeyHandle

Um ponteiro para uma variável HANDLE na qual a rotina grava o identificador na chave.

[in] DesiredAccess

Especifica o tipo de acesso à chave que o chamador solicita. Esse parâmetro é um valor ACCESS_MASK . Para obter mais informações, consulte a descrição do parâmetro DesiredAccess da rotina ZwCreateKey .

[in] ObjectAttributes

Um ponteiro para os atributos de objeto da chave que está sendo aberta. Esse parâmetro aponta para uma estrutura OBJECT_ATTRIBUTES que deve ter sido inicializada anteriormente pela rotina InitializeObjectAttributes . O chamador deve especificar o nome da chave do Registro como o parâmetro ObjectName na chamada para InitializeObjectAttributes. 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

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

[in] CreateOptions

Especifica as opções a serem aplicadas quando a rotina cria ou abre a chave. Defina esse parâmetro como zero ou como OR bit a bit de um ou mais dos bits de sinalizador REG_OPTION_XXX a seguir.

Sinalizador CreateOptions	Descrição
REG_OPTION_VOLATILE	A chave não é preservada após a reinicialização do computador.
REG_OPTION_NON_VOLATILE	A chave é preservada após a reinicialização do computador.
REG_OPTION_CREATE_LINK	A chave é um link simbólico. Esse sinalizador não é usado por drivers intermediários e de dispositivo.
REG_OPTION_BACKUP_RESTORE	Abra a chave com privilégios especiais que habilitam operações de backup e restauração. Esse sinalizador não é usado por drivers intermediários e de dispositivo.

[in] TransactionHandle

Um identificador para um objeto de transação. Para obter esse identificador, você pode chamar a rotina ZwCreateTransaction . Ou, se você tiver um ponteiro para um objeto de transação, poderá fornecer o ponteiro para a rotina ObOpenObjectByPointer para obter o identificador de transação correspondente.

[out, optional] Disposition

Um ponteiro para um local no qual a rotina grava um dos valores a seguir para indicar se a chamada criou uma nova chave ou abriu uma existente.

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

Você poderá definir Disposição = NULL se essas informações não forem necessárias.

Retornar valor

ZwCreateKeyTransacted retornará STATUS_SUCCESS se a chamada criar ou abrir a chave com êxito. Os possíveis valores retornados por erro incluem o seguinte:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O parâmetro ObjectAttributes é NULL ou aponta para informações inválidas ou o valor do parâmetro CreateOptions especifica opções inválidas.
STATUS_OBJECT_PATH_SYNTAX_BAD	O caminho do Registro nos atributos de objeto é inválido.
STATUS_OBJECT_NAME_NOT_FOUND	O caminho do Registro nos atributos de objeto não foi encontrado.
STATUS_ACCESS_DENIED	O chamador não tinha os direitos de acesso necessários para abrir um identificador para a chave do Registro nomeada.
STATUS_INSUFFICIENT_RESOURCES	Falha em uma operação de alocação de memória.

Comentários

Essa rotina fornece um identificador com o qual o chamador pode acessar uma chave do Registro. Além disso, essa rotina associa a chave a uma transação ativa.

Depois que o identificador apontado por KeyHandle não estiver mais sendo usado, o driver deverá chamar a rotina ZwClose para fechá-la.

Como ZwCreateKeyTransacted, a rotina ZwOpenKeyTransacted associa uma chave a uma transação. Ao contrário de ZwCreateKeyTransacted, que pode criar uma nova chave ou abrir uma chave existente, ZwOpenKeyTransacted só pode abrir uma chave do Registro que já existe.

Depois que um driver de modo kernel obtém um identificador para uma transação (por exemplo, chamando ZwCreateTransaction), o driver pode executar uma série de operações do Registro que fazem parte dessa transação. O driver pode fechar a transação confirmando as alterações feitas na transação ou revertendo a transação.

Depois que o driver concluir com êxito todas as operações do Registro que fazem parte de uma transação, ele poderá chamar a rotina ZwCommitTransaction para confirmar as alterações. O driver pode chamar a rotina ZwRollbackTransaction para reverter a transação.

Durante uma transação, uma operação do Registro fará parte da transação se a chamada do sistema que executa a operação atender a uma das seguintes condições:

A chamada especifica, como um parâmetro de entrada, o identificador de transação. Por exemplo, chamadas para ZwCreateKeyTransacted e ZwOpenKeyTransacted podem associar um ou mais identificadores a chaves do Registro com a transação.
A chamada especifica, como um parâmetro de entrada, um identificador de chave do Registro que foi obtido por uma chamada para ZwCreateKeyTransacted ou ZwOpenKeyTransacted para o qual o identificador de transação foi fornecido. Por exemplo, uma chamada para a rotina ZwSetValueKey pode usar um identificador de chave que foi obtido dessa forma para definir o valor de uma chave do Registro como parte de uma transação.

Para obter mais informações sobre transações no modo kernel, consulte Usando o Gerenciador de Transações do Kernel.

O descritor de segurança nos atributos de objeto determina se os direitos de acesso especificados pelo parâmetro DesiredAccess são concedidos em chamadas posteriores a rotinas, como ZwOpenKeyTransacted que acessam a chave ou a rotinas, como ZwCreateKeyTransacted, que criam subchaves da chave.

Se o chamador do modo kernel 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 de kernel. 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 no modo kernel, consulte Usando o Registro em um Driver.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows Vista e versões posteriores do Windows.
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 da DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)