Verwenden von NTSTATUS-Werten

Hinweis

Wenn Sie nach einer Tabelle mit Zuordnungen von NTSTATUS-Werten zu den entsprechenden Win32-Fehlercodes suchen, lesen Sie NTSTATUS zu Win32 Error Code Mappings.

Viele Standardtreiberroutinen und Treiberunterstützungsroutinen im Kernelmodus verwenden den NTSTATUS-Typ für Rückgabewerte. Darüber hinaus stellen Treiber beim Abschließen von IRPs einen NTSTATUS-typierten Wert in der IO_STATUS_BLOCK Struktur eines IRP bereit. Der NTSTATUS-Typ ist in Ntdef.h definiert, und die vom System bereitgestellten Statuscodes werden in Ntstatus.h definiert. (Anbieter können auch private Statuscodes definieren, obwohl sie selten erforderlich sind. Weitere Informationen finden Sie unter Definieren neuer NTSTATUS-Werte.)

NTSTATUS-Werte sind in vier Typen unterteilt: Erfolgswerte, Informationswerte, Warnungen und Fehlerwerte.

Jedem Typ werden zahlreiche Werte zugewiesen. Ein häufiger Fehler beim Testen einer erfolgreichen Rückgabe aus einer Routine besteht darin, den Rückgabewert der Routine mit STATUS_SUCCESS zu vergleichen. Dieser Vergleich überprüft nur einen von mehreren Erfolgswerten.

Beim Testen eines Rückgabewerts sollten Sie eines der folgenden vom System bereitgestellten Makros verwenden (definiert in Ntdef.h):

NT_SUCCESS(Status)
Wird auf TRUE ausgewertet, wenn der durch Status angegebene Rückgabewert ein Erfolgstyp (0 − 0x3FFFFFFF) oder ein Informationstyp (0x40000000 − 0x7FFFFFFF) ist.

NT_INFORMATION(Status)
Wird auf TRUE ausgewertet, wenn der durch Status angegebene Rückgabewert ein Informationstyp (0x40000000 − 0x7FFFFFFF) ist.

NT_WARNING(Status)
Wird auf TRUE ausgewertet, wenn der durch Status angegebene Rückgabewert ein Warntyp (0x80000000 − 0xBFFFFFFF).

NT_ERROR(Status)
Wird auf TRUE ausgewertet, wenn der durch Status angegebene Rückgabewert ein Fehlertyp ist (0xC0000000 - 0xFFFFFFFF).

Angenommen, ein Treiber ruft IoRegisterDeviceInterface auf, um eine Geräteschnittstelle zu registrieren. Wenn der Treiber den Rückgabewert mithilfe des NT_SUCCESS-Makros überprüft, wird das Makro auf TRUE ausgewertet, wenn die Routine STATUS_SUCCESS zurückgibt, die keine Fehler angibt, oder wenn der Informationsstatus STATUS_OBJECT_NAME_EXISTS zurückgegeben wird, was angibt, dass die Geräteschnittstelle bereits registriert ist.

Angenommen, ein Treiber ruft ZwEnumerateKey auf, um die Unterschlüssel eines angegebenen Registrierungsschlüssels aufzählen zu können. Wenn das NT_SUCCESS-Makro auf FALSE ausgewertet wird, liegt es möglicherweise daran, dass die Routine STATUS_INVALID_PARAMETER zurückgegeben wird, was ein Fehlercode ist, oder weil die Routine, die STATUS_NO_MORE_ENTRIES zurückgegeben hat, ein Warncode ist.

Angenommen, ein Treiber sendet ein IRP, das dazu führt, dass ein Treiber auf niedrigerer Ebene Informationen von einem Gerät lesen kann. Wenn der anfordernde Treiber einen Puffer angibt, der zu klein ist, um Informationen zu empfangen, kann der Treiber auf niedrigerer Ebene reagieren, indem STATUS_BUFFER_TOO_SMALL zurückgegeben wird, was ein Fehlercode ist. Wenn der erste Treiber einen Puffer angibt, der einige, aber nicht alle der angeforderten Informationen empfangen kann, kann der Treiber auf niedrigerer Ebene reagieren, indem so viele Daten wie möglich bereitgestellt und dann STATUS_BUFFER_OVERFLOW zurückgegeben werden, was ein Warncode ist. Wenn der erste Treiber den Statuswert mit NT_SUCCESS oder NT_ERROR falsch testet, kann er versehentlich einige der empfangenen Informationen ablegen.