NtReadFile 函式
從開啟的檔案讀取資料。
此函式是使用者模式，相當於 Windows 驅動程式套件 (WDK) 中所述的 ZwReadFile 函式。
語法
NTSTATUS NtReadFile(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE Event,
_In_opt_ PIO_APC_ROUTINE ApcRoutine,
_In_opt_ PVOID ApcContext,
_Out_ PIO_STATUS_BLOCK IoStatusBlock,
_Out_ PVOID Buffer,
_In_ ULONG Length,
_In_opt_ PLARGE_INTEGER ByteOffset,
_In_opt_ PULONG Key
);
參數
-
FileHandle [in]
-
檔案物件的控制碼。 此控制碼是由成功呼叫 NtCreateFile 或 NtOpenFile所建立。
-
事件 [in， 選擇性]
-
選擇性地，在讀取作業完成之後，要設定為訊號狀態的事件物件控制碼。 裝置和中繼驅動程式應該將此參數設定為 Null。
-
ApcRoutine [in， optional]
-
此參數已保留備用。 裝置和中繼驅動程式應該將此指標設定為 Null。
-
ApcCoNtext [in， optional]
-
此參數已保留備用。 裝置和中繼驅動程式應該將此指標設定為 Null。
-
IoStatusBlock [out]
-
接收最終完成狀態的 IO_STATUS_BLOCK 結構的指標，以及所要求讀取作業的相關資訊。 Information成員會接收實際從檔案讀取的位元組數目。
-
緩衝區 [out]
-
呼叫端配置的緩衝區指標，該緩衝區會接收從檔案讀取的資料。
-
長度 [in]
-
Buffer所指向之緩衝區的大小，以位元組為單位。
-
ByteOffset [in， optional]
-
變數的指標，指定讀取作業開始之檔案中的起始位元組位移。 如果嘗試在檔案結尾之外讀取， 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， 選擇性]
-
裝置和中繼驅動程式應該將此指標設定為 Null。
傳回值
NtReadFile 會傳回STATUS_SUCCESS或適當的 NTSTATUS 錯誤碼。
備註
NtReadFile的呼叫端必須已經使用DesiredAccess參數中設定的FILE_READ_DATA或GENERIC_READ值呼叫NtCreateFile。
如果上述 對 NtCreateFile 的呼叫將 CreateOptions 參數中的 FILE_NO_INTERMEDIATE_BUFFERING 旗標設定為 NtCreateFile， 則 Length 和 ByteOffset 參數必須是 扇 區大小的倍數。 如需詳細資訊，請參閱 NtCreateFile。
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 會透過 APC 回呼常式，通知驅動程式 I/O 完成，驅動程式傳遞給 NtReadFile。
檔案和事件控制碼只有在建立控制碼的進程內容中才有效。 因此，若要避免安全性漏洞，驅動程式應該建立任何檔案或事件控制碼，以在系統進程的內容中傳遞至 NtReadFile ，而不是驅動程式所在的進程內容。
同樣地，如果 NtReadFile 透過 APC 通知 I/O 完成的驅動程式，則應該在系統進程的內容中呼叫 NtReadFile ，因為 APC 一律會在發出 I/O 要求的執行緒內容中引發。 如果驅動程式在系統以外的進程內容中呼叫 NtReadFile ，APC 可能會無限期延遲，或完全不會引發。
如需使用檔案的詳細資訊，請參閱 在驅動程式中使用檔案。
NtReadFile的呼叫端必須在 IRQL = PASSIVE_LEVEL且啟用特殊核心 APC 時執行。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 |
Windows 2000 專業版 [僅限傳統型應用程式] |
| 最低支援的伺服器 |
Windows 2000 Server [僅限傳統型應用程式] |
| 目標平台 |
|
| 標頭 |
|
| 程式庫 |
|
| DLL |
|
另請參閱