RTL_QUERY_REGISTRY_ROUTINE função de retorno de chamada (wdm.h)
A rotina queryRoutine fornece informações sobre um valor do Registro que foi solicitado em uma chamada anterior à rotina de rtlQueryRegistryValues.
Sintaxe
RTL_QUERY_REGISTRY_ROUTINE RtlQueryRegistryRoutine;
NTSTATUS RtlQueryRegistryRoutine(
[in] PWSTR ValueName,
[in] ULONG ValueType,
[in] PVOID ValueData,
[in] ULONG ValueLength,
[in, optional] PVOID Context,
[in, optional] PVOID EntryContext
)
{...}
Parâmetros
[in] ValueName
Especifica a chave do Registro associada ao valor do Registro solicitado. Esse parâmetro é um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que contém a chave.
[in] ValueType
Especifica o tipo de valor do Registro armazenado com a chave do Registro especificada. Para obter mais informações sobre os tipos de valor do Registro, consulte a definição do parâmetro Type em KEY_VALUE_BASIC_INFORMATION.
[in] ValueData
Um ponteiro para o valor de dados associado à chave do Registro especificada. O driver deve tratar esse valor como somente leitura. Para obter mais informações sobre o tipo de dados de valor que ValueData aponta, consulte a definição do parâmetro tipo em KEY_VALUE_BASIC_INFORMATION.
[in] ValueLength
Especifica o comprimento, em bytes, do valor para o qual ValueData aponta.
[in, optional] Context
Especifica o valor do parâmetro Context especificado pelo driver na chamada anterior para RtlQueryRegistryValues.
[in, optional] EntryContext
Especifica um valor EntryContext em um elemento de matriz QueryTable que o driver especificou na chamada anterior para RtlQueryRegistryValues.
Valor de retorno
QueryRoutine retornará STATUS_SUCCESS se a chamada for bem-sucedida. Caso contrário, ele retornará um código de status de erro apropriado. Use somente códigos de status definidos no arquivo de cabeçalho Ntstatus.h.
Observações
Um driver no modo kernel implementa uma rotina de de QueryRoutine. Essa rotina é chamada pela rotina RtlQueryRegistryValues.
Para obter informações sobre um ou mais valores do Registro, o driver chama rtlQueryRegistryValues e passa um ponteiro, como um parâmetro de entrada, para uma matriz de estruturas de RTL_QUERY_REGISTRY_TABLE. Cada estrutura nessa matriz contém um ponteiro para um queryRoutine implementado pelo driver rotina e uma solicitação de informações sobre um valor específico do Registro. Para cada estrutura na matriz, RtlQueryRegistryValues chama a rotina QueryRoutine especificada e passa para essa rotina um conjunto de parâmetros que contêm as informações solicitadas sobre o valor do registro especificado.
Para obter mais informações sobre a estrutura de RTL_QUERY_REGISTRY_TABLE, consulte RtlQueryRegistryValues.
Exemplos
Para definir uma rotina de retorno de chamada QueryRoutine, primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a análise de código para drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação encontram erros e é um requisito para gravar drivers para o sistema operacional Windows.
Por exemplo, para definir um rotina de retorno de chamada que é denominada MyQueryRoutine, use o tipo RTL_QUERY_REGISTRY_ROUTINE, conforme mostrado neste exemplo de código:
RTL_QUERY_REGISTRY_ROUTINE MyQueryRoutine;
Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
NTSTATUS
MyQueryRoutine(
PWSTR ValueName,
ULONG ValueType,
PVOID ValueData,
ULONG ValueLength,
PVOID Context,
PVOID EntryContext
)
{
// Function body
}
O tipo de função RTL_QUERY_REGISTRY_ROUTINE é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação _Use_decl_annotations_ à sua definição de função. A anotação _Use_decl_annotations_ garante que as anotações aplicadas ao tipo de função RTL_QUERY_REGISTRY_ROUTINE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre _Use_decl_annotations_, consulte Anotando o comportamento da função.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Chamado no PASSIVE_LEVEL. |