Uso dei valori NTSTATUS

Nota

Se si sta cercando una tabella di mapping dei valori NTSTATUS ai codici di errore Win32 corrispondenti, vedere Mapping di codice errore da 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 IO_STATUS_BLOCK di un IRP durante il completamento degli IRP. 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.

Numerosi valori vengono assegnati a ogni tipo. Un errore comune, durante il test di una restituzione corretta 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 esegue il test di 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 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 restituirà 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, 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 la lettura di informazioni da un dispositivo da parte di un driver di livello inferiore. 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 in grado di ricevere alcune informazioni, ma non tutte, delle informazioni richieste, il driver di livello inferiore potrebbe rispondere fornendo il maggior numero di dati possibile e quindi restituendo STATUS_BUFFER_OVERFLOW, ovvero un codice di avviso. Si noti che se il primo driver verifica il valore di stato usando NT_SUCCESS o NT_ERROR in modo errato, potrebbe inavvertitamente eliminare alcune delle informazioni ricevute.