RTL_RUN_ONCE_INIT_FN função de retorno de chamada (ntddk.h)
A rotina de RunOnceInitialization executa uma operação de inicialização única.
Sintaxe
ULONG /* LOGICAL */
NTAPI
RTL_RUN_ONCE_INIT_FN (
_Inout_ PRTL_RUN_ONCE RunOnce,
_Inout_opt_ PVOID Parameter,
_Inout_opt_ PVOID *Context
);
typedef RTL_RUN_ONCE_INIT_FN *PRTL_RUN_ONCE_INIT_FN;
Parâmetros
[in, out] RunOnce
Um ponteiro para a estrutura de inicialização RTL_RUN_ONCE única que o driver passou anteriormente como um parâmetro para a rotina rtlRunOnceExecuteOnce que chamou essa rotina de RunOnceInitialization.
[in, out] Parameter
O parâmetro valor que o driver passou para a rotina de rtlRunOnceExecuteOnce que chamou essa rotina de RunOnceInitialization.
[out] Context
Um ponteiro para uma variável PVOID na qual a rotina grava os dados de inicialização.
Valor de retorno
A rotina RunOnceInitialization retorna um valor diferente de zero para indicar êxito e retorna zero para indicar falha.
Observações
Uma rotina de runOnceInitialization implementada pelo driver executa a inicialização específica do driver e grava os dados de inicialização no local de memória para o qual o parâmetro Context aponta. Os drivers usam a rotina rtlRunOnceExecuteOnce para fazer uma chamada única para uma rotina de RunOnceInitialization. O sistema operacional garante que a rotina de RunOnceInitialization não seja chamada duas vezes para o mesmo valor do parâmetro RunOnce.
Um pequeno número de bits de baixa ordem no local apontado pelo parâmetro Context são reservados para uso pelo sistema operacional. A rotina de runOnceInitialization do do driver deve definir esses bits reservados como zero no valor de saída que ele grava em *Context. A constante RTL_RUN_ONCE_CTX_RESERVED_BITS definida em Ntddk.h especifica o número de bits de ordem baixa reservados. Atualmente, RTL_RUN_ONCE_CTX_RESERVED_BITS é definido como dois, o que significa que o driver deve definir os dois bits menos significativos do valor PVOID apontados por Context como zero.
Exemplos
Para definir um RunOnceInitialization rotina de retorno de chamada, 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 RunOnceInitialization rotina de retorno de chamada denominada MyRunOnceInitialization, use o tipo RTL_RUN_ONCE_INIT_FN conforme mostrado neste exemplo de código:
RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;
Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
ULONG
MyRunOnceInitialization(
PRTL_RUN_ONCE RunOnce,
PVOID Parameter,
PVOID *Context
)
{
// Function body
}
O tipo de função RTL_RUN_ONCE_INIT_FN é 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_RUN_ONCE_INIT_FN 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 |
|---|---|
| de cliente com suporte mínimo | Os drivers podem implementar a rotina RunOnceInitialization somente no Windows Vista e versões posteriores do Windows. |
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | ntddk.h (inclua Ntddk.h, Ntifs.h) |
| IRQL | Chamado no <DO IRQL = APC_LEVEL. |