Função ZwOpenKeyEx (wdm.h)

A rotina ZwOpenKeyEx abre uma chave do Registro existente.

Sintaxe

NTSYSAPI NTSTATUS ZwOpenKeyEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions
);

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 seguintes bits de sinalizador REG_OPTION_XXX :

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.

Retornar valor

ZwOpenKeyEx retornará STATUS_SUCCESS se a chamada for bem-sucedida na abertura da chave. Os possíveis valores retornados por erro incluem o seguinte:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER_4	O 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 nome da chave do Registro nos atributos de objeto não foi encontrado.
STATUS_OBJECT_TYPE_MISMATCH	A chave do Registro nomeada é um link simbólico, mas o bit de sinalizador REG_OPTION_OPEN_LINK não está definido em OpenOptions.
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 na 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. Se a chave especificada não existir, a rotina retornará um erro status valor e não fornecerá um identificador de chave.

A rotina ZwOpenKey é semelhante a ZwOpenKeyEx , mas não aceita um parâmetro OpenOptions . O parâmetro OpenOptions de ZwOpenKeyEx 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 ZwOpenKeyEx com OpenOptions = 0 é equivalente a uma chamada para ZwOpenKey.

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

ZwOpenKeyEx 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 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 de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Confira também

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ZwClose

ZwOpenKey