ReadFile2

從檔案指針指示的位置開始從檔案讀數據的函式

函式功能

該函式從檔案指針指示的位置開始從檔案讀數據,在讀操作完成後,如果檔案句柄不是用重疊屬性來創建,則檔案指針用實際讀的字數來調整。

如果檔案句柄為重疊的輸入和輸出(I/O)操作而創建,則應用程式必須在讀操作之後調整檔案指針的位置。

函式原型

BOOL ReadFile(HANDLE hFile, LPVOID lpBuffer, DWORD nNumberOfBytesToRead, LPDWORD lpNumberOfBytesRead, LPOVERLAPPED lpOverlapped);

參數

hFile:指向要讀的檔案的句柄,檔案句柄一定用 GENERIC_READ 對檔案的訪問來創建。

Windows NT:對於異步讀操作,hFile 可為任何一個句柄,該句柄可以通過 CreatFile函式用 FILE_FLAG_OVERLAPPED 標誌來打開或通過插孔或接收函式返回的插孔句柄來打開。

Windows 95:對於異步讀操作,hFILE 可以是一個通信源、郵件插孔或命名的管道句柄,此管道句柄通過 CreatFile 用 FILE_FLAG_OVERLAPPED 標誌來打開或通過插孔或接收函式返回的插孔句柄來打開,Windows 95 不支持磁碟檔案的異步讀操作。

lpBuffer:指向一個從檔案存取數據的緩衝區的指針。

nNumberOfBytesToRead:從檔案讀的位元組數目。

lpNumberOfBytesRead:指向一個讀位元組數的指針,在做任何工作或錯誤檢測之前,ReadFile 把此值設定為零,當 ReadFile 在命名管道上返回 TRUE 時,如果此參數為零,則用 nNumberOfBytesToWrite 調用 WriteFile 函式的信息模組將管道的另一端設定為零。

Windows NT:如果 lpOverlapped 為 NULL,則 lpNumberOfBytesRead 不為 NULL;如果 lpOverlapped 不為 NULL,則 lpNumberOfBytesRead 可以為 NULL,如果這是一個重疊寫操作,則可通過調用 GetQueuedCompletionStatus 來得到讀位元組的數目。

Windows 95 或 Windows 98:此參數不能為 NULL。

lpOverlapped:指向一個OVERLAPPED 結構的指針,如果用 FILE_FLAG_OVERLAPPED 來創建 hFile,則需要此結構,如果用 FILE_FLAG_OVERLAPPED 來打開 hFile,則 lpOverlapped 參數一定不是 NULL,它必須指向一個有效的 OVERLAPPED結構,如果 hFile 是由 FILE_FLAG_OVERLAPPED 創建且 lpOverlapped 為 NULL,則函式可不正確地記錄關於讀操作是完全的。

如果 hFile 用 FILE_FLAG_OVERLAPPED 打開,且 lpOverlapped 不為 NULL,則讀操作在 OVERLAPPED 結構中指定的位移處開始,在完成操作之前,且 ReadFile 可以返回在這種情況下 ReadFile 返回 FALSE 且 GetLastError 函式返回 ERROR_IO_PENDING 這使在讀操作完成時,調用套用系統繼續。在 OVERLAPPED 結構中指定的事件被設定為讀操作完成的傳送信號狀態。

如果 hFile 不用 FILE_FLAG_OVERLAPPED 打開,且 lpOverlapped 不為 NULL,則讀操作在當前檔案位置開始且至操作完成,ReadFile 函式返回。

如果 hFile 不用 FILE_FLAG_OVERLAPPED 打開,且 lpOverlapped 不為 NULL,則讀操作 OVERLAPPED 結構指定的位移處開始,直到操作完成,ReadFile 函式返回。

返回值

當下列之一的為真時,ReadFile 函式返回。寫操作的管道寫終端完成,請求讀的位元組數目或出現錯誤。如果函式調用成功,則返回值為非零值。如果返回值為非零值,且讀位元組數目為零,則在讀操作時檔案指針超出檔案終端。但是,如果檔案用 FILE_FLAG_OVERLAPPED 打開且 lpOverlapped 不為 NULL,則返回值為 FALSE,且當檔案指針超過檔案當前終端時 GetLastError 函式返回 ERROR_HANDLE_EOF。如果函式調用失敗,則返回值為零。若想獲得更多錯誤信息,請調用 GetLastError 函式。

檔案訪問一定在檔案內位元組位移處開始,該檔案為容量扇區大小的整數倍,為決定一個容量扇區的大小,調用 GetDiskFreeSpace 函式。

檔案訪問必須是對於位元組數目的訪問,該位元組數目為容量扇區大小的整數倍,例如如果扇區大小為512位元組,應用程式可以請求512、1024或2048位元組的讀和寫訪問,但不是335、981、7171位元組。緩衝區對讀、寫操作的地址一定為對齊扇區(在記憶體地址上對齊,該記憶體為容量扇區大小的整數倍)。一種對齊扇區的緩衝區的方法是用 VirtualAlloc 函式來分配緩衝區,此函式分配記憶體,該記憶體在為系統頁面大小的整數倍的地址上對齊,因為無論是頁面還是扇區大小都是2的冪,用系統頁面大小的倍數對齊的記憶體也可用容量扇區大小的倍數來對齊調整(‘對齊’改為‘調整’)。

在讀操作正在有緩衝區時訪問輸入緩衝區,則可導致輸入緩衝區數據的破壞,直到讀操作完成為止,應用程式才能讀、寫重分配或釋放一個正被一個讀操作使用的輸入緩衝區。

如果一個命名的管道正在信息模組中讀且狹義個信息比 nNumberOfBytesToRead 參數長,則 ReadFile 返回 FALSE 且 GetLastError 返回 ERROR_MODE_DATA,剩下的信息也許通過下一次對 ReadFile 或 PeekNamePipe 函式的調用來讀。

當從通信設備來讀數據時,且當用 SetCommTimeouts 和 GetCommTimeouts 函式來設定和檢取逾時時,ReadFile的行為由當前通信逾時來操縱,如果不能設定逾時時,則會出現不可預料的結果,有關信息逾時更詳細的資料,參見 COMMTIMEOUTS。

如果 ReadFile 試圖從緩衝區太小的郵件插孔讀數據,則函式返回 FALSE 且 GetLastError 函式返回 ERROR_INSUFFICENT_BUFFER。

如果匿名寫通道句柄已經被關閉且 ReadFile 試圖用相應的匿名讀通道句柄來讀,則函式返回 FALSE 且 GetLastError 返回 ERROR_BROKEN_PIPE。

當不足夠多的明顯異步 I/O 請求時,ReadFile 函式可能失敗且返回 ERROR_INVALID_USER_BUFFER 或 ERROR_NOT_ENOUGH_MEMORY。

ReadFile 代碼為狀態檔案終端而檢測與異步和同步讀操作不同。

當一個同步讀操作到達檔案末尾時,ReadFile 返回 TRUE 且把 lpNumberOfBytesResd 設定為零,下列樣本代碼用來為同步讀操作檔案末尾的檢測。

// Attempt a synchronous read operation

bResut = ReadFile(hFile, ∈Buffer, nBytesToRead, &nBytesRead, NULL);

// Check for end of file

if(bResult&nBytesRead==0)

{// we're at the end of the file}

在其始的 ReadFile 調用期間,或下一步異步操作期間,一個異步讀操作可以遇到檔案的末尾。

如果對於異步讀操作在 ReadFile 時間 EOF 被刪除,則 ReadFile 返回 FALSE 且 GetLastError 返回 ERROR_HANDLE_EOF。

如果下一次異步操作期間 EOF 被刪除,對 GetOverlappedResult 的調用,可以導致操作返回 FALSE 且 GetError 返回 ERROR_HANDLE_EOF。

用 Cancel 函式來取消所有未知異步 I/O 操作,此函式只取消由關於指定檔案句柄的調用執行緒發布的操作,被取消的 I/O 操作用錯誤 ERROR_OPERATION_ABORTED 來完成。

如果試圖從一個沒有軟碟的軟碟機中讀數據,則系統顯示一個信息框告訴用戶重新執行此操作,為避免系統顯示此信息框,用 SEM_NOOPENFILEERRORBOX 來調用 SetErrorMode 函式。

Windows CE:lpOverlapped 參數一定被設定為 NULL,Windows CE 不允許用重疊屬性來創建檔案,Windows CE 不支持對檔案的異步讀操作。

速查

Windows NT 3.1及以上版本、Windows 95及以上版本、Windows CE 1.0及以上版本,頭檔案:winbase.h;庫檔案:kernel32.lib。

相關詞條

相關搜尋

熱門詞條

聯絡我們