Użyj wartości NTSTATUS

Ważne

Jeśli szukasz tabeli mapowań wartości NTSTATUS na odpowiednie kody błędów Win32, zobacz NTSTATUS to Win32 Error Code Mappings (Mapowania kodu błędu NTSTATUS na Win32).

Wiele standardowych procedur sterowników trybu jądra i procedur obsługi sterowników używa typu NTSTATUS dla zwracanych wartości. Ponadto sterowniki zapewniają wartość typu NTSTATUS w strukturze IO_STATUS_BLOCK podczas kończenia IRP. Typ NTSTATUS jest zdefiniowany w ntdef.h, a kody stanu dostarczone przez system są zdefiniowane w ntstatus.h. (Dostawcy mogą również definiować kody stanu prywatnego, chociaż rzadko muszą. Aby uzyskać więcej informacji, zobacz Definiowanie nowych wartości NTSTATUS).

Wartości NTSTATUS są podzielone na cztery typy:

• Wartości powodzenia
• Wartości informacyjne
• Warnings
• Wartości błędów

Do każdego typu są przypisywane liczne wartości. Typowym błędem podczas testowania pomyślnego powrotu z rutyny jest porównanie wartości zwracanej rutyny z "STATUS_SUCCESS". To porównanie sprawdza tylko jedną z kilku wartości powodzenia.

Podczas testowania wartości zwracanej należy użyć jednego z następujących makr dostarczonych przez system (zdefiniowanych w ntdef.h):

Makro	Opis
NT_SUCCESS(Status)	Zwraca wartość TRUE , jeśli zwracana wartość określona przez stan jest typem powodzenia (0 — 0x3FFFFFFF) lub typem informacyjnym (0x40000000 — 0x7FFFFFFF).
NT_INFORMATION(stan)	Ocena na TRUE, jeśli zwracana wartość określona przez Status jest typem informacyjnym (0x40000000 — 0x7FFFFFFF).
NT_WARNING(status)	Zwraca wartość TRUE jeśli zwracana wartość określona przez Status jest typem ostrzeżenia (0x80000000 — 0xBFFFFFFF).
NT_ERROR(Status)	Zwraca wartość TRUE , jeśli zwracana wartość określona przez stan jest typem błędu (0xC0000000 — 0xFFFFFFFF).

Załóżmy na przykład, że sterownik wywołuje interfejs IoRegisterDeviceInterface w celu zarejestrowania interfejsu urządzenia. Jeśli sterownik sprawdza wartość zwracaną przy użyciu makra NT_SUCCESS, makro zwraca wartość TRUE , jeśli procedura zwraca STATUS_SUCCESS, co oznacza brak błędów lub zwraca stan informacyjny STATUS_OBJECT_NAME_EXISTS, co oznacza, że interfejs urządzenia jest już zarejestrowany.

W innym przykładzie załóżmy, że sterownik wywołuje element ZwEnumerateKey , aby wyliczyć podklucze określonego klucza rejestru. Jeśli makro NT_SUCCESS zwróci wartość FALSE, może to być spowodowane tym, że rutyna zwróciła STATUS_INVALID_PARAMETER, czyli kod błędu, lub dlatego, że rutyna zwróciła STATUS_NO_MORE_ENTRIES, czyli kod ostrzegawczy.

W ostatnim przykładzie załóżmy, że sterownik wysyła protokół IRP, który powoduje, że sterownik niższego poziomu odczytuje informacje z urządzenia. Jeśli sterownik żądający określa bufor, który jest zbyt mały, aby otrzymywać jakiekolwiek informacje, sterownik niższego poziomu może odpowiedzieć, zwracając STATUS_BUFFER_TOO_SMALL, czyli kod błędu. Jeśli pierwszy sterownik określa bufor, który może odbierać niektóre, ale nie wszystkie, żądane informacje, sterownik niższego poziomu może reagować, podając jak najwięcej danych, a następnie zwracając STATUS_BUFFER_OVERFLOW, co jest kodem ostrzegawczym. Jeśli pierwszy sterownik niepoprawnie sprawdza wartość stanu przy użyciu NT_SUCCESS lub NT_ERROR, może przypadkowo utracić niektóre odebrane informacje.