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
| Requisito | Valore |
|---|---|
| Client minimo supportato | I driver possono implementare la routine RunOnceInitialization solo in Windows Vista e versioni successive di Windows. |
| Piattaforma di destinazione | Desktop |
| Intestazione | ntddk.h (include Ntddk.h, Ntifs.h) |
| IRQL | Chiamato in IRQL <= APC_LEVEL. |