Função WdfFdoInitOpenRegistryKey (wdffdo.h)
[Aplica-se a KMDF e UMDF]
O método WdfFdoInitOpenRegistryKey abre a chave de hardware de um dispositivo ou a chave de software de um driver no registro e cria um objeto de chave do Registro de estrutura que representa a chave do Registro.
Sintaxe
NTSTATUS WdfFdoInitOpenRegistryKey(
[in] PWDFDEVICE_INIT DeviceInit,
[in] ULONG DeviceInstanceKeyType,
[in] ACCESS_MASK DesiredAccess,
[in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
[out] WDFKEY *Key
);
Parâmetros
[in] DeviceInit
Um ponteiro para uma estrutura WDFDEVICE_INIT que o driver obteve de sua função de retorno de chamada EvtDriverDeviceAdd .
[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 que seu driver precisa.
[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
WdfFdoInitOpenRegistryKey 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 |
|---|---|
|
WdfFdoInitOpenRegistryKey não foi chamado em IRQL = PASSIVE_LEVEL. |
|
Um parâmetro inválido foi especificado ou o driver não obteve a estrutura WDFDEVICE_INIT de sua função de retorno de chamada EvtDriverDeviceAdd . Para UMDF, esse valor retornado pode indicar direitos de acesso insuficientes. |
|
Não foi possível alocar um objeto de chave do Registro. |
|
A chave do Registro especificada não existe. |
Para obter uma lista de outros valores retornados que o método WdfFdoInitOpenRegistryKey pode retornar, consulte Erros de criação de objeto de estrutura.
O método também pode retornar outros valores NTSTATUS.
Comentários
O driver deve chamar WdfFdoInitOpenRegistryKey antes de chamar WdfDeviceCreate. Para obter mais informações sobre como chamar WdfDeviceCreate, consulte Criando um objeto de dispositivo de estrutura.
Para obter mais informações sobre o método WdfFdoInitOpenRegistryKey , consulte Criando objetos de dispositivo em um driver de função.
ou mais informações sobre o registro, chaves de hardware e software e objetos do Registro, consulte Usando o Registro em drivers de Framework-Based.
Exemplos
O exemplo de código a seguir abre a chave de hardware de um dispositivo, com acesso de leitura.
WDFKEY key;
NTSTATUS status;
status = WdfFdoInitOpenRegistryKey(
DeviceInit,
PLUGPLAY_REGKEY_DEVICE,
GENERIC_READ,
WDF_NO_OBJECT_ATTRIBUTES,
&key
);
if (!NT_SUCCESS(status)) {
return status;
}
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 | wdffdo.h (include Wdf.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade da DDI | DeviceInitAPI(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |