readDirectoryChangesW 函式 (winbase.h)
擷取描述指定目錄內變更的資訊。 函式不會報告指定目錄本身的變更。
若要追蹤磁片區上的變更，請參閱 變更日誌。
語法
BOOL ReadDirectoryChangesW(
[in] HANDLE hDirectory,
[out] LPVOID lpBuffer,
[in] DWORD nBufferLength,
[in] BOOL bWatchSubtree,
[in] DWORD dwNotifyFilter,
[out, optional] LPDWORD lpBytesReturned,
[in, out, optional] LPOVERLAPPED lpOverlapped,
[in, optional] LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
參數
[in] hDirectory
要監視之目錄的控制碼。 此目錄必須以FILE_LIST_DIRECTORY存取權限開啟，或是包含FILE_LIST_DIRECTORY存取權限的GENERIC_READ等存取權限。
[out] lpBuffer
要傳回讀取結果的 DWORD對齊格式化緩衝區指標。 這個緩衝區的結構是由 FILE_NOTIFY_INFORMATION 結構所定義。 視目錄的開啟方式和 lpOverlapped 參數的值而定，此緩衝區會以同步或非同步方式填入。 如需詳細資訊，請參閱＜備註＞一節。
[in] nBufferLength
lpBuffer參數所指向的緩衝區大小，以位元組為單位。
[in] bWatchSubtree
如果此參數為 TRUE，函式會監視位於指定目錄的根目錄樹狀目錄。 如果此參數為 FALSE，函式只會監視 hDirectory 參數所指定的目錄。
[in] dwNotifyFilter
函式檢查的篩選準則，以判斷等候作業是否已完成。 此參數可以是下列一或多個值。
[out, optional] lpBytesReturned
針對同步呼叫，此參數會接收傳送至 lpBuffer 參數的位元組數目。 針對非同步呼叫，這個參數是未定義的。 您必須使用非同步通知技術來擷取傳輸的位元組數目。
[in, out, optional] lpOverlapped
重迭結構的指標，提供非同步作業期間要使用的資料。 否則，此值為 Null。 不會使用此結構的 Offset 和 OffsetHigh 成員。
[in, optional] lpCompletionRoutine
當作業完成或取消且呼叫執行緒處於可警示等候狀態時，要呼叫的完成常式指標。 如需此完成常式的詳細資訊，請參閱 FileIOCompletionRoutine。
傳回值
如果函式成功，則傳回非零的值。 針對同步呼叫，這表示作業成功。 針對非同步呼叫，這表示作業已成功排入佇列。
如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
如果網路重新導向器或目的檔案系統不支援此作業，則函式會失敗並 ERROR_INVALID_FUNCTION。
備註
若要取得目錄的控制碼，請使用 CreateFile 函式搭配 FILE_FLAG_BACKUP_SEMANTICS 旗標。
ReadDirectoryChangesW的呼叫可以同步或非同步完成。 若要指定非同步完成，請使用上述的 CreateFile開啟目錄，但另外在dwFlagsAndAttributes參數中指定FILE_FLAG_OVERLAPPED屬性。 然後在呼叫ReadDirectoryChangesW時指定OVERLAPPED結構。
當您第一次呼叫 ReadDirectoryChangesW時，系統會配置緩衝區來儲存變更資訊。 這個緩衝區會與目錄控制碼相關聯，直到關閉為止，而且其大小不會在其存留期間變更。 呼叫此函式時發生的目錄變更會新增至緩衝區，然後使用下一次呼叫傳回。 如果緩衝區溢位， ReadDirectoryChangesW 仍然會傳回 true，但會捨棄緩衝區的整個內容，而 lpBytesReturned 參數會是零，這表示您的緩衝區太小而無法保存發生的所有變更。
成功完成同步時， lpBuffer 參數是格式化的緩衝區，而寫入緩衝區的位元組數目可在 lpBytesReturned中使用。 如果傳輸的位元組數目為零，則緩衝區太大，系統無法配置或太小，無法提供有關目錄或子樹中發生之所有變更的詳細資訊。 在此情況下，您應該藉由列舉目錄或子樹來計算變更。
針對非同步完成，您可以透過下列三種方式之一接收通知：
- 使用 GetOverlappedResult 函 式。 若要透過 GetOverlappedResult接收通知，請勿在 lpCompletionRoutine 參數中指定完成常式。 請務必將OVERLAPPED結構的hEvent成員設定為唯一事件。
- 使用 GetQueuedCompletionStatus 函 式。 若要透過 GetQueuedCompletionStatus接收通知，請勿在 lpCompletionRoutine中指定完成常式。 呼叫CreateIoCompletionPort函式，將目錄控制碼hDirectory與完成埠產生關聯。
- 使用完成常式。 若要透過完成常式接收通知，請勿將目錄與完成埠產生關聯。 在 lpCompletionRoutine中指定完成常式。 每當執行緒處於可警示的等候狀態時，就會呼叫此常式。 系統不會使用OVERLAPPED結構的hEvent成員，因此您可以自行使用它。
當緩衝區長度大於 64 KB 且應用程式透過網路監視目錄時，ReadDirectoryChangesW會失敗並ERROR_INVALID_PARAMETER。 這是因為基礎檔案共用通訊協定的封包大小限制。
當緩衝區未對齊DWORD界限時，ReadDirectoryChangesW會因為ERROR_NOACCESS而失敗。
當系統無法記錄目錄的所有變更時，ReadDirectoryChangesW會因為ERROR_NOTIFY_ENUM_DIR而失敗。 在此情況下，您應該藉由列舉目錄或子樹來計算變更。
如果您使用簡短名稱開啟檔案，您可以接收簡短名稱的變更通知。
在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。
| 技術 | 支援 |
|---|---|
| 伺服器訊息區 (SMB) 3.0 通訊協定 | Yes |
| SMB 3.0 透明容錯移轉 (TFO) | Yes |
| 具有向外延展檔案共用的 SMB 3.0 (SO) | Yes |
| 叢集共用磁片區檔案系統 (CsvFS) | Yes |
| 彈性檔案系統 (ReFS) | 是 |
交易作業
如果有系結至目錄控制碼的交易，則通知會遵循適當的交易隔離規則。規格需求
| 最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | winbase.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |