NtReadFile 関数 (ntifs.h)
NtReadFile ルーチンは、開いているファイルからデータを読み取ります。
構文
__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[out] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
パラメーター
[in] FileHandle
ファイル オブジェクトへのハンドル。 このハンドルは、NtCreateFileまたは NtOpenFile正常に呼び出すことによって作成されます。
[in, optional] Event
必要に応じて、読み取り操作の完了後にシグナル状態に設定するイベント オブジェクトのハンドル。 デバイス ドライバーと中間ドライバーでは、このパラメーターを NULL に設定する必要があります。
[in, optional] ApcRoutine
このパラメーターは予約されています。 デバイス ドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。
[in, optional] ApcContext
このパラメーターは予約されています。 デバイス ドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。
[out] IoStatusBlock
最終的な完了状態と、要求された読み取り操作に関する情報を受け取る IO_STATUS_BLOCK 構造体へのポインター。 情報 メンバーは、ファイルから実際に読み取られたバイト数を受け取ります。
[out] Buffer
ファイルから読み取られたデータを受信する呼び出し元によって割り当てられたバッファーへのポインター。
[in] Length
Bufferが指すバッファーのサイズ (バイト単位)。
[in, optional] ByteOffset
読み取り操作を開始するファイル内の開始バイト オフセットを指定する変数へのポインター。 ファイルの末尾を超えて読み取ろうとすると、NtReadFile エラーが返されます。
NtCreateFile の呼び出しCreateOptions フラグFILE_SYNCHRONOUS_IO_ALERTまたはFILE_SYNCHRONOUS_IO_NONALERTのいずれかを設定すると、I/O マネージャーは現在のファイル位置を維持します。 その場合、NtReadFile の呼び出し元は、明示的な ByteOffset 値の代わりに現在のファイル位置オフセットを使用するように指定できます。 この仕様は、次のいずれかの方法を使用して行うことができます。
- HighPart メンバーが -1 に設定され、LowPart メンバーがシステム定義値FILE_USE_FILE_POINTER_POSITIONに設定されているLARGE_INTEGER値へのポインターを指定します。
- ByteOffset に NULL ポインター渡します。
NtReadFile は、I/O マネージャーによって維持されている現在のファイル位置を使用している場合、読み取り操作の完了時に読み取られたバイト数を追加することで、現在のファイルの位置を更新します。
I/O マネージャーが現在のファイル位置を維持している場合でも、呼び出し元は明示的な ByteOffset 値を NtReadFile 渡すことによって、この位置をリセットできます。 これにより、現在のファイルの位置が ByteOffset 値 に自動的に変更され、読み取り操作が実行され、実際に読み取られたバイト数に従って位置が更新されます。 この手法により、呼び出し元にアトミックなシークアンドリード サービスが提供されます。
[in, optional] Key
デバイス ドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。
戻り値
NtReadFile は、STATUS_SUCCESSまたは適切な NTSTATUS エラー コードを返します。
備考
NtReadFile の呼び出し元は、DesiredAccess パラメーターに設定されたFILE_READ_DATAまたはGENERIC_READ値を使用して、NtCreateFileを既に呼び出している必要があります。
上記の NtCreateFile 呼び出し、CreateOptions パラメーターのFILE_NO_INTERMEDIATE_BUFFERING フラグを NtCreateFile をするように設定した場合、NtReadFile を するには、Length および ByteOffset パラメーターをセクター サイズの倍数にする必要があります。
NtReadFile は、指定された ByteOffset または現在のファイル位置から、指定された Bufferへの読み取りを開始します。 次のいずれかの条件で読み取り操作を終了します。
- Length パラメーターで指定されたバイト数が読み取られたため、バッファーがいっぱいです。 そのため、オーバーフローなしでは、これ以上データをバッファーに配置できません。
- 読み取り操作中にファイルの末尾に到達するため、バッファーに転送するデータはファイル内にありません。
呼び出し元が desiredAccess で設定SYNCHRONIZE フラグを使用してファイルを開いた場合、呼び出し元のスレッドは FileHandle ファイル ハンドルを待機することで、読み取り操作の完了に同期できます。 ハンドルは、ハンドルに対して発行された I/O 操作が完了するたびに通知されます。 ただし、呼び出し元は、同期ファイル アクセス (FILE_SYNCHRONOUS_IO_NONALERTまたはFILE_SYNCHRONOUS_IO_ALERT) のために開かれたハンドルを待機してはなりません。 この場合、ntReadFile 呼び出し元の代わりに待機し、読み取り操作が完了するまで戻りません。 呼び出し元は、次の 3 つの条件がすべて満たされている場合にのみ、ファイル ハンドルを安全に待機できます。
- 非同期アクセス用にハンドルが開かれました (つまり、XXXフラグFILE_SYNCHRONOUS_IO_指定されませんでした)。
- ハンドルは、一度に 1 つの I/O 操作にのみ使用されています。
- NtReadFile 返されるSTATUS_PENDING します。
ドライバーは、次のいずれかの条件が存在する場合、システム プロセスのコンテキストで NtReadFile 呼び出す必要があります。
- ドライバーは、NtReadFile に渡すファイル ハンドル作成しました。
- NtReadFile は、ドライバーが作成したイベントを使用して、I/O の完了をドライバーに通知します。
- NtReadFile は、ドライバーが NtReadFile に渡す APC コールバック ルーチンを使用して、I/O 完了ドライバーに通知します。
ファイル ハンドルとイベント ハンドルは、ハンドルが作成されるプロセス コンテキストでのみ有効です。 したがって、セキュリティホールを回避するために、ドライバーは、ドライバーが存在するプロセスのコンテキストではなく、システム プロセスのコンテキストで NtReadFile に渡す任意のファイルまたはイベント ハンドルを作成する必要があります。
同様に、NtReadFile は、APC を使用して I/O 完了をドライバーに通知する場合、システム プロセスのコンテキストで呼び出す必要があります。これは、APC は常に I/O 要求を発行するスレッドのコンテキストで起動されるためです。 ドライバーがシステム 1 以外のプロセスのコンテキストで ntReadFile 呼び出した場合、APC が無期限に遅延したり、まったく起動しない可能性があります。
ファイルの操作の詳細については、「ドライバー でのファイルの使用」を参照してください。
NtReadFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル API が有効になっている 必要があります。
この関数の呼び出しがユーザー モードで発生する場合は、"ZwReadFile" ではなく"NtReadFile" という名前を使用する必要があります。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXxx と ZwXxx バージョンの間の関係の詳細については、「ネイティブ システム サービス ルーチンの Nt および Zw バージョンの使用 を参照してください。
必要条件
要件 | 価値 |
---|---|
サポートされる最小クライアント | Windows 2000 |
ターゲット プラットフォーム の | 万国 |
ヘッダー | ntifs.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
ライブラリ | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |
DDI コンプライアンス規則 を する | BufAfterReqCompletedIntIoctlA、BufAfterReqCompletedIoctlA、BufAfterReqCompletedReadA、BufAfterReqCompletedWriteA、HwStorPortProhibitedDDIs、PowerIrpDDis |
関連項目
NtQueryInformationFileの
NtSetInformationFileの
NtWriteFileの