共用方式為

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 通訊協定 是的
SMB 3.0 透明故障轉移 （TFO） 是的
具有向外延展檔案共用的SMB 3.0（SO） 是的
叢集共用磁碟區檔案系統 （CsvFS） 請參閱備註
復原檔案系統 （ReFS） 是的
 

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

例子

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

注意

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

要求

要求 價值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 fileapi.h （包括 Windows.h）
連結庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

Directory Management Functions

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW