ZwReadFile 関数 (wdm.h)

ZwReadFile ルーチンは、開いているファイルからデータを読み取ります。

構文

NTSYSAPI NTSTATUS ZwReadFile(
  [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

ファイル オブジェクトを処理します。 このハンドルは、 ZwCreateFile または ZwOpenFile を正常に呼び出すことによって作成 されます。

[in, optional] Event

必要に応じて、読み取り操作の完了後にシグナル状態に設定するイベント オブジェクトへのハンドル。 デバイスドライバーと中間ドライバーでは、このパラメーターを NULL に設定する必要があります。

[in, optional] ApcRoutine

このパラメーターは予約されています。 デバイスドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。

[in, optional] ApcContext

このパラメーターは予約されています。 デバイスドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。

[out] IoStatusBlock

最終的 な完了 状態と要求された読み取り操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 Information メンバーは、ファイルから実際に読み取られたバイト数を受け取ります。

[out] Buffer

ファイルから読み取られたデータを受信する呼び出し元によって割り当てられたバッファーへのポインター。

[in] Length

Buffer が指すバッファーのサイズ (バイト単位)。

[in, optional] ByteOffset

読み取り操作が開始されるファイル内の開始バイト オフセットを指定する変数へのポインター。 ファイルの末尾を超えて読み取ろうとすると、 ZwReadFile はエラーを返します。

ZwCreateFile の呼び出しが CreateOptions フラグFILE_SYNCHRONOUS_IO_ALERTまたはFILE_SYNCHRONOUS_IO_NONALERTのいずれかに設定されている場合、I/O マネージャーは現在のファイル位置を維持します。 その場合、 ZwReadFile の呼び出し元は、明示的な ByteOffset 値の代わりに現在のファイル位置オフセットを使用するように指定できます。 この仕様は、次のいずれかの方法を使用して行うことができます。

• HighPart メンバーが -1 に設定され、LowPart メンバーがシステム定義値に設定されたLARGE_INTEGER値へのポインター FILE_USE_FILE_POINTER_POSITION指定します。

• ByteOffset に NULL ポインターを渡します。

ZwReadFile は、I/O マネージャーによって維持されている現在のファイル位置を使用している場合に、読み取り操作が完了したときに読み取られたバイト数を追加することで、現在のファイル位置を更新します。

I/O マネージャーが現在のファイル位置を維持している場合でも、呼び出し元は、明示的な ByteOffset 値を ZwReadFile に渡すことで、この位置をリセットできます。 これを行うと、現在のファイル位置がその ByteOffset 値に自動的に変更され、読み取り操作が実行され、実際に読み取られたバイト数に従って位置が更新されます。 この手法により、呼び出し元にアトミックな seek-and-read サービスが提供されます。

[in, optional] Key

デバイスドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。

戻り値

ZwReadFile は 、STATUS_SUCCESSまたは適切な NTSTATUS エラー コードを返します。

注釈

ZwReadFile の呼び出し元は、DesiredAccess パラメーターに設定されたFILE_READ_DATAまたはGENERIC_READ値を持つ ZwCreateFile を既に呼び出している必要があります。

上記の ZwCreateFile の呼び出しで CreateOptions パラメーターのFILE_NO_INTERMEDIATE_BUFFERING フラグを ZwCreateFile に設定した場合、Length パラメーターと ByteOffset パラメーターを ZwReadFile に設定するには、セクター サイズの倍数にする必要があります。 詳細については、「 ZwCreateFile」を参照してください。

ZwReadFile は 、指定された ByteOffset または現在のファイル位置から、指定された Buffer への読み取りを開始 します。 次のいずれかの条件で読み取り操作を終了します。

• Length パラメーターで指定されたバイト数が読み取られたため、バッファーがいっぱいです。 そのため、オーバーフローなしでは、これ以上データをバッファーに配置できません。

• 読み取り操作中にファイルの末尾に到達するため、ファイル内のデータをバッファーに転送する必要はありません。

呼び出し元が DesiredAccess に SYNCHRONIZE フラグを設定してファイルを開いた場合、呼び出し元のスレッドは、ファイル ハンドル FileHandle を待機することで、読み取り操作の完了に同期できます。 ハンドルは、ハンドルに対して発行された I/O 操作が完了するたびに通知されます。 ただし、呼び出し元は、同期ファイル アクセス (FILE_SYNCHRONOUS_IO_NONALERTまたはFILE_SYNCHRONOUS_IO_ALERT) のために開かれたハンドルを待機することはできません。 この場合、 ZwReadFile は呼び出し元の代わりに待機し、読み取り操作が完了するまで戻りません。 呼び出し元は、次の 3 つの条件がすべて満たされた場合にのみ、ファイル ハンドルを安全に待機できます。

• 非同期アクセス用にハンドルが開かれた (つまり、どちらのFILE_SYNCHRONOUS_IO_XXX フラグも指定されませんでした)。

• ハンドルは、一度に 1 つの I/O 操作にのみ使用されています。

• ZwReadFile がSTATUS_PENDING返されました。

ドライバーは、次のいずれかの条件が存在する場合、システム プロセスのコンテキストで ZwReadFile を呼び出す必要があります。

• ドライバーは、 ZwReadFile に渡すファイル ハンドルを作成しました。

• ZwReadFile は、ドライバーが作成したイベントによって、I/O 完了をドライバーに通知します。

• ZwReadFile は、ドライバーが ZwReadFile に渡す APC コールバック ルーチンを使用して、I/O 完了をドライバーに通知します。

ファイル ハンドルとイベント ハンドルは、ハンドルが作成されるプロセス コンテキストでのみ有効です。 そのため、セキュリティ ホールを回避するために、ドライバーは、ドライバーが存在するプロセスのコンテキストではなく、システム プロセスのコンテキストで ZwReadFile に渡す任意のファイルまたはイベント ハンドルを作成する必要があります。

同様に、APC を使用して I/O 完了をドライバーに通知する場合は、システム プロセスのコンテキストで ZwReadFile を呼び出す必要があります。これは、APC は常に I/O 要求を発行するスレッドのコンテキストで発生するためです。 ドライバーがシステム 1 以外のプロセスのコンテキストで ZwReadFile を呼び出すと、APC が無期限に遅延したり、まったく起動しない可能性があります。

ファイルの操作の詳細については、「 ドライバーでのファイルの使用」を参照してください。

ZwReadFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル API が有効になっている必要があります。

この関数の呼び出しがユーザー モードで行われる場合は、"ZwReadFile" ではなく "NtReadFile" という名前を使用する必要があります。

要件

こちらもご覧ください

KeInitializeEvent

ZwCreateFile

ZwQueryInformationFile

ZwSetInformationFile

ZwWriteFile