Função ZwOpenKeyTransacted (wdm.h)

Artigo
08/08/2023

A rotina ZwOpenKeyTransacted abre uma chave do Registro existente e associa a chave a uma transação.

Sintaxe

NTSYSAPI NTSTATUS ZwOpenKeyTransacted(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  HANDLE             TransactionHandle
);

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.

[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.

Retornar valor

ZwOpenKeyTransacted retornará STATUS_SUCCESS se a chamada abrir com êxito a chave. 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.
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.

Se a chave especificada não existir no registro, ZwOpenKeyTransacted retornará um erro status valor e não fornecerá um identificador de chave. Ao contrário da rotina ZwCreateKeyTransacted , a rotina ZwOpenKeyTransacted não criará a chave especificada se a chave não existir. ZwCreateKeyTransacted e ZwOpenKeyTransacted associam uma chave do Registro a uma transação.

A rotina ZwOpenKey é semelhante a ZwOpenKeyTransacted, mas não associa uma chave a uma transação.

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 uma ou mais chaves à 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.

ZwOpenKeyTransacted ignora as informações de segurança na estrutura para a qual o parâmetro ObjectAttributes aponta.

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 sistema operacional 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)