Função IoOpenDeviceRegistryKey (wdm.h)

Artigo
08/08/2023

A rotina IoOpenDeviceRegistryKey retorna um identificador para um local de estado do Registro para uma instância de dispositivo específica.

Sintaxe

NTSTATUS IoOpenDeviceRegistryKey(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  ULONG          DevInstKeyType,
  [in]  ACCESS_MASK    DesiredAccess,
  [out] PHANDLE        DeviceRegKey
);

Parâmetros

[in] DeviceObject

Ponteiro para o PDO (objeto de dispositivo físico) da instância do dispositivo para a qual o local de estado do Registro deve ser aberto.

[in] DevInstKeyType

Especifica sinalizadores que indicam se uma chave de hardware específica do dispositivo ou uma chave de software específica do driver deve ser aberta. Os sinalizadores também indicam se a chave é relativa ao perfil de hardware atual. Para obter mais informações sobre chaves de hardware e software, consulte Introdução às Chaves do Registro para Drivers.

Os sinalizadores são definidos da seguinte maneira:

PLUGPLAY_REGKEY_DEVICE

Abra a chave de hardware do dispositivo, um local de estado do registro específico do dispositivo que contém informações sobre o dispositivo. Esse sinalizador não pode ser especificado com PLUGPLAY_REGKEY_DRIVER.

PLUGPLAY_REGKEY_DRIVER

Abra a chave de software do dispositivo, um local de estado do registro específico do dispositivo para armazenar informações específicas do driver. Esse sinalizador não pode ser especificado com PLUGPLAY_REGKEY_DEVICE.

PLUGPLAY_REGKEY_CURRENT_HWPROFILE

Os perfis de hardware foram preteridos e o estado não deve ser armazenado em relação a um perfil de hardware.

Abra uma chave relativa ao perfil de hardware atual para obter informações de dispositivo ou driver. Isso permite que o driver acesse informações de configuração específicas do perfil de hardware. O chamador deve especificar PLUGPLAY_REGKEY_DEVICE ou PLUGPLAY_REGKEY_DRIVER com esse sinalizador.

[in] DesiredAccess

Especifica o valor ACCESS_MASK que representa o acesso que o chamador precisa para a chave. Consulte a rotina ZwCreateKey para obter uma descrição de cada direito de acesso KEY_XXX .

[out] DeviceRegKey

Ponteiro para um buffer alocado pelo chamador que, no retorno bem-sucedido, contém um identificador para o local de estado do Registro solicitado.

Retornar valor

IoOpenDeviceRegistryKey retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Os possíveis valores retornados por erro incluem o seguinte:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Possivelmente indica que o chamador especificou um conjunto ilegal de sinalizadores DevInstKeyType ou forneceu um DeviceObject que não é um PDO válido.

Comentários

O driver deve chamar ZwClose para fechar o identificador retornado dessa rotina quando o acesso não for mais necessário.

As chaves do Registro abertas por essa rotina não sãovolatile.

Os aplicativos de instalação do modo de usuário podem acessar essas chaves do Registro usando CM_Open_DevNode_Key ou funções de informações do dispositivo , como SetupDiOpenDevRegKey ou SetupDiCreateDevRegKey.

Para preencher previamente o estado nesses locais de estado do Registro no momento da instalação do pacote de driver, use as diretivas AddReg do INF em um arquivo INF.

Os chamadores de IoOpenDeviceRegistryKey devem estar em execução em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)