WriteFileEx 函式 (fileapi.h)

將資料寫入指定的檔案或輸入/輸出 (I/O) 裝置。 它會以非同步方式報告其完成狀態,並在寫入完成或取消時呼叫指定的完成常式,而呼叫執行緒處於可警示的等候狀態。

若要以同步方式將資料寫入檔案或裝置,請使用 WriteFile 函式。

語法

BOOL WriteFileEx(
  [in]           HANDLE                          hFile,
  [in, optional] LPCVOID                         lpBuffer,
  [in]           DWORD                           nNumberOfBytesToWrite,
  [in, out]      LPOVERLAPPED                    lpOverlapped,
  [in]           LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

參數

[in] hFile

檔案或 I/O 裝置的控制碼 (例如,檔案、檔案資料流程、實體磁片、磁片區、主控台緩衝區、磁帶機、通訊端、通訊資源、mailslot 或管道) 。

此參數可以是由CreateFile函式以 FILE_FLAG_OVERLAPPED旗標開啟的任何控制碼,或是通訊端或accept函式所傳回的通訊端控制碼。

請勿將 I/O 完成埠與此控制碼產生關聯。 如需詳細資訊,請參閱<備註>一節。

此控制碼也必須具有 GENERIC_WRITE 存取權限。 如需存取權限的詳細資訊,請參閱 檔案安全性和存取權限

[in, optional] lpBuffer

緩衝區的指標,其中包含要寫入檔案或裝置的資料。

此緩衝區在寫入作業期間必須維持有效狀態。 呼叫端在寫入作業完成之前,不得使用此緩衝區。

[in] nNumberOfBytesToWrite

要寫入檔案或裝置的位元組數目。

值為零會指定 Null 寫入作業。 Null 寫入作業的行為取決於基礎檔案系統。

網路上的管道寫入作業限制為每個寫入 65,535 個位元組。 如需管道的詳細資訊,請參閱一節。

[in, out] lpOverlapped

重迭 (非同步) 寫入作業期間,提供要使用的重迭資料結構的 重迭 資料結構指標。

對於支援位元組位移的檔案,您必須指定要開始寫入檔案的位元組位移。 您可以藉由設定OVERLAPPED結構的OffsetOffsetHigh成員來指定此位移。 對於不支援位元組位移的檔案或裝置,會忽略 OffsetOffsetHigh

若要寫入檔案結尾,請將OVERLAPPED結構的 Offset 和OffsetHigh成員指定為0xFFFFFFFF。 這在功能上相當於先前呼叫CreateFile函式,以使用FILE_APPEND_DATA存取來開啟hFile

WriteFileEx函式會忽略重迭結構的hEvent成員。 應用程式在 WriteFileEx 呼叫的內容中,可以自由使用該成員作為自己的用途。 WriteFileEx 會藉由呼叫 或佇列呼叫 來發出寫入作業完成的訊號,也就是 lpCompletionRoutine所指向的完成常式,因此不需要事件控制碼。

WriteFileEx函式會使用OVERLAPPED結構的InternalInternalHigh成員。 您不應該變更這些成員的值。

OVERLAPPED資料結構在寫入作業期間必須維持有效狀態。 它不應該是可在寫入作業擱置完成時超出範圍的變數。

[in] lpCompletionRoutine

當寫入作業完成且呼叫執行緒處於可警示的等候狀態時,要呼叫的完成常式指標。 如需此完成常式的詳細資訊,請參閱 FileIOCompletionRoutine

傳回值

如果函式成功,則傳回非零的值。

如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

如果 WriteFileEx 函式成功,則呼叫執行緒會有非同步 I/O 作業擱置中:檔案的重迭寫入作業。 當此 I/O 作業完成,且呼叫執行緒處於可警示的等候狀態時,作業系統會呼叫 lpCompletionRoutine所指向的函式,而等候會以傳回碼 WAIT_IO_COMPLETION完成。

如果函式成功且檔案寫入作業完成,但呼叫執行緒未處於可警示的等候狀態,系統會將呼叫排入 *lpCompletionRoutine的佇列,直到呼叫執行緒進入可警示的等候狀態為止。 如需可警示的等候狀態和重迭輸入/輸出作業的詳細資訊,請參閱 關於同步處理

備註

使用 WriteFileEx 時,即使函式傳回 「成功」,還是應該檢查 GetLastError ,以檢查是否有「成功」但可能會想要知道的一些結果。 例如,呼叫 WriteFileEx 時的緩衝區溢位會傳回 TRUE,但 GetLastError 會回報具有 ERROR_MORE_DATA溢位。 如果函式呼叫成功且沒有警告條件, GetLastError 會傳回 ERROR_SUCCESS

如果 hFile 參數與I/O 完成埠相關聯,WriteFileEx函式將會失敗。 若要使用這種類型的控制碼執行寫入,請使用 WriteFile 函式。

如果有太多未處理的非同步 I/O 要求, WriteFileEx 函式可能會失敗。 發生這類失敗時, GetLastError 可以傳回 ERROR_INVALID_USER_BUFFERERROR_NOT_ENOUGH_MEMORY

若要取消所有擱置的非同步 I/O 作業,請使用:

  • CancelIo — 此函式只會取消所指定檔案控制碼的呼叫執行緒所發出的作業。
  • CancelIoEx— 此函式會取消執行緒針對指定的檔案控制代碼發出的所有作業。
使用 CancelSynchronousIo 取消暫止的同步 I/O 作業。

取消的 I/O 作業已完成,錯誤 ERROR_OPERATION_ABORTED

如果 hFile 所指定的檔案部分被另一個進程鎖定,而指定的寫入作業會與鎖定的部分重迭, WriteFileEx 會失敗。

寫入檔案時,上次寫入時間不會完全更新,直到所有用於寫入的控制碼都已關閉為止。 因此,若要確保上次寫入時間正確,請在寫入檔案之後立即關閉檔案控制碼。

當寫入作業使用緩衝區時存取輸出緩衝區,可能會導致從該緩衝區寫入的資料損毀。 應用程式不得寫入、重新配置或釋放寫入作業所使用的輸出緩衝區,直到寫入作業完成為止。

請注意,遠端檔案可能無法正確更新時間戳記。 若要確保結果一致,請使用未緩衝的 I/O。

系統會將零個位元組解譯為寫入,以指定 Null 寫入作業, 而 WriteFile 不會截斷或擴充檔案。 若要截斷或擴充檔案,請使用 SetEndOfFile 函式。

應用程式會使用 WaitForSingleObjectExWaitForMultipleObjectsExMsgWaitForMultipleObjectsExSignalObjectAndWaitSleepEx 函式來進入可警示的等候狀態。 如需可警示的等候狀態和重迭 I/O 作業的詳細資訊,請參閱 關於同步處理

如果您直接寫入具有掛接檔案系統的磁片區,您必須先取得磁片區的獨佔存取權。 否則,您有造成資料損毀或系統不穩定的風險,因為應用程式的寫入可能會與其他來自檔案系統的變更衝突,並將磁片區的內容保持不一致的狀態。 若要避免這些問題,Windows Vista 和更新版本中已進行下列變更:

  • 如果磁片區沒有掛接的檔案系統,或下列其中一個條件成立,磁片區控制碼上的寫入將會成功:
    • 要寫入的磁區是開機磁區。
    • 要寫入的磁區位於檔案系統空間之外。
    • 您已使用 FSCTL_LOCK_VOLUMEFSCTL_DISMOUNT_VOLUME明確鎖定或卸載磁片區。
    • 磁片區沒有實際的檔案系統。 (換句話說,它已掛接 RAW 檔案系統。)
  • 如果下列其中一個條件成立,磁片控制碼上的寫入將會成功:
    • 要寫入的磁區不會落在磁片區的範圍內。
    • 要寫入的磁區落在掛接的磁片區內,但您已使用 FSCTL_LOCK_VOLUMEFSCTL_DISMOUNT_VOLUME明確鎖定或卸載磁片區。
    • 要寫入的磁區落在未掛接檔案系統的磁片區中,而不是 RAW。
使用FILE_FLAG_NO_BUFFERING,成功使用CreateFile開啟的檔案有嚴格的需求。 如需詳細資訊,請參閱 檔案緩衝處理。

在Windows 8和Windows Server 2012中,下列技術支援此函式。

技術 支援
伺服器訊息區 (SMB) 3.0 通訊協定 Yes
SMB 3.0 透明容錯移轉 (TFO) Yes
具有向外延展檔案共用的 SMB 3.0 (SO) Yes
叢集共用磁片區檔案系統 (CsvFS) Yes
彈性檔案系統 (ReFS) Yes
 

交易作業

如果有系結至檔案控制碼的交易,則會交易檔案寫入。 如需詳細資訊,請參閱 關於交易式 NTFS

範例

如需範例,請參閱 使用完成常式的具名管道伺服器

規格需求

   
最低支援的用戶端 Windows XP [傳統型應用程式|UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式|UWP 應用程式]
目標平臺 Windows
標頭 fileapi.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

檔案管理功能

FileIOCompletionRoutine

MsgWaitForMultipleObjectsEx

ReadFileEx

SetEndOfFile

SetErrorMode

SignalObjectAndWait

SleepEx

WaitForMultipleObjectsEx

WaitForSingleObjectEx

WriteFile