EX_CALLBACK_FUNCTION funzione di callback (wdm.h)
La routine RegistryCallback di un driver di filtro può monitorare, bloccare o modificare un'operazione del Registro di sistema.
Sintassi
EX_CALLBACK_FUNCTION ExCallbackFunction;
NTSTATUS ExCallbackFunction(
[in] PVOID CallbackContext,
[in, optional] PVOID Argument1,
[in, optional] PVOID Argument2
)
{...}
Parametri
[in] CallbackContext
Valore passato dal driver come parametro Context a CmRegisterCallback o CmRegisterCallbackEx quando ha registrato questa routine RegistryCallback .
[in, optional] Argument1
Valore tipizzato REG_NOTIFY_CLASS che identifica il tipo di operazione del Registro di sistema che viene eseguita e se la routine RegistryCallback viene chiamata prima o dopo l'esecuzione dell'operazione del Registro di sistema.
[in, optional] Argument2
Puntatore a una struttura che contiene informazioni specifiche del tipo di operazione del Registro di sistema. Il tipo di struttura dipende dal valore tipizzato REG_NOTIFY_CLASS per Argument1, come illustrato nella tabella seguente. Per informazioni sui valori tipizzati REG_NOTIFY_CLASS disponibili per le versioni del sistema operativo, vedere REG_NOTIFY_CLASS.
A partire da Windows 7, la struttura dei dati effettiva passata quando la classe notify è RegNtPreCreateKeyEx o RegNtPreOpenKeyEx è rispettivamente la versione V1 di questa struttura, REG_CREATE_KEY_INFORMATION_V1 o REG_OPEN_KEY_INFORMATION_V1. Controllare il membro riservato per determinare la versione della struttura.
| Numero di versione | Nome struttura |
|---|---|
| 0 | REG_CREATE_KEY_INFORMATION e REG_OPEN_KEY_INFORMATION |
| 1 | REG_CREATE_KEY_INFORMATION_V1 e REG_OPEN_KEY_INFORMATION_V1 |
Valore restituito
Per altre informazioni sui casi in cui una routine RegistryCallback deve restituire ognuno di questi valori di stato, vedere Filtro delle chiamate al Registro di sistema.
Commenti
Per ricevere una notifica delle operazioni del Registro di sistema, un componente in modalità kernel (ad esempio il componente driver di un pacchetto software antivirus) può chiamare CmRegisterCallback o CmRegisterCallbackEx per registrare una routine RegistryCallback .
La routine RegistryCallback può esaminare il contenuto dei buffer di input e di output forniti per le operazioni del Registro di sistema. Un'operazione del Registro di sistema può essere avviata da un'applicazione in modalità utente che chiama una routine del Registro di sistema in modalità utente (ad esempio RegCreateKeyEx o RegOpenKeyEx) o da un driver che chiama una routine del Registro di sistema in modalità kernel (ad esempio ZwCreateKey o ZwOpenKey). Un buffer di input è un buffer di memoria fornito dall'iniziatore da cui il Registro di sistema legge i dati di input per l'operazione. Un buffer di output è un buffer fornito dall'iniziatore in cui il Registro di sistema scrive i dati di output richiesti dall'iniziatore.
Prima di chiamare la routine RegistryCallback , i probe del kernel (per verificare l'allineamento e l'accessibilità) tutti i membri delle strutture Argument2 che puntano ai buffer di output nella memoria in modalità utente, ma non acquisisce i buffer di output in modalità utente nella memoria di sistema. La routine di callback deve racchiudere qualsiasi accesso di un buffer di output in un blocco try/except . Se la routine di callback deve passare un puntatore del buffer di output a una routine di sistema (ad esempio ZwOpenKey) e il buffer è in modalità utente, la routine di callback deve prima acquisire il buffer.
La gestione dei buffer di input dipende dalla versione di Windows. A partire da Windows 8, il kernel acquisisce tutti i buffer di input a cui puntano i membri delle strutture Argument2 nella memoria di sistema prima di chiamare la routine RegistryCallback. Nelle versioni di Windows prima di Windows 8, il kernel esegue il probe di tutti i membri delle strutture Argument2 che puntano ai buffer di input nella memoria in modalità utente, ma acquisisce solo alcuni di questi buffer nella memoria di sistema. In queste versioni precedenti di Windows, la routine di callback deve racchiudere qualsiasi accesso di un buffer di input in un blocco try/except . Inoltre, se la routine di callback deve passare un puntatore del buffer di input a una routine di sistema (ad esempio ZwOpenKey) e il buffer si trova in memoria in modalità utente, la routine di callback deve prima acquisire il buffer.
La tabella seguente riepiloga i requisiti per gli accessi al buffer tramite la routine RegistryCallback .
| Tipo di buffer | Versione di Windows | Puntatore al buffer passato alla routine di callback | Sicurezza per la routine di callback per l'accesso diretto? | Sicuro da passare alle routine di sistema (ad esempio ZwOpenKey)? |
|---|---|---|---|---|
| Input in modalità utente | Windows 8 e versioni successive | Punta ai dati acquisiti. | Sì | Sì |
| Input in modalità utente | Windows 7 e versioni precedenti | Punta ai dati acquisiti o al buffer in modalità utente originale. | No. Deve leggere in try/except. | No. Deve allocare memoria kernel, copiare i dati dal buffer originale in try/except e passare i dati copiati alla routine di sistema. |
| Output in modalità utente | Tutti | Punta al buffer originale in modalità utente. | No. Deve scrivere in try/except. | No. Deve allocare memoria kernel, passare la memoria del kernel alla routine di sistema e copiare i risultati nel buffer originale in try/except. |
| Input e output in modalità kernel | Tutti | Punta al buffer originale in modalità kernel. | Sì | Sì |
Per altre informazioni sulle routine RegistryCallback e sui driver di filtro del Registro di sistema, vedere Filtro delle chiamate al Registro di sistema.
RegistryCallback viene eseguito in IRQL = PASSIVE_LEVEL e nel contesto del thread che esegue l'operazione del Registro di sistema.
Esempio
Per definire una routine di callback RegistryCallback , è 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 RegistryCallback denominata MyRegistryCallback, usare il tipo di EX_CALLBACK_FUNCTION come illustrato nell'esempio di codice seguente:
EX_CALLBACK_FUNCTION MyRegistryCallback;
Implementare quindi la routine di callback come indicato di seguito:
_Use_decl_annotations_
NTSTATUS
MyRegistryCallback(
PVOID CallbackContext,
PVOID Argument1,
PVOID Argument2
)
{
// Function body
}
Il tipo di funzione EX_CALLBACK_FUNCTION è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli 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 usate le annotazioni applicate al tipo di funzione EX_CALLBACK_FUNCTION nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver WDM. Per informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Supportato a partire da Windows XP (vedere sezione Valore restituito). |
| Piattaforma di destinazione | Desktop |
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Chiamato in PASSIVE_LEVEL (vedere la sezione Osservazioni). |