Fungsi FindFirstChangeNotificationA (fileapi.h)

Membuat handel pemberitahuan perubahan dan menyiapkan kondisi filter pemberitahuan perubahan awal. Tunggu pada handel pemberitahuan berhasil saat perubahan yang cocok dengan kondisi filter terjadi di direktori atau subtree yang ditentukan. Fungsi tidak melaporkan perubahan pada direktori yang ditentukan itu sendiri.

Fungsi ini tidak menunjukkan perubahan yang memenuhi kondisi tunggu. Untuk mengambil informasi tentang perubahan tertentu sebagai bagian dari pemberitahuan, gunakan
fungsi ReadDirectoryChangesW.

Sintaksis

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

Parameter

[in] lpPathName

Jalur lengkap direktori yang akan diawasi.

Ini tidak boleh berupa jalur relatif atau string kosong.

Secara default, nama dibatasi untuk MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan awal "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Penamaan File, Jalur, dan Namespace.

Ujung

Dimulai dengan Windows 10, Versi 1607, Anda dapat memilih untuk menghapus batasan MAX_PATH tanpa prepending "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" Penamaan File, Jalur, dan Namespace untuk detailnya.

[in] bWatchSubtree

Jika parameter ini TRUE, fungsi memantau pohon direktori yang berakar pada direktori yang ditentukan; jika FALSE, itu hanya memantau direktori yang ditentukan.

[in] dwNotifyFilter

Kondisi filter yang memenuhi pemberitahuan perubahan menunggu. Parameter ini bisa berupa satu atau beberapa nilai berikut.

Nilai	Arti
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Setiap perubahan nama file di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan kembali. Perubahan termasuk mengganti nama, membuat, atau menghapus nama file.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Setiap perubahan nama direktori di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan kembali. Perubahan termasuk membuat atau menghapus direktori.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Setiap perubahan atribut dalam direktori atau subtree yang ditonton menyebabkan operasi tunggu pemberitahuan perubahan kembali.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Setiap perubahan ukuran file dalam direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan kembali. Sistem operasi mendeteksi perubahan ukuran file hanya ketika file ditulis ke disk. Untuk sistem operasi yang menggunakan penembolokan ekstensif, deteksi hanya terjadi ketika cache cukup dibersihkan.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Setiap perubahan pada waktu tulis file terakhir di direktori atau subtree yang ditonton menyebabkan operasi tunggu pemberitahuan perubahan kembali. Sistem operasi mendeteksi perubahan pada write-time terakhir hanya ketika file ditulis ke disk. Untuk sistem operasi yang menggunakan penembolokan ekstensif, deteksi hanya terjadi ketika cache cukup dibersihkan.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Setiap perubahan pendeskripsi keamanan di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan kembali.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian adalah handel untuk menemukan objek pemberitahuan perubahan.

Jika fungsi gagal, nilai yang dikembalikan adalah INVALID_HANDLE_VALUE. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

Fungsi tunggu dapat memantau direktori atau subtree yang ditentukan dengan menggunakan handel yang dikembalikan oleh fungsi FindFirstChangeNotification . Penantian terpenuhi ketika salah satu kondisi filter terjadi di direktori atau subtree yang dipantau.

Setelah penantian terpenuhi, aplikasi dapat merespons kondisi ini dan terus memantau direktori dengan memanggil fungsi FindNextChangeNotification dan fungsi tunggu yang sesuai. Ketika handel tidak lagi diperlukan, handel dapat ditutup dengan menggunakan fungsi FindCloseChangeNotification.

Pemberitahuan mungkin tidak dikembalikan saat memanggil FindFirstChangeNotification untuk sistem file jarak jauh.

Perilaku tautan simbolis—Jika jalur menunjuk ke tautan simbolis, handel pemberitahuan dibuat untuk target.

Jika aplikasi telah mendaftar untuk menerima pemberitahuan perubahan untuk direktori yang berisi tautan simbolis, aplikasi hanya diberi tahu ketika tautan simbolis telah diubah, bukan file target.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
Failover Transparan (TFO) SMB 3.0	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Lihat komentar
Sistem File Tangguh (ReFS)	Ya

 

Aplikasi mungkin mengalami positif palsu pada CsvFs jeda/lanjutkan.

Contoh

Misalnya, lihat Mendapatkan Direktori Change_Notifications.

Nota

Header fileapi.h mendefinisikan FindFirstChangeNotification sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosektor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Platform Target	Windows
Header	fileapi.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

Directory Management Functions

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW