Função WdfDeviceOpenRegistryKey (wdfdevice.h)

Artigo
02/07/2025

[Aplica-se a KMDF e UMDF]

O método WdfDeviceOpenRegistryKey abre a chave de hardware de um dispositivo ou a chave de software de um driver no registro e cria um objeto de chave de registro da estrutura que representa a chave do Registro.

Sintaxe

NTSTATUS WdfDeviceOpenRegistryKey(
  [in]           WDFDEVICE              Device,
  [in]           ULONG                  DeviceInstanceKeyType,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] DeviceInstanceKeyType

Especifica qual chave ou subchave abrir.

Nota

O UMDF não dá suporte à criação de subchaves.

Este é um OR bit a bit dos sinalizadores a seguir (que são definidos em Wdm.h).

Sinalizador DeviceInstanceKeyType	Significado	Estrutura
PLUGPLAY_REGKEY_DEVICE	Abre a chave de hardware do dispositivo.	KMDF/UMDF
PLUGPLAY_REGKEY_DRIVER	Abre a chave de software do driver. Um driver UMDF que define esse sinalizador também deve definir DesiredAccess como KEY_READ. Caso contrário, esse método retornará STATUS_ACCESS_DENIED.	KMDF/UMDF
PLUGPLAY_REGKEY_CURRENT_HWPROFILE	Um driver KMDF usa esse sinalizador para abrir a cópia da chave de hardware ou software que está no perfil de hardware atual.	KMDF
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	Um driver UMDF usa esses sinalizadores juntos para abrir a subchave ServiceName da chave de software do driver para acesso de leitura/gravação.	UMDF
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	Da mesma forma, um driver UMDF usa esses sinalizadores para abrir a subchave ServiceName da chave de hardware do dispositivo para acesso de leitura/gravação.	UMDF

[in] DesiredAccess

Um valor ACCESS_MASKdigitado que especifica os direitos de acesso que o driver está solicitando para a chave do Registro especificada.

Um driver KMDF normalmente solicita KEY_READ, KEY_WRITEou KEY_READ | KEY_WRITE.

Se você estiver escrevendo um driver UMDF, use a tabela a seguir.

DeviceInstanceKeyType	DesiredAccess
PLUGPLAY_REGKEY_DEVICE	KEY_READ
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	KEY_READ ou KEY_READ \| KEY_SET_VALUE
PLUGPLAY_REGKEY_DRIVER	KEY_READ
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	KEY_READ ou KEY_READ \| KEY_SET_VALUE

Como prática recomendada, peça apenas os tipos de acesso necessários ao driver.

[in, optional] KeyAttributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES que contém atributos fornecidos pelo driver para o novo objeto de chave do Registro. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] Key

Um ponteiro para um local que recebe um identificador para o novo objeto de chave do Registro.

Valor de retorno

WdfDeviceOpenRegistryKey retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceOpenRegistryKey não foi chamado em IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado. Para UMDF, esse valor retornado pode indicar direitos de acesso insuficientes.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar um objeto de chave do Registro.
STATUS_OBJECT_NAME_NOT_FOUND	A chave do Registro especificada não existe.

Para obter uma lista de outros valores retornados que o método WdfDeviceOpenRegistryKey pode retornar, consulte Framework Object Creation Errors.

O método pode retornar outros valores NTSTATUS .

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Observações

Se o driver precisar abrir uma chave de hardware ou software antes de chamar WdfDeviceCreate, ele deverá chamar WdfFdoInitOpenRegistryKey em vez de WdfDeviceOpenRegistryKey.

Quando o driver terminar de usar a chave do Registro que abriu com WdfDeviceOpenRegistryKey, o driver deverá chamar WdfRegistryClose.

Para obter mais informações sobre o registro, chaves de hardware e software e objetos do Registro, consulte Usando o Registro em Framework-Based Drivers.

Exemplos

Para obter exemplos de código que usam WdfDeviceOpenRegistryKey, consulte WdfRegistryCreateKey, WdfRegistryOpenKeye WdfRegistryQueryValue.

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
versão mínima do UMDF	2.0
cabeçalho	wdfdevice.h (inclua Wdf.h)
biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	AccessHardwareKey(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte também

WdfFdoInitOpenRegistryKey

Compartilhar via