FindFirstChangeNotificationA 函式 (fileapi.h)

  • 發行項

建立變更通知控制碼，並設定初始變更通知篩選準則。 當符合篩選準則的變更出現在指定的目錄或子樹中時，通知控制碼的等候就會成功。 函式不會報告指定目錄本身的變更。

此函式不會指出滿足等候條件的變更。 若要擷取通知中特定變更的相關資訊，請使用
ReadDirectoryChangesW 函式。

語法

HANDLE FindFirstChangeNotificationA(
  [in] LPCSTR lpPathName,
  [in] BOOL   bWatchSubtree,
  [in] DWORD  dwNotifyFilter
);

參數

[in] lpPathName

要監看之目錄的完整路徑。

這不可以是相對路徑或空字串。

根據預設，名稱限制為MAX_PATH個字元。 若要將此限制延伸至 32，767 寬字元，請在路徑前面加上 「\\？\」。 如需詳細資訊，請參閱命名檔案、路徑與命名空間。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 「\\？\」。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間 的一節。

[in] bWatchSubtree

如果此參數為 TRUE，函式會監視位於指定目錄的根目錄樹狀目錄;如果為 FALSE，則只會監視指定的目錄。

[in] dwNotifyFilter

滿足變更通知等候的篩選準則。 此參數可以是下列一或多個值。

值 意義
FILE_NOTIFY_CHANGE_FILE_NAME
0x00000001
 監看目錄或樹狀子目錄中的任何檔案名稱變更都會造成變更告知等待作業傳回。 變更包括重新命名、建立或刪除檔案名稱。
FILE_NOTIFY_CHANGE_DIR_NAME
0x00000002
 監看目錄或子樹中的任何目錄名稱變更都會傳回變更通知等候作業。 變更包括建立或刪除目錄。
FILE_NOTIFY_CHANGE_ATTRIBUTES
0x00000004
 監看目錄或樹狀子目錄中的任何屬性變更都會造成變更告知等待作業傳回。
FILE_NOTIFY_CHANGE_SIZE
0x00000008
 監看目錄或樹狀子目錄中的任何檔案大小變更都會造成變更告知等待作業傳回。 作業系統只會在檔案寫入磁碟時偵測檔案大小的變更。 如果是使用大量快取的作業系統，則只會在快取有效排清時進行偵測。
FILE_NOTIFY_CHANGE_LAST_WRITE
0x00000010
 監看目錄或樹狀子目錄中檔案上次寫入時間的任何變更都會造成變更告知等待作業傳回。 作業系統只會在檔案寫入磁碟時偵測上次寫入時間的變更。 如果是使用大量快取的作業系統，則只會在快取有效排清時進行偵測。
FILE_NOTIFY_CHANGE_SECURITY
0x00000100
 監看目錄或子樹中的任何安全性描述項變更都會導致變更通知等候作業傳回。

傳回值

如果函式成功，則傳回值是尋找變更通知物件的控制碼。

如果函式失敗，傳回值會 INVALID_HANDLE_VALUE。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

等候函式可以使用FindFirstChangeNotification函式所傳回的控制碼來監視指定的目錄或子樹。 當其中一個篩選準則出現在受監視的目錄或子樹中時，就會滿足等候。

滿足等候之後，應用程式可以回應此條件，並呼叫 FindNextChangeNotification 函式和適當的等候函式，以繼續監視目錄。 不再需要控制碼時，可以使用 FindCloseChangeNotification 函式加以關閉。

呼叫 遠端檔案系統的 FindFirstChangeNotification 時，可能不會傳回通知。

符號連結行為—如果路徑指向符號連結，則會為目標建立通知控制碼。

如果應用程式已註冊以接收包含符號連結之目錄的變更通知，則只有在符號連結已變更時，應用程式才會收到通知，而不是目標檔案。

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

技術 支援
伺服器訊息區 (SMB) 3.0 通訊協定 Yes
SMB 3.0 透明容錯移轉 (TFO) Yes
具有向外延展檔案共用的 SMB 3.0 (SO) Yes
叢集共用磁片區檔案系統 (CsvFS) 請參閱備註
彈性檔案系統 (ReFS) Yes
 

應用程式可能會在 CsvFs 暫停/繼續時遇到誤判。

範例

如需範例，請參閱 取得目錄Change_Notifications。

注意

fileapi.h 標頭會將 FindFirstChangeNotification 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

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

另請參閱

目錄管理功能

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW