struktur READ_USN_JOURNAL_DATA_V0 (winioctl.h)
Berisi informasi yang menentukan sekumpulan nomor urutan pembaruan (USN) mengubah catatan jurnal untuk kembali ke proses panggilan. Ini digunakan oleh kode kontrol FSCTL_QUERY_USN_JOURNAL dan FSCTL_READ_USN_JOURNAL . Sebelum Windows 8 dan Windows Server 2012, struktur ini diberi nama READ_USN_JOURNAL_DATA. Gunakan nama tersebut untuk mengkompilasi dengan SDK dan kompilator yang lebih lama. Windows Server 2012 memperkenalkan READ_USN_JOURNAL_DATA_V1 untuk mendukung pengidentifikasi file 128-bit yang digunakan oleh ReFS.
Sintaks
typedef struct {
USN StartUsn;
DWORD ReasonMask;
DWORD ReturnOnlyOnClose;
DWORDLONG Timeout;
DWORDLONG BytesToWaitFor;
DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;
Anggota
StartUsn
USN untuk mulai membaca jurnal perubahan.
Untuk memulai operasi baca pada rekaman pertama dalam jurnal, atur anggota StartUsn ke nol. Karena USN terkandung dalam setiap catatan jurnal, buffer output memberi tahu di mana rekaman operasi baca benar-benar dimulai.
Untuk memulai operasi baca pada rekaman tertentu, atur StartUsn ke USN rekaman tersebut.
Jika USN bukan nol ditentukan yang kurang dari USN pertama dalam jurnal perubahan, maka kesalahan terjadi dan kode kesalahan ERROR_JOURNAL_ENTRY_DELETED dikembalikan. Kode ini dapat menunjukkan kasus di mana USN yang ditentukan valid pada satu waktu tetapi sejak itu telah dihapus.
Untuk informasi selengkapnya tentang menavigasi buffer jurnal perubahan yang dikembalikan di READ_USN_JOURNAL_DATA_V0, lihat Menjalankan Buffer Change Journal Records.
ReasonMask
Masker bendera, setiap bendera yang mencatat perubahan di mana file atau direktori memiliki rekaman dalam jurnal perubahan. Untuk dikembalikan dalam operasi FSCTL_READ_USN_JOURNAL , rekaman jurnal perubahan harus memiliki setidaknya salah satu bendera yang ditetapkan.
Daftar bendera yang valid adalah sebagai berikut. Bit yang tidak digunakan dicadangkan.
| Nilai | Makna |
|---|---|
|
Pengguna telah mengubah satu atau beberapa atribut file atau direktori (seperti atribut baca-saja, tersembunyi, sistem, arsip, atau jarang), atau satu atau beberapa stempel waktu. |
|
File atau direktori ditutup. |
|
Status pemadatan file atau direktori diubah dari atau menjadi terkompresi. |
|
File atau direktori ditambahkan ke. |
|
Data dalam file atau direktori ditimpa. |
|
File atau direktori terpotok. |
|
Pengguna membuat perubahan pada atribut file atau direktori yang diperluas. Atribut sistem file NTFS ini tidak dapat diakses oleh aplikasi berbasis Windows. |
|
File atau direktori dienkripsi atau didekripsi. |
|
File atau direktori dibuat untuk pertama kalinya. |
|
File atau direktori dihapus. |
|
Tautan keras sistem file NTFS ditambahkan ke atau dihapus dari file atau direktori. Tautan keras sistem file NTFS, mirip dengan tautan keras POSIX, adalah salah satu dari beberapa entri direktori yang melihat file atau direktori yang sama. |
|
Pengguna mengubah atribut FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Artinya, pengguna mengubah file atau direktori dari yang dapat diindeks konten menjadi konten yang tidak dapat, atau sebaliknya. (Pengindeksan konten memungkinkan pencarian data yang cepat dengan membangun database konten yang dipilih.) |
|
Satu atau beberapa aliran data bernama untuk file ditambahkan. |
|
Data dalam satu atau beberapa aliran data bernama untuk file ditimpa. |
|
Satu atau beberapa aliran data bernama untuk file terpotok. |
|
Pengidentifikasi objek file atau direktori diubah. |
|
Nama file atau direktori diganti namanya, dan nama file dalam struktur USN_RECORD_V2 atau USN_RECORD_V3 yang menyimpan catatan jurnal ini adalah nama baru. |
|
Nama file atau direktori diganti namanya, dan nama file dalam struktur USN_RECORD_V2 atau USN_RECORD_V3 yang memegang catatan jurnal ini adalah nama sebelumnya. |
|
Titik reparse yang terkandung dalam file atau direktori diubah, atau titik reparse ditambahkan ke atau dihapus dari file atau direktori. |
|
Perubahan dilakukan dalam izin akses ke file atau direktori. |
|
Aliran bernama ditambahkan ke atau dihapus dari file atau direktori, atau aliran bernama diganti namanya. |
ReturnOnlyOnClose
Nilai yang menentukan kapan harus mengembalikan rekaman jurnal perubahan.
Untuk menerima pemberitahuan ketika handel akhir untuk file atau direktori yang diubah ditutup, bukan pada saat perubahan terjadi, atur ReturnOnlyOnClose ke nilai bukan nol dan tentukan bendera USN_REASON_CLOSE di anggota ReasonMask .
Semua perubahan yang ditunjukkan oleh bendera ReasonMask akhirnya menghasilkan panggilan ke perangkat lunak jurnal perubahan ketika file ditutup. Jika panggilan DeviceIoControl Anda menunggu file ditutup, panggilan tersebut pada gilirannya akan memungkinkan panggilan DeviceIoControl Anda untuk kembali. Jika file atau direktori tidak ditutup sebelum kegagalan volume, kegagalan sistem operasi, atau pematian, panggilan pembersihan ke perangkat lunak jurnal perubahan terjadi saat volume dipasang di lain waktu. Panggilan terjadi bahkan jika ada sistem intervensi yang dimulai ulang.
Untuk menerima pemberitahuan pertama kali setiap perubahan dicatat, serta saat pembersihan, atur ReturnOnlyOnClose ke nol.
Apakah ReturnOnlyOnClose adalah nol atau bukan nol, rekaman yang dihasilkan pada log pembersihan dalam jurnal perubahan semua alasan untuk perubahan USN yang terjadi pada file atau direktori. Setiap kali operasi penutupan akhir terjadi untuk item, rekaman tutup USN ditulis ke jurnal perubahan, dan bendera ReasonMask untuk item semuanya diatur ulang.
Untuk file atau direktori yang tidak ada data pengguna (misalnya, folder yang dipasang), operasi penutupan akhir terjadi ketika fungsi CloseHandle dipanggil pada handel pengguna terakhir ke item.
Timeout
Nilai waktu habis, dalam detik, digunakan dengan anggota BytesToWaitFor untuk memberi tahu sistem operasi apa yang harus dilakukan jika operasi FSCTL_READ_USN_JOURNAL meminta lebih banyak data daripada yang ada di jurnal perubahan.
Jika Timeout adalah nol dan BytesToWaitFor bukan nol, dan panggilan operasi FSCTL_READ_USN_JOURNAL mencapai akhir jurnal perubahan tanpa menemukan data untuk dikembalikan, FSCTL_READ_USN_JOURNAL menunggu sampai BytesToWaitFor byte dari data yang tidak difilter telah ditambahkan ke jurnal perubahan lalu mengambil rekaman yang ditentukan.
Jika Timeout bukan nol dan BytesToWaitFor bukan nol, dan panggilan operasi FSCTL_READ_USN_JOURNAL mencapai akhir jurnal perubahan tanpa menemukan data untuk dikembalikan, FSCTL_READ_USN_JOURNAL menunggu detik Timeout lalu mencoba mengembalikan rekaman yang ditentukan. Setelah Timeout detik, FSCTL_READ_USN_JOURNAL mengambil rekaman apa pun yang tersedia dalam rentang yang ditentukan.
Dalam kedua kasus, setelah periode waktu habis setiap data baru yang ditambahkan ke jurnal perubahan diproses. Jika masih tidak ada rekaman yang dikembalikan dari set yang ditentukan, periode waktu habis akan diulang. Dalam mode ini, FSCTL_READ_USN_JOURNAL tetap luar biasa sampai setidaknya satu rekaman dikembalikan atau I/O dibatalkan.
Jika BytesToWaitFor adalah nol, maka Waktu habis diabaikan. Batas waktu juga diabaikan untuk handel yang dibuka secara asinkron.
BytesToWaitFor
Jumlah byte data yang tidak difilter yang ditambahkan ke jurnal perubahan. Gunakan nilai ini dengan Batas Waktu untuk memberi tahu sistem operasi apa yang harus dilakukan jika operasi FSCTL_READ_USN_JOURNAL meminta lebih banyak data daripada yang ada di jurnal perubahan.
Jika BytesToWaitFor adalah nol, maka Waktu habis diabaikan. Dalam hal ini, operasi FSCTL_READ_USN_JOURNAL selalu berhasil ditampilkan ketika akhir file jurnal perubahan ditemui. Ini juga mengambil USN yang harus digunakan untuk operasi FSCTL_READ_USN_JOURNAL berikutnya. Ketika USN berikutnya yang dikembalikan sama dengan StartUsn yang disediakan, tidak ada catatan yang tersedia. Proses panggilan tidak boleh segera menggunakan FSCTL_READ_USN_JOURNAL lagi.
Karena jumlah data yang dikembalikan tidak dapat diprediksi ketika BytesToWaitFor adalah nol, Anda berisiko meluapkan buffer output. Untuk mengurangi risiko ini, tentukan nilai BytesToWaitFor nonzero dalam operasi FSCTL_READ_USN_JOURNAL berulang hingga semua rekaman dalam jurnal perubahan habis. Kemudian tentukan nol untuk menunggu rekaman baru.
Atau, gunakan parameter lpBytesReturned dari DeviceIoControl dalam panggilan operasi FSCTL_READ_USN_JOURNAL untuk menentukan jumlah data yang tersedia, merealokasi buffer output (dengan ruang untuk cadangan rekaman baru), dan memanggil DeviceIoControl lagi.
UsnJournalID
Pengidentifikasi untuk instans jurnal yang saat ini untuk volume.
Sistem file NTFS dapat melewatkan menempatkan peristiwa dalam jurnal perubahan jika jurnal perubahan dihentikan dan dimulai ulang atau dihapus dan dibuat ulang. Jika salah satu peristiwa ini terjadi, sistem file NTFS memberi jurnal pengidentifikasi baru. Jika pengidentifikasi jurnal tidak setuju dengan pengidentifikasi jurnal saat ini, panggilan ke DeviceIoControl gagal dan mengembalikan kode kesalahan yang sesuai. Untuk mengambil pengidentifikasi jurnal baru, panggil DeviceIoControl dengan operasi FSCTL_QUERY_USN_JOURNAL .
Persyaratan
| Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Header | winioctl.h (termasuk Windows.h) |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk