RTL_RUN_ONCE_INIT_FN funzione di callback (ntddk.h)

La routine RunOnceInitialization esegue un'operazione di inizializzazione una tantum.

Sintassi

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

Parametri

[in, out] RunOnce

Puntatore alla struttura di inizializzazione RTL_RUN_ONCE una tantum passata il driver in precedenza come parametro alla routine RtlRunOnceExecuteOnce che ha chiamato questa routine RunOnceInitialization .

[in, out] Parameter

Valore Parameter passato dal driver alla routine RtlRunOnceExecuteOnce che ha chiamato questa routine RunOnceInitialization .

[out] Context

Puntatore a una variabile PVOID in cui la routine scrive i dati di inizializzazione.

Valore restituito

La routine RunOnceInitialization restituisce un valore diverso da zero per indicare l'esito positivo e restituisce zero per indicare l'errore.

Commenti

Una routine RunOnceInitialization implementata dal driver esegue l'inizializzazione specifica del driver e quindi scrive i dati di inizializzazione nella posizione di memoria a cui punta il parametro Context . I driver usano la routine RtlRunOnceExecuteOnce per effettuare una chiamata una tantum a una routine RunOnceInitialization . Il sistema operativo garantisce che la routine RunOnceInitialization non venga chiamata due volte per lo stesso valore del parametro RunOnce .

Un numero ridotto di bit di ordine basso nella posizione a cui punta il parametro Context è riservato per l'uso da parte del sistema operativo. La routine RunOnceInitialization del driver deve impostare questi bit riservati su zero nel valore di output scritto in *Context. La costante RTL_RUN_ONCE_CTX_RESERVED_BITS definita in Ntddk.h specifica il numero di bit di ordine basso riservati. Attualmente, RTL_RUN_ONCE_CTX_RESERVED_BITS è definito come due, il che significa che il driver deve impostare i due bit meno significativi del valore PVOID a cui punta Context su zero.

Esempio

Per definire una routine di callback RunOnceInitialization , è innanzitutto necessario fornire una dichiarazione di funzione che identifica il tipo di routine di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback RunOnceInitialization denominata MyRunOnceInitialization, usare il tipo RTL_RUN_ONCE_INIT_FN come illustrato nell'esempio di codice seguente:

RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
ULONG 
  MyRunOnceInitialization(
    PRTL_RUN_ONCE  RunOnce,
    PVOID  Parameter,
    PVOID  *Context
    )
  {
      // Function body
  }

Il tipo di funzione RTL_RUN_ONCE_INIT_FN è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione _Use_decl_annotations_ alla definizione della funzione. L'annotazione _Use_decl_annotations_ garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione RTL_RUN_ONCE_INIT_FN nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver WDM. Per informazioni su _Use_decl_annotations_, vedere Annotazione del comportamento della funzione.

Requisiti

Vedi anche

RTL_RUN_ONCE

RtlRunOnceBeginInitialize

RtlRunOnceComplete

RtlRunOnceExecuteOnce

RtlRunOnceInitialize