Função WdfRegistryOpenKey (wdfregistry.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfRegistryOpenKey abre uma chave do Registro especificada e cria um objeto de chave de registro da estrutura que representa a chave do Registro.

Sintaxe

NTSTATUS WdfRegistryOpenKey(
  [in, optional] WDFKEY                 ParentKey,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parâmetros

[in, optional] ParentKey

Um identificador para um objeto de chave de registro da estrutura. Esse objeto representa uma chave do Registro pai que o driver abriu. Esse parâmetro é opcional e pode ser NULL. Se o parâmetro não for NULL, a chave especificada por KeyName deverá residir sob essa chave pai no Registro. Para obter mais informações sobre essa chave pai, consulte a seção Comentários.

[in] KeyName

Um ponteiro para uma estrutura UNICODE_STRING que contém o nome da chave a ser aberta. O nome da chave pode incluir informações de caminho. Se ParentKey for NULL, KeyName deverá especificar um caminho completo para uma chave do Registro. Para obter exemplos, consulte a seção Comentários.

[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. Para obter uma lista de direitos de acesso que os drivers normalmente usam para chaves do Registro, consulte Abrindo um identificador para um objeto Registry-Key. Seu driver deve solicitar apenas os tipos de acesso necessários. Por exemplo, o driver não deve solicitar KEY_ALL_ACCESS se ele lerá apenas a chave do Registro.

[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

WdfRegistryOpenKey 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	WdfRegistryOpenKey não foi chamado em IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar um objeto de chave do Registro.
STATUS_ACCESS_DENIED	O sistema negou os direitos de acesso especificados.
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 WdfRegistryOpenKey pode retornar, consulte Erros de criação de objeto da estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Comentários

Para obter um identificador para um objeto de chave do Registro que representa uma chave pai, seu driver pode chamar WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKey ou WdfFdoInitOpenRegistryKey.

O formato de cadeia de caracteres especificado no parâmetro KeyName depende se o chamador é um driver KMDF ou um driver UMDF. Por exemplo, para abrir o seguinte caminho:

HKLM\System\CurrentControlSet\Control

Seu driver pode usar essa lógica condicional:

#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\" 
#endif

Quando o driver terminar de usar uma chave do Registro aberta com WdfRegistryOpenKey, o driver deverá chamar WdfRegistryClose.

Para obter mais informações sobre objetos de chave do Registro, consulte Usando o Registro em drivers de Framework-Based.

Exemplos

O exemplo de código a seguir abre a chave de software de um driver e, em seguida, abre a chave do Registro MySubKey , que está localizada sob a chave de software do driver.

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"MySubKey"
                         );
    status = WdfRegistryOpenKey(
                                hKey,
                                &myKeyStr,
                                KEY_READ,
                                WDF_NO_OBJECT_ATTRIBUTES,
                                &subkey
                                );
}

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	wdfregistry.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)