Função ZwOpenKeyTransactedEx (wdm.h)

Artigo
08/08/2023

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

Sintaxe

NTSYSAPI NTSTATUS ZwOpenKeyTransactedEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions,
  [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] OpenOptions

Especifica as opções a serem aplicadas ao abrir 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 OpenOptions	Descrição
REG_OPTION_OPEN_LINK	A chave é um link simbólico. Esse sinalizador não é usado por drivers intermediários e de dispositivo.
REG_OPTION_BACKUP_RESTORE	A chave deve ser 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.

[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

ZwOpenKeyTransactedEx 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_INVALID_PARAMETER_4	O valor do parâmetro OpenOptions 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.

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

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

A rotina ZwOpenKeyTransacted é semelhante a ZwOpenKeyTransactedEx , mas não aceita um parâmetro OpenOptions . O parâmetro OpenOptions de ZwOpenKeyTransactedEx permite que o chamador abra uma chave que seja um link simbólico ou abra uma chave para operações de backup e restauração. Uma chamada para ZwOpenKeyTransactedEx com o parâmetro OpenOptions definido como zero é equivalente a uma chamada para ZwOpenKeyTransacted.

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

ZwOpenKeyTransactedEx 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 7 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)