NTSTATUS 値の使用

Note

NTSTATUS 値と対応する Win32 エラー コードのマッピングの表については、「 NTSTATUS から Win32 エラー コード マッピング」を参照してください。

多くのカーネル モード 標準ドライバー ルーチン とドライバー サポート ルーチンは、戻り値に NTSTATUS 型を使用します。 さらに、ドライバーは IRP の完了時に IRP の IO_STATUS_BLOCK 構造体に NTSTATUS 型の値 を提供します。 NTSTATUS 型は Ntdef.h で定義され、システム提供の状態コードは Ntstatus.h で定義されます。 (ベンダーはプライベート状態コードを定義することもできますが、ほとんど必要ありません。詳細については、「 新しい NTSTATUS 値の定義」を参照してください)。

NTSTATUS 値は、成功値、情報値、警告、エラー値の 4 種類に分かれています。

各型には多数の値が割り当てられます。 ルーチンからの正常な戻り値をテストする場合、一般的な間違いは、ルーチンの戻り値とSTATUS_SUCCESSを比較することです。 この比較では、いくつかの成功値の 1 つだけがチェックされます。

戻り値をテストする場合は、次のいずれかのシステム指定マクロ (Ntdef.h で定義) を使用する必要があります。

NT_SUCCESS(Status)
Status で指定された戻り値が成功の種類 (0 - 0x3FFFFFFF) または情報型 (0x40000000 - 0x7FFFFFFF) の場合は TRUE に評価されます。

NT_INFORMATION(Status)
Status で指定された戻り値が情報型 (0x40000000 - 0x7FFFFFFF) の場合は TRUE に評価されます。

NT_WARNING(Status)
Status で指定された戻り値が警告の種類 (0x80000000 - 0xBFFFFFFF) の場合は TRUE に評価されます。

NT_ERROR(Status)
Status で指定された戻り値がエラーの種類 (0xC0000000 - 0xFFFFFFFF) の場合は TRUE に評価されます。

たとえば、ドライバーが IoRegisterDeviceInterface を 呼び出してデバイス インターフェイスを登録するとします。 ドライバーがNT_SUCCESS マクロを使用して戻り値を確認する場合、ルーチンがSTATUS_SUCCESSを返す場合、エラーがないことを示す場合、またはデバイス インターフェイスが既に登録されていることを示す情報状態STATUS_OBJECT_NAME_EXISTSを返す場合、マクロは TRUE に 評価されます。

別の例として、ドライバーが ZwEnumerateKey を 呼び出して、指定したレジストリ キーのサブキーを列挙するとします。 NT_SUCCESS マクロが FALSE に評価される場合は、ルーチンがエラー コードであるSTATUS_INVALID_PARAMETERを返したか、ルーチンが警告コードであるSTATUS_NO_MORE_ENTRIESを返したためである可能性があります。

最後の例として、ドライバーは、下位レベルのドライバーがデバイスから情報を読み取る原因となる IRP を送信するとします。 要求元のドライバーが、情報を受信するには小さすぎるバッファーを指定した場合、下位レベルのドライバーは、エラー コードである STATUS_BUFFER_TOO_SMALLを返すことによって応答する可能性があります。 最初のドライバーが、要求された情報の一部 (すべてではない) を受信できるバッファーを指定した場合、下位レベルのドライバーは、可能な限り多くのデータを提供し、警告コードであるSTATUS_BUFFER_OVERFLOWを返すことによって応答する可能性があります。 最初のドライバーがNT_SUCCESSを使用して状態値をテストした場合、または正しくNT_ERRORされていない場合、受信した情報の一部が誤って削除される可能性があることに注意してください。