Compartilhar via


Função WdfDeviceOpenRegistryKey (wdfdevice.h)

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

Observação

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

Esse é 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 de tipo ACCESS_MASK 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_WRITE ou 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 WDF_OBJECT_ATTRIBUTES que contém atributos fornecidos pelo driver para o novo objeto registry-key. 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.

Retornar valor

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 Erros de criação de objeto da estrutura.

O método pode retornar outros valores NTSTATUS.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

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, as chaves de hardware e software e os objetos do Registro, consulte Usando o Registro no Framework-Based Drivers.

Exemplos

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

Requisitos

Requisito Valor
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)

Confira também

WdfFdoInitOpenRegistryKey