Freigeben über

Verwenden von NTSTATUS-Werten

  • Artikel

Hinweis

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

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

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

Jedem Typ werden zahlreiche Werte zugewiesen. Ein häufiger Fehler beim Testen auf eine erfolgreiche Rückgabe einer Routine besteht darin, den Rückgabewert der Routine mit STATUS_SUCCESS zu vergleichen. Bei diesem Vergleich wird nur einer von mehreren Erfolgswerten überprüft.

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

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

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

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

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

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 zu TRUE ausgewertet, wenn die Routine STATUS_SUCCESS zurückgibt, was keine Fehler anzeigt, oder wenn die informationale status STATUS_OBJECT_NAME_EXISTS zurückgegeben wird, die angibt, dass die Geräteschnittstelle bereits registriert ist.

Nehmen wir als weiteres Beispiel an, dass ein Treiber ZwEnumerateKey aufruft, um die Unterschlüssel eines angegebenen Registrierungsschlüssels aufzulisten. Wenn das NT_SUCCESS Makro zu FALSE ausgewertet wird, liegt dies möglicherweise daran, dass die Routine STATUS_INVALID_PARAMETER zurückgegeben hat, bei dem es sich um einen Fehlercode handelt, oder daran, dass die Routine STATUS_NO_MORE_ENTRIES zurückgegeben hat, bei dem es sich um einen Warncode handelt.

Nehmen wir als letztes Beispiel an, dass ein Treiber ein IRP sendet, das dazu führt, dass ein Treiber auf niedrigerer Ebene Informationen von einem Gerät liest. Wenn der anfordernde Treiber einen Puffer angibt, der zu klein ist, um Informationen zu empfangen, antwortet der Treiber auf niedrigerer Ebene möglicherweise mit der Rückgabe von STATUS_BUFFER_TOO_SMALL, bei dem es sich um einen Fehlercode handelt. Wenn der erste Treiber einen Puffer angibt, der einige, aber nicht alle der angeforderten Informationen empfangen kann, antwortet der Treiber auf niedrigerer Ebene möglicherweise, indem er so viele Daten wie möglich bereitstellt und dann STATUS_BUFFER_OVERFLOW zurückgibt, bei dem es sich um einen Warncode handelt. Wenn der erste Treiber den status-Wert mit NT_SUCCESS oder falsch NT_ERROR testet, werden möglicherweise versehentlich einige der empfangenen Informationen gelöscht.