NTSTATUS-Werte verwenden

  • Artikel

Wichtig

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

Viele Kernelmodus-Standardtreiberroutinen und Treiberunterstützungsroutinen 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 wird in Ntdef.h definiert, und vom System bereitgestellte Statuscodes werden in Ntstatus.h definiert. (Anbieter können auch private Statuscodes definieren, obwohl sie nur 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):

Makro Beschreibung
NT_SUCCESS(Status) Wertet wahr aus, wenn der durch Status angegebene Rückgabewert ein Erfolgstyp (0 − 0x3FFFFFFF) oder ein Informationstyp (0x40000000 − 0x7FFFFFFF) ist.
NT_INFORMATION(Status) Wird als WAHR ausgewertet, wenn der durch Status angegebene Rückgabewert ein Informationstyp ist (0x40000000 − 0x7FFFFFFF).
NT_WARNING(Status) Wertet auf TRUE aus, wenn der durch Status angegebene Rückgabewert ein Warntyp ist (0x80000000 − 0xBFFFFFFF).
NT_ERROR(Status) Wertet auf TRUE aus, 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, was keine Fehler angibt, oder wenn der Informationsstatus STATUS_OBJECT_NAME_EXISTS zurückgegeben wird, was 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 aufzählen zu können. Wenn das NT_SUCCESS Makro als FALSCH ausgewertet wird, liegt dies möglicherweise daran, dass die routine, die STATUS_INVALID_PARAMETER zurückgegeben wurde, ein Fehlercode ist, oder weil die Routine, die STATUS_NO_MORE_ENTRIES zurückgegeben wurde, ein Warncode ist.

Nehmen wir als letztes Beispiel an, dass ein Treiber einen IRP sendet, der 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 erhalten, kann der Treiber auf niedrigerer Ebene reagieren, indem STATUS_BUFFER_TOO_SMALL zurückgegeben wird, bei dem es sich um einen Fehlercode handelt. Wenn der erste Treiber einen Puffer angibt, der einige, aber nicht alle 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.