Menggunakan Nilai NTSTATUS

Catatan

Jika Anda mencari tabel pemetaan nilai NTSTATUS ke kode kesalahan Win32 yang sesuai, lihat Pemetaan Kode Kesalahan NTSTATUS ke Win32.

Banyak rutinitas driver standar mode kernel dan rutinitas dukungan driver menggunakan jenis NTSTATUS untuk nilai pengembalian. Selain itu, driver memberikan nilai berjenis NTSTATUS dalam struktur IO_STATUS_BLOCK IRP saat menyelesaikan RUNP. Jenis NTSTATUS didefinisikan dalam Ntdef.h, dan kode status yang disediakan sistem didefinisikan dalam Ntstatus.h. (Vendor juga dapat menentukan kode status privat, meskipun jarang perlu. Untuk informasi selengkapnya, lihat Menentukan Nilai NTSTATUS Baru.)

Nilai NTSTATUS dibagi menjadi empat jenis: nilai keberhasilan, nilai informasi, peringatan, dan nilai kesalahan.

Banyak nilai ditetapkan untuk setiap jenis. Kesalahan umum, saat menguji pengembalian yang berhasil dari rutinitas, adalah membandingkan nilai pengembalian rutin dengan STATUS_SUCCESS. Perbandingan ini hanya memeriksa salah satu dari beberapa nilai keberhasilan.

Saat menguji nilai pengembalian, Anda harus menggunakan salah satu makro yang disediakan sistem berikut (ditentukan dalam Ntdef.h):

NT_SUCCESS(Status)
Mengevaluasi ke TRUE jika nilai pengembalian yang ditentukan oleh Status adalah jenis keberhasilan (0 − 0x3FFFFFFF) atau jenis informasi (0x40000000 − 0x7FFFFFFF).

NT_INFORMATION(Status)
Mengevaluasi ke TRUE jika nilai pengembalian yang ditentukan oleh Status adalah jenis informasi (0x40000000 − 0x7FFFFFFF).

NT_WARNING(Status)
Mengevaluasi ke TRUE jika nilai pengembalian yang ditentukan oleh Status adalah jenis peringatan (0x80000000 − 0xBFFFFFFF).

NT_ERROR(Status)
Mengevaluasi ke TRUE jika nilai pengembalian yang ditentukan oleh Status adalah jenis kesalahan (0xC0000000 - 0xFFFFFFFF).

Misalnya, driver memanggil IoRegisterDeviceInterface untuk mendaftarkan antarmuka perangkat. Jika driver memeriksa nilai pengembalian menggunakan makro NT_SUCCESS, makro akan mengevaluasi ke TRUE jika rutin mengembalikan STATUS_SUCCESS, yang menunjukkan tidak ada kesalahan, atau jika mengembalikan status informasi STATUS_OBJECT_NAME_EXISTS, yang menunjukkan bahwa antarmuka perangkat sudah terdaftar.

Sebagai contoh lain, misalkan driver memanggil ZwEnumerateKey untuk menghitung subkunci kunci registri tertentu. Jika makro NT_SUCCESS mengevaluasi ke FALSE, mungkin karena rutinitas yang dikembalikan STATUS_INVALID_PARAMETER, yang merupakan kode kesalahan, atau karena rutinitas dikembalikan STATUS_NO_MORE_ENTRIES, yang merupakan kode peringatan.

Sebagai contoh akhir, misalkan driver mengirim IRP yang menyebabkan driver tingkat bawah membaca informasi dari perangkat. Jika driver yang meminta menentukan buffer yang terlalu kecil untuk menerima informasi apa pun, driver tingkat bawah mungkin merespons dengan mengembalikan STATUS_BUFFER_TOO_SMALL, yang merupakan kode kesalahan. Jika driver pertama menentukan buffer yang dapat menerima beberapa, tetapi tidak semua, dari informasi yang diminta, driver tingkat bawah mungkin merespons dengan menyediakan data sebanyak mungkin dan kemudian mengembalikan STATUS_BUFFER_OVERFLOW, yang merupakan kode peringatan. Perhatikan bahwa jika driver pertama menguji nilai status menggunakan NT_SUCCESS atau NT_ERROR salah, itu mungkin secara tidak sengaja menghilangkan beberapa informasi yang diterima.