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 中，下列技術支援此函式。

交易作業

規格需求

另請參閱

CreateFile

CreateIoCompletionPort

目錄管理功能

FILE_NOTIFY_INFORMATION

FileIOCompletionRoutine

GetOverlappedResult

GetQueuedCompletionStatus

重疊