Fungsi ReadDirectoryChangesExW (winbase.h)

Artikel
08/27/2023

Mengambil informasi yang menjelaskan perubahan dalam direktori yang ditentukan, yang dapat menyertakan informasi yang diperluas jika jenis informasi tersebut ditentukan. Fungsi tidak melaporkan perubahan pada direktori yang ditentukan itu sendiri.

Untuk melacak perubahan pada volume, lihat mengubah jurnal.

Sintaks

BOOL ReadDirectoryChangesExW(
  [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,
  [in]                READ_DIRECTORY_NOTIFY_INFORMATION_CLASS ReadDirectoryNotifyInformationClass
);

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 ReadDirectoryChangesExW harus mengembalikan hasil baca. Struktur buffer ini ditentukan oleh struktur FILE_NOTIFY_EXTENDED_INFORMATION jika nilai parameter ReadDirectoryNotifyInformationClass adalah ReadDirectoryNotifyExtendedInformation, atau oleh struktur FILE_NOTIFY_INFORMATION jika ReadDirectoryNotifyInformationClass adalah ReadDirectoryNotifyInformation.

Buffer ini diisi 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 tempat parameter lpBuffer menunjuk, 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 kembali. 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 kembali. Perubahan termasuk membuat atau menghapus direktori.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Setiap perubahan atribut dalam direktori atau subtree yang diawasi 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 memerah.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Setiap perubahan pada waktu penulisan file terakhir 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 memerah.
FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020	Setiap perubahan pada waktu akses terakhir file di direktori atau subtree yang diawasi menyebabkan operasi tunggu pemberitahuan perubahan kembali.
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 kembali.

[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 NULL. Anggota Offset dan OffsetHigh dari struktur ini tidak digunakan.

[in, optional] lpCompletionRoutine

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

[in] ReadDirectoryNotifyInformationClass

Jenis informasi yang harus ditulis ReadDirectoryChangesExW ke buffer tempat parameter lpBuffer menunjuk. Tentukan ReadDirectoryNotifyInformation untuk menunjukkan bahwa informasi harus terdiri dari struktur FILE_NOTIFY_INFORMATION , atau ReadDirectoryNotifyExtendedInformation untuk menunjukkan bahwa informasi harus terdiri dari struktur FILE_NOTIFY_EXTENDED_INFORMATION .

Mengembalikan nilai

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 ReadDirectoryChangesExW dapat diselesaikan secara sinkron atau asinkron. Untuk menentukan penyelesaian asinkron, buka direktori dengan CreateFile seperti yang ditunjukkan di atas, tetapi juga tentukan atribut FILE_FLAG_OVERLAPPED dalam parameter dwFlagsAndAttributes . Kemudian tentukan struktur YANG TUMPANG TINDIH saat Anda memanggil ReadDirectoryChangesExW.

Ketika Anda pertama kali memanggil ReadDirectoryChangesExW, sistem mengalokasikan buffer untuk menyimpan informasi perubahan. Buffer ini dikaitkan dengan handel direktori hingga 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, ReadDirectoryChangesExW akan tetap mengembalikan true, tetapi seluruh konten buffer dibuang dan parameter lpBytesReturned akan menjadi nol, yang menunjukkan bahwa buffer Anda terlalu kecil untuk menahan semua perubahan yang terjadi.

Setelah penyelesaian sinkron berhasil, parameter lpBuffer adalah buffer berformat 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 direktori menangani 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 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.

ReadDirectoryChangesExW 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.

ReadDirectoryChangesExW gagal dengan ERROR_NOACCESS ketika buffer tidak diselaraskan pada batas DWORD .

ReadDirectoryChangesExW gagal dengan ERROR_NOTIFY_ENUM_DIR ketika sistem tidak dapat merekam semua perubahan ke 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.

ReadDirectoryChangesExW saat ini hanya didukung untuk sistem file NTFS.

Operasi yang Ditransaksikan

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10, versi 1709 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2019 [hanya aplikasi desktop]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll