RTL_RUN_ONCE_INIT_FN função de retorno de chamada (ntddk.h)

Artigo
02/29/2024

A rotina RunOnceInitialization executa uma operação de inicialização única.

Sintaxe

RTL_RUN_ONCE_INIT_FN (
    _Inout_ PRTL_RUN_ONCE RunOnce,
    _Inout_opt_ PVOID Parameter,
    _Inout_opt_ PVOID *Context
  );

Parâmetros

[in, out] RunOnce

Um ponteiro para o RTL_RUN_ONCE estrutura de inicialização única que o driver passou anteriormente como um parâmetro para a rotina RtlRunOnceExecuteOnce que chamou essa rotina RunOnceInitialization .

[in, out] Parameter

O valor parameter que o driver passou para a rotina RtlRunOnceExecuteOnce que chamou essa rotina RunOnceInitialization .

[out] Context

Um ponteiro para uma variável PVOID na qual a rotina grava os dados de inicialização.

Retornar valor

A rotina RunOnceInitialization retorna um valor diferente de zero para indicar êxito e retorna zero para indicar falha.

Comentários

Uma rotina 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 RunOnceInitialization . O sistema operacional garante que a rotina 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 é reservado para uso pelo sistema operacional. A rotina RunOnceInitialization do driver deve definir esses bits reservados como zero no valor de saída que ele grava em *Contexto. A constante RTL_RUN_ONCE_CTX_RESERVED_BITS definida em Ntddk.h especifica o número de bits de baixa ordem 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 apontado por Context como zero.

Exemplos

Para definir uma rotina de retorno de chamada RunOnceInitialization , 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 a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada RunOnceInitialization chamada 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 _Use_decl_annotations_ anotação à sua definição de função. A _Use_decl_annotations_ anotação 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
Cliente mínimo com suporte	Os drivers podem implementar a rotina RunOnceInitialization somente no Windows Vista e versões posteriores do Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	ntddk.h (inclua Ntddk.h, Ntifs.h)
IRQL	Chamado em IRQL <= APC_LEVEL.