readDirectoryChangesExW 函式 (winbase.h)
擷取描述指定目錄內變更的資訊，如果指定了該資訊類型，則可以包含擴充資訊。 函式不會報告指定目錄本身的變更。
若要追蹤磁碟區上的變更，請參閱 變更日誌。
語法
BOOL ReadDirectoryChangesExW(
[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] READ_DIRECTORY_NOTIFY_INFORMATION_CLASS ReadDirectoryNotifyInformationClass
);
參數
[in] hDirectory
要監視之目錄的句柄。 此目錄必須以FILE_LIST_DIRECTORY訪問許可權開啟，或是包含FILE_LIST_DIRECTORY訪問許可權的GENERIC_READ等訪問許可權。
[out] lpBuffer
DWORD 對齊格式緩衝區的指標，ReadDirectoryChangesExW 應該會傳回讀取結果。 如果 ReadDirectoryNotifyInformationClass 參數的值是 ReadDirectoryNotifyExtendedInformation，則此緩衝區的結構是由 FILE_NOTIFY_EXTENDED_INFORMATION 結構所定義，如果 ReadDirectoryNotifyInformationClass 為 ReadDirectoryNotifyInformation，則為 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。
[in] ReadDirectoryNotifyInformationClass
ReadDirectoryChangesExW 應該寫入至 lpBuffer 參數所指向之緩衝區的信息類型。 指定 ReadDirectoryNotifyInformation 以指出資訊應包含 FILE_NOTIFY_INFORMATION 結構，或 ReadDirectoryNotifyExtendedInformation ，以指出資訊應該包含 FILE_NOTIFY_EXTENDED_INFORMATION 結構。
傳回值
如果函式成功，則傳回非零的值。 針對同步呼叫，這表示作業成功。 針對異步呼叫，這表示作業已成功排入佇列。
如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
如果網路重新導向器或目標檔系統不支援此作業，則函式會失敗並 ERROR_INVALID_FUNCTION。
備註
若要取得目錄的句柄，請使用 CreateFile 函式搭配 FILE_FLAG_BACKUP_SEMANTICS 旗標。
ReadDirectoryChangesExW 的呼叫可以同步或異步完成。 若要指定異步完成，請使用上述的 CreateFile 開啟目錄，但另外在 dwFlagsAndAttributes 參數中指定 FILE_FLAG_OVERLAPPED 屬性。 然後在呼叫 ReadDirectoryChangesExW 時指定 OVERLAPPED 結構。
當您第一次呼叫 ReadDirectoryChangesExW 時，系統會配置緩衝區來儲存變更資訊。 這個緩衝區會與目錄句柄相關聯，直到關閉為止，而且其大小不會在其存留期間變更。 呼叫此函式時發生的目錄變更會新增至緩衝區，然後使用下一次呼叫傳回。 如果緩衝區溢位， ReadDirectoryChangesExW 仍然會傳回 true，但會捨棄緩衝區的整個內容，而 lpBytesReturned 參數會是零，這表示您的緩衝區太小而無法保存發生的所有變更。
成功完成同步時， lpBuffer 參數是格式化的緩衝區，而寫入緩衝區的位元元組數目可在 lpBytesReturned 中使用。 如果傳輸的位元組數目為零，則緩衝區太大，系統無法配置或太小，無法提供有關目錄或子樹中發生之所有變更的詳細資訊。 在此情況下，您應該藉由列舉目錄或子樹來計算變更。
針對異步完成，您可以透過下列三種方式之一接收通知：
- 使用 GetOverlappedResult 函 式。 若要透過 GetOverlappedResult 接收通知，請勿在 lpCompletionRoutine 參數中指定完成例程。 請務必將 OVERLAPPED 結構的 hEvent 成員設定為唯一事件。
- 使用 GetQueuedCompletionStatus 函 式。 若要透過 GetQueuedCompletionStatus 接收通知，請勿在 lpCompletionRoutine 中指定完成例程。 呼叫 CreateIoCompletionPort 函式，將目錄句柄 hDirectory 與完成埠產生關聯。
- 使用完成例程。 若要透過完成例程接收通知，請勿將目錄與完成埠產生關聯。 在 lpCompletionRoutine 中指定完成例程。 每當線程處於可警示的等候狀態時，就會呼叫此例程。 系統不會使用 OVERLAPPED 結構的 hEvent 成員，因此您可以自行使用它。
當緩衝區長度大於 64 KB 且應用程式透過網路監視目錄時，ReadDirectoryChangesExW 會失敗並ERROR_INVALID_PARAMETER。 這是因為基礎檔案共享通訊協定的封包大小限制。
當緩衝區未對齊 DWORD 界限時，ReadDirectoryChangesExW 會失敗，且ERROR_NOACCESS。
當系統無法記錄目錄的所有變更時，ReadDirectoryChangesExW 會因為ERROR_NOTIFY_ENUM_DIR而失敗。 在此情況下，您應該藉由列舉目錄或子樹來計算變更。
如果您使用簡短名稱開啟檔案，您可以接收簡短名稱的變更通知。
ReadDirectoryChangesExW 目前僅支援NTFS文件系統。
交易作業
如果有系結至目錄句柄的交易，則通知會遵循適當的交易隔離規則。規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 10 1709 版 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2019 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | winbase.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |