Fungsi ReadDirectoryChangesW (winbase.h)
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.
[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.
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 |