Uso dei valori NTSTATUS

Nota

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'istanza di IRP durante il completamento degli indirizzi DI ACCESSO. 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 essere necessari. 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.

Numerosi valori vengono assegnati a ogni tipo. Un errore comune, quando si esegue il test per un ritorno riuscito da una routine, consiste nel confrontare il valore restituito della routine con STATUS_SUCCESS. Questo confronto controlla solo uno dei diversi valori di esito positivo.

Quando si testa un valore restituito, è necessario usare una delle macro fornite dal sistema seguenti (definite in Ntdef.h):

NT_SUCCESS(Stato)
Restituisce TRUE se il valore restituito specificato da Status è un tipo di esito positivo (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 usando la macro NT_SUCCESS, la macro restituirà TRUE se la routine restituisce STATUS_SUCCESS, che indica alcun errore o se restituisce lo stato informativo STATUS_OBJECT_NAME_EXISTS, che indica che l'interfaccia del dispositivo è già registrata.

Come un altro esempio, si supponga che un driver chiami ZwEnumerateKey per enumerare le sottochiave di una chiave del Registro di sistema specificata. Se la macro NT_SUCCESS restituisce FALSE, potrebbe essere perché la routine ha restituito STATUS_INVALID_PARAMETER, ovvero un codice di errore o perché la routine ha restituito STATUS_NO_MORE_ENTRIES, ovvero un codice di avviso.

Come esempio finale, si supponga che un driver invii un'IRP che causa un driver di livello inferiore per leggere le informazioni da un dispositivo. Se il driver di richiesta 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 alcuni elementi, ma non tutti, 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. Si noti che se il primo driver testa il valore di stato usando NT_SUCCESS o NT_ERROR in modo errato, potrebbe eliminare inavvertitamente alcune delle informazioni ricevute.