Usare valori NTSTATUS
Importante
Se si sta cercando una tabella di mapping di valori NTSTATUS ai codici di errore Win32 corrispondenti, vedere Mapping del codice di errore NTSTATUS a Win32.
Molte routine di driver standard in modalità kernel e routine di supporto driver usano il tipo NTSTATUS per i valori restituiti. Inoltre, i driver forniscono un valore tipizzato NTSTATUS nella struttura di IO_STATUS_BLOCK di un IRP quando si completano i runtime di integrazione. Il tipo NTSTATUS è definito in Ntdef.h e i codici di stato forniti dal sistema sono definiti in Ntstatus.h. I fornitori possono anche definire codici di stato privati, anche se raramente devono. Per altre informazioni, vedere Definizione di nuovi valori NTSTATUS.
I valori NTSTATUS sono suddivisi in quattro tipi: valori di esito positivo, valori informativi, avvisi e valori di errore.
A ogni tipo vengono assegnati numerosi valori. Un errore comune, quando si verifica un esito positivo di una routine, consiste nel confrontare il valore restituito della routine con STATUS_SUCCESS. Questo confronto controlla solo uno dei diversi valori di esito positivo.
Durante il test di un valore restituito, è consigliabile usare una delle macro fornite dal sistema seguenti (definite in Ntdef.h):
| Macro | Descrizione |
|---|---|
| NT_SUCCESS(Stato) | Restituisce TRUE se il valore restituito specificato da Status è un tipo di operazione riuscita (0 − 0x3FFFFFFF) o un tipo informativo (0x40000000 − 0x7FFFFFFF). |
| NT_INFORMATION(Stato) | Restituisce TRUE se il valore restituito specificato da Status è un tipo informativo (0x40000000 − 0x7FFFFFFF). |
| NT_WARNING(Stato) | Restituisce TRUE se il valore restituito specificato da Status è un tipo di avviso (0x80000000 − 0xBFFFFFFF). |
| NT_ERROR(Stato) | Restituisce TRUE se il valore restituito specificato da Status è un tipo di errore (0xC0000000 - 0xFFFFFFFF). |
Si supponga, ad esempio, che un driver chiami IoRegisterDeviceInterface per registrare un'interfaccia del dispositivo. Se il driver controlla il valore restituito utilizzando la macro NT_SUCCESS, la macro restituisce TRUE se la routine restituisce STATUS_SUCCESS, che indica nessun errore o se restituisce lo stato informativo STATUS_OBJECT_NAME_EXISTS, che indica che l'interfaccia del dispositivo è già registrata.
Come altro esempio, si supponga che un driver chiami ZwEnumerateKey per enumerare le sottochiavi di una chiave del Registro di sistema specificata. Se la macro NT_SUCCESS restituisce FALSE, è possibile che la routine restituisca STATUS_INVALID_PARAMETER, ovvero un codice di errore o perché la routine restituita STATUS_NO_MORE_ENTRIES, ovvero un codice di avviso.
Come esempio finale, si supponga che un driver invii un IRP che fa sì che un driver di livello inferiore legga le informazioni da un dispositivo. Se il driver richiedente specifica un buffer troppo piccolo per ricevere informazioni, il driver di livello inferiore potrebbe rispondere restituendo STATUS_BUFFER_TOO_SMALL, ovvero un codice di errore. Se il primo driver specifica un buffer che può ricevere alcune informazioni, ma non tutte, delle informazioni richieste, il driver di livello inferiore potrebbe rispondere fornendo il maggior numero possibile di dati e quindi restituendo STATUS_BUFFER_OVERFLOW, ovvero un codice di avviso. Se il primo driver verifica il valore di stato usando NT_SUCCESS o NT_ERROR in modo non corretto, potrebbe eliminare inavvertitamente alcune delle informazioni ricevute.