LockFileEx 函式 (fileapi.h)

發行項
02/26/2024

鎖定指定的檔案，以供呼叫進程獨佔存取。此函式可以同步或異步操作，而且可以要求獨佔或共享鎖定。

語法

BOOL LockFileEx(
  [in]      HANDLE       hFile,
  [in]      DWORD        dwFlags,
            DWORD        dwReserved,
  [in]      DWORD        nNumberOfBytesToLockLow,
  [in]      DWORD        nNumberOfBytesToLockHigh,
  [in, out] LPOVERLAPPED lpOverlapped
);

參數

[in] hFile

檔案的句柄。必須使用 GENERIC_READ 或 GENERIC_WRITE 訪問許可權來建立句柄。如需詳細資訊，請參閱檔案安全性和訪問許可權。

[in] dwFlags

此參數可以是下列一或多個值。

值	意義
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	函式會要求獨佔鎖定。否則，它會要求共享鎖定。
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	如果函式無法取得要求的鎖定，函式會立即傳回。否則，它會等候。

dwReserved

保留參數;必須設定為零。

[in] nNumberOfBytesToLockLow

要鎖定之位元組範圍長度的低序 32 位。

[in] nNumberOfBytesToLockHigh

要鎖定之位元組範圍長度的高階32位。

[in, out] lpOverlapped

函式搭配鎖定要求使用的重疊結構指標。此結構是必要的，其中包含鎖定範圍開頭的檔案位移。您必須將 hEvent 成員初始化為有效的句柄或零。

傳回值

如果函式成功，則傳回值為非零 (TRUE) 。

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

備註

鎖定檔案的區域是用來使用此檔案句柄取得指定區域的共享或獨佔存取權。如果檔案句柄是由鎖定進程所建立的進程所繼承，子進程就不會被授與鎖定區域的存取權。如果鎖定程式第二次開啟檔案，則必須先解除鎖定區域，才能透過這個第二個句柄存取指定的區域。

鎖定檔案的一部分以進行獨佔存取會拒絕所有其他進程讀取和寫入檔案指定區域的存取權。鎖定超出目前檔案結尾位置的區域不是錯誤。

鎖定檔案的一部分以進行共用存取會拒絕對檔案指定區域的所有進程寫入存取權，包括第一次鎖定區域的進程。所有進程都可以讀取鎖定的區域。

鎖定檔案的區域不會防止從對應的檔案檢視讀取或寫入。

如果檔案句柄已針對異步 I/O 開啟，則 LockFileEx 函式會以異步方式運作，除非指定 LOCKFILE_FAIL_IMMEDIATELY 旗標。如果已擁有共用或獨佔鎖定的檔案範圍要求獨佔鎖定，函式會傳回錯誤 ERROR_IO_PENDING。系統會在授與鎖定之後，發出重迭結構中指定的事件訊號。若要判斷是否已授與鎖定，請使用 GetOverlappedResult 函式或其中一個等候函式。如需詳細資訊，請參閱同步和異步 I/O。

如果檔案句柄未針對異步 I/O 開啟，且鎖定無法使用，則除非指定 LOCKFILE_FAIL_IMMEDIATELY 旗標，否則此呼叫會等到授與鎖定或發生錯誤為止。

獨佔鎖定不能與檔案的現有鎖定區域重疊。共用鎖定可以重迭鎖定區域，前提是保留於該區域的鎖定是共享鎖定。如果兩個鎖定都使用相同的檔案句柄建立，共用鎖定可能會重迭獨佔鎖定。當共用鎖定重迭獨佔鎖定時，唯一可能的存取權是由鎖定的擁有者讀取。如果使用獨佔鎖定和共用鎖定鎖定相同的範圍，則需要兩個解除鎖定作業才能解除鎖定區域;第一個解除鎖定作業會解除鎖定獨佔鎖定，第二個解除鎖定作業會解除鎖定共用鎖定。

如果進程以鎖定的檔案部分終止，或關閉具有未完成鎖定的檔案，則操作系統會解除鎖定鎖定。不過，操作系統解除鎖定這些鎖定所需的時間取決於可用的系統資源。因此，建議您的程式在終止時明確解除鎖定其鎖定的所有檔案。如果未這麼做，如果操作系統尚未解除鎖定這些檔案，可能會拒絕這些檔案的存取。

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

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

規格需求

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