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 結構的指標。 Information 成員會接收實際從檔案讀取的位元元組數目。

[out] Buffer

呼叫端配置的緩衝區指標，該緩衝區會接收從檔案讀取的數據。

[in] Length

Buffer 所指向緩衝區的大小，以位元組為單位。

[in, optional] ByteOffset

變數的指標，指定讀取作業開始所在檔案中的起始位移。 如果嘗試讀取超過檔案結尾， NtReadFile 會傳回錯誤。

如果對 NtCreateFile 的呼叫設定 了 CreateOptions 旗標FILE_SYNCHRONOUS_IO_ALERT或FILE_SYNCHRONOUS_IO_NONALERT，I/O 管理員會維護目前的檔案位置。 如果是的話， NtReadFile 的呼叫端可以指定使用目前的檔案位置位移，而不是明確的 ByteOffset 值。 您可以使用下列其中一種方法來建立此規格：

  • 指定LARGE_INTEGER值的指標， 並將 HighPart 成員設定為 -1， 並將 LowPart 成員設定為系統定義的值FILE_USE_FILE_POINTER_POSITION。
  • 傳遞 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，則 Length 和 ByteOffset 參數必須是扇區大小的倍數。

NtReadFile 會從指定的 ByteOffset 或目前檔案位置開始讀取指定的 Buffer。 它會在下列其中一個情況下終止讀取作業：

  • 緩衝區已滿，因為已讀取 Length 參數指定的位元元組數目。 因此，在沒有溢位的情況下，無法再將數據放入緩衝區。
  • 讀取作業期間會到達檔案結尾，因此檔案中沒有其他數據要傳送到緩衝區。

如果呼叫端以 DesiredAccess 中設定的 SYNCHRONIZE 旗標開啟檔案，則呼叫線程可以等候檔句柄 FileHandle 同步至讀取作業完成。 每次在句柄上發出的 I/O 作業完成時，都會發出句柄的訊號。 不過，呼叫端不得等候開啟以進行同步檔案存取的句柄， (FILE_SYNCHRONOUS_IO_NONALERT 或FILE_SYNCHRONOUS_IO_ALERT) 。 在此情況下， NtReadFile 會代表呼叫端等候，而且在讀取作業完成之前不會傳回。 只有在符合下列三個條件時，呼叫端才能安全地等候檔句柄：

  • 已針對異步存取開啟句柄 (也就是說，FILE_SYNCHRONOUS_IO_XXX 旗標都未指定) 。
  • 句柄一次只能用於一個 I/O 作業。
  • NtReadFile 傳回STATUS_PENDING。

如果下列任何條件存在，驅動程式應該在系統進程的內容中呼叫 NtReadFile ：

  • 驅動程式已建立傳遞給 NtReadFile 的檔案句柄。
  • NtReadFile 會透過驅動程式所建立的事件通知驅動程式 I/O 完成。
  • NtReadFile 會透過驅動程序傳遞至 NtReadFile 的 APC 回呼例程，通知驅動程式 I/O 完成。

檔案和事件句柄只有在建立句柄的進程內容中才有效。 因此，為了避免安全漏洞，驅動程式應該建立任何檔案或事件句柄，以在系統進程的內容中傳遞至 NtReadFile ，而不是驅動程式所在的進程內容。

同樣地，如果 NtReadFile 透過 APC 通知 I/O 完成的驅動程式，則應該在系統進程的內容中呼叫 NtReadFile ，因為 APC 一律會在發出 I/O 要求的線程內容中引發。 如果驅動程式在系統以外的進程內容中呼叫 NtReadFile，APC 可能會無限期延遲，或完全不會引發。

如需使用檔案的詳細資訊，請參閱 在驅動程式中使用檔案。

NtReadFile 的呼叫端必須在 IRQL = PASSIVE_LEVEL且啟用特殊核心 APC 時執行。

如果在使用者模式中呼叫此函式，您應該使用名稱 「NtReadFile」 而不是 「ZwReadFile」。

針對來自內核模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本會以處理和解譯輸入參數的方式，以不同的方式運作。 如需 例程 NtXxx 和 ZwXxx 版本之間關聯性的詳細資訊，請參閱 使用原生系統服務例程的 Nt 和 Zw 版本。

規格需求

需求 值
最低支援的用戶端 Windows 2000
目標平台 Universal
標頭 ntifs.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL (请参阅一节)
DDI 合規性規則 BufAfterReqCompletedIntIoctlA、BufAfterReqCompletedIoctlA、BufAfterReqCompletedReadA、BufAfterReqCompletedWriteA、HwStorPortProhibitedDDIs、PowerIrpDDis

另請參閱

KeInitializeEvent

ZwCreateFile

NtQueryInformationFile

NtSetInformationFile

NtWriteFile