Fungsi ReadDirectoryChangesW (winbase.h)

Artikel
08/27/2023

Mengambil informasi yang menjelaskan perubahan dalam direktori yang ditentukan. Fungsi tidak melaporkan perubahan pada direktori yang ditentukan itu sendiri.

Untuk melacak perubahan pada volume, lihat mengubah jurnal.

Sintaks

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
);

Parameter

[in] hDirectory

Handel ke direktori yang akan dipantau. Direktori ini harus dibuka dengan hak akses FILE_LIST_DIRECTORY , atau hak akses seperti GENERIC_READ yang menyertakan hak akses FILE_LIST_DIRECTORY .

[out] lpBuffer

Penunjuk ke buffer berformat yang diratakan DWORD di mana hasil baca akan dikembalikan. Struktur buffer ini didefinisikan oleh struktur FILE_NOTIFY_INFORMATION . Buffer ini diisi baik secara sinkron atau asinkron, tergantung pada bagaimana direktori dibuka dan nilai apa yang diberikan ke parameter lpOverlapped . Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in] nBufferLength

Ukuran buffer yang diacu oleh parameter lpBuffer , dalam byte.

[in] bWatchSubtree

Jika parameter ini TRUE, fungsi memantau pohon direktori yang berakar pada direktori yang ditentukan. Jika parameter ini FALSE, fungsi hanya memantau direktori yang ditentukan oleh parameter hDirectory .

[in] dwNotifyFilter

Kriteria filter yang diperiksa fungsi untuk menentukan apakah operasi tunggu telah selesai. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Setiap perubahan nama file di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan dikembalikan. Perubahan termasuk mengganti nama, membuat, atau menghapus file.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Setiap perubahan nama direktori di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan dikembalikan. Perubahan termasuk membuat atau menghapus direktori.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Setiap perubahan atribut di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan kembali.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Setiap perubahan ukuran file di 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 penulisan terakhir file di direktori atau subtree yang diawasi 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_LAST_ACCESS 0x00000020	Setiap perubahan pada waktu akses terakhir file di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan dikembalikan.
FILE_NOTIFY_CHANGE_CREATION 0x00000040	Setiap perubahan pada waktu pembuatan file di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan kembali.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Setiap perubahan pendeskripsi keamanan di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan dikembalikan.

[out, optional] lpBytesReturned

Untuk panggilan sinkron, parameter ini menerima jumlah byte yang ditransfer ke parameter lpBuffer . Untuk panggilan asinkron, parameter ini tidak terdefinisi. Anda harus menggunakan teknik pemberitahuan asinkron untuk mengambil jumlah byte yang ditransfer.

[in, out, optional] lpOverlapped

Penunjuk ke struktur TUMPANG TINDIH yang memasok data yang akan digunakan selama operasi asinkron. Jika tidak, nilai ini adalah NULL. Anggota Offset dan OffsetHigh dari struktur ini tidak digunakan.

[in, optional] lpCompletionRoutine

Penunjuk ke rutinitas penyelesaian yang akan dipanggil ketika operasi telah selesai atau dibatalkan dan utas panggilan berada dalam status tunggu yang dapat diingat. Untuk informasi selengkapnya tentang rutinitas penyelesaian ini, lihat FileIOCompletionRoutine.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol. Untuk panggilan sinkron, ini berarti bahwa operasi berhasil. Untuk panggilan asinkron, ini menunjukkan bahwa operasi berhasil diantrekan.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Jika pengalih jaringan atau sistem file target tidak mendukung operasi ini, fungsi gagal dengan ERROR_INVALID_FUNCTION.

Keterangan

Untuk mendapatkan handel ke direktori, gunakan fungsi CreateFile dengan bendera FILE_FLAG_BACKUP_SEMANTICS .

Panggilan ke ReadDirectoryChangesW dapat diselesaikan secara sinkron atau asinkron. Untuk menentukan penyelesaian asinkron, buka direktori dengan CreateFile seperti yang ditunjukkan di atas, tetapi tentukan atribut FILE_FLAG_OVERLAPPED dalam parameter dwFlagsAndAttributes . Kemudian tentukan struktur YANG TUMPANG TINDIH saat Anda memanggil ReadDirectoryChangesW.

Ketika Anda pertama kali memanggil ReadDirectoryChangesW, sistem mengalokasikan buffer untuk menyimpan informasi perubahan. Buffer ini dikaitkan dengan handel direktori sampai ditutup dan ukurannya tidak berubah selama masa pakainya. Perubahan direktori yang terjadi antara panggilan ke fungsi ini ditambahkan ke buffer lalu dikembalikan dengan panggilan berikutnya. Jika buffer meluap, ReadDirectoryChangesW masih akan mengembalikan true, tetapi seluruh konten buffer dibuang dan parameter lpBytesReturned akan menjadi nol, yang menunjukkan bahwa buffer Anda terlalu kecil untuk menyimpan semua perubahan yang terjadi.

Setelah penyelesaian sinkron berhasil, parameter lpBuffer adalah buffer yang diformat dan jumlah byte yang ditulis ke buffer tersedia di lpBytesReturned. Jika jumlah byte yang ditransfer adalah nol, buffer terlalu besar bagi sistem untuk mengalokasikan atau terlalu kecil untuk memberikan informasi terperinci tentang semua perubahan yang terjadi di direktori atau subtree. Dalam hal ini, Anda harus menghitung perubahan dengan menghitung direktori atau subtree.

Untuk penyelesaian asinkron, Anda dapat menerima pemberitahuan dengan salah satu dari tiga cara:

Menggunakan fungsi GetOverlappedResult . Untuk menerima pemberitahuan melalui GetOverlappedResult, jangan tentukan rutinitas penyelesaian dalam parameter lpCompletionRoutine . Pastikan untuk mengatur anggota hEvent dari struktur TUMPANG TINDIH ke peristiwa unik.
Menggunakan fungsi GetQueuedCompletionStatus . Untuk menerima pemberitahuan melalui GetQueuedCompletionStatus, jangan tentukan rutinitas penyelesaian di lpCompletionRoutine. Kaitkan handel direktori hDirectory dengan port penyelesaian dengan memanggil fungsi CreateIoCompletionPort .
Menggunakan rutinitas penyelesaian. Untuk menerima pemberitahuan melalui rutinitas penyelesaian, jangan kaitkan direktori dengan port penyelesaian. Tentukan rutinitas penyelesaian dalam lpCompletionRoutine. Rutinitas ini dipanggil setiap kali operasi telah selesai atau dibatalkan saat utas dalam status tunggu yang dapat diperingatkan. Anggota hEvent dari struktur TUMPANG TINDIH tidak digunakan oleh sistem, sehingga Anda dapat menggunakannya sendiri.

Untuk informasi selengkapnya, lihat I/O Sinkron dan Asinkron.

ReadDirectoryChangesW gagal dengan ERROR_INVALID_PARAMETER ketika panjang buffer lebih besar dari 64 KB dan aplikasi memantau direktori melalui jaringan. Hal ini disebabkan oleh keterbatasan ukuran paket dengan protokol berbagi file yang mendasar.

ReadDirectoryChangesW gagal dengan ERROR_NOACCESS ketika buffer tidak selaras pada batas DWORD .

ReadDirectoryChangesW gagal dengan ERROR_NOTIFY_ENUM_DIR ketika sistem tidak dapat merekam semua perubahan pada direktori. Dalam hal ini, Anda harus menghitung perubahan dengan menghitung direktori atau subtree.

Jika Anda membuka file menggunakan nama pendek, Anda dapat menerima pemberitahuan perubahan untuk nama pendek.

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

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

Operasi yang Ditransaksikan

Jika ada transaksi yang terikat ke handel direktori, maka pemberitahuan mengikuti aturan isolasi transaksi yang sesuai.

Persyaratan


Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll