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 結構的 Offset 和 OffsetHigh 成員來指定此位移。 對於不支援位元組位移的檔案或裝置，會忽略 Offset 和 OffsetHigh 。

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

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

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

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_BUFFER 或 ERROR_NOT_ENOUGH_MEMORY。

若要取消所有擱置的異步 I/O 作業，請使用：

  • CancelIo：此函式只會取消所指定檔案句柄的呼叫線程所發出的作業。
  • CancelIoEx：此函式會取消線程針對指定的檔句柄發出的所有作業。

使用 CancelSynchronousIo 取消暫止的同步 I/O 作業。

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

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

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

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

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

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

應用程式會使用 WaitForSingleObjectEx、 WaitForMultipleObjectsEx、 MsgWaitForMultipleObjectsEx、 SignalObjectAndWait 和 SleepEx 函式來進入可警示的等候狀態。 如需可警示的等候狀態和重疊 I/O 作業的詳細資訊，請參閱 關於同步處理。

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

  • 如果磁碟區沒有掛接的文件系統，或下列其中一個條件成立，磁碟區句柄上的寫入將會成功：
    • 要寫入的扇區是開機扇區。
    • 要寫入的扇區位於文件系統空間之外。
    • 您已使用 FSCTL_LOCK_VOLUME 或 FSCTL_DISMOUNT_VOLUME明確鎖定或卸載磁碟區。
    • 磁碟區沒有實際的文件系統。 (換句話說，它已掛接 RAW 文件系統。)
  • 如果下列其中一個條件成立，磁碟句柄上的寫入將會成功：
    • 要寫入的扇區不會落在磁碟區的範圍內。
    • 要寫入的扇區落在掛接的磁碟區內，但您已使用 FSCTL_LOCK_VOLUME 或 FSCTL_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

另請參閱