NTSTATUS 値の使用

多くのカーネル モード 標準ドライバー ルーチン とドライバー サポート ルーチンは、戻り値に 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 を誤って使用して状態値をテストした場合、受信した情報の一部が誤って削除される可能性があることに注意する必要があります。