struktur USN_RECORD_V4 (winioctl.h)

Artikel
03/08/2023

Berisi informasi untuk catatan nomor urutan pembaruan (USN) versi 4.0. Rekaman versi 2.0 dan 3.0 ditentukan oleh struktur USN_RECORD_V2 (juga disebut USN_RECORD) dan USN_RECORD_V3 .

Sintaks

typedef struct {
  USN_RECORD_COMMON_HEADER Header;
  FILE_ID_128              FileReferenceNumber;
  FILE_ID_128              ParentFileReferenceNumber;
  USN                      Usn;
  DWORD                    Reason;
  DWORD                    SourceInfo;
  DWORD                    RemainingExtents;
  WORD                     NumberOfExtents;
  WORD                     ExtentSize;
  USN_RECORD_EXTENT        Extents[1];
} USN_RECORD_V4, *PUSN_RECORD_V4;

Anggota

Header

Struktur USN_RECORD_COMMON_HEADER yang menjelaskan panjang rekaman, versi utama, dan versi minor untuk rekaman.

FileReferenceNumber

Nomor ordinal 128-bit dari file atau direktori yang catatan catatan ini berubah.

Nilai ini adalah nilai yang ditetapkan secara acak yang mengaitkan rekaman jurnal dengan file.

ParentFileReferenceNumber

Nomor ordinal 128-bit direktori tempat file atau direktori yang terkait dengan rekaman ini berada.

Nilai ini adalah nilai yang ditetapkan secara semena-mena yang mengaitkan rekaman jurnal dengan direktori induk.

Usn

USN dari catatan ini.

Reason

Bendera yang mengidentifikasi alasan perubahan yang telah terakumulasi dalam rekaman file atau jurnal direktori ini sejak file atau direktori dibuka.

Saat file atau direktori ditutup, rekaman USN akhir dihasilkan dengan kumpulan bendera USN_REASON_CLOSE . Perubahan berikutnya (misalnya, setelah operasi atau penghapusan terbuka berikutnya) memulai rekaman baru dengan serangkaian bendera alasan baru.

Operasi ganti nama atau pemindahan menghasilkan dua rekaman USN, satu yang merekam direktori induk lama untuk item tersebut, dan yang merekam induk baru.

Tabel berikut mengidentifikasi kemungkinan bendera.

Catatan Bit yang tidak digunakan dicadangkan.

Nilai	Makna
USN_REASON_BASIC_INFO_CHANGE 0x00008000	Pengguna telah mengubah satu atau beberapa atribut file atau direktori (misalnya, atribut baca-saja, tersembunyi, sistem, arsip, atau jarang), atau satu atau beberapa stempel waktu.
USN_REASON_CLOSE 0x80000000	File atau direktori ditutup.
USN_REASON_COMPRESSION_CHANGE 0x00020000	Status pemadatan file atau direktori diubah dari atau menjadi terkompresi.
USN_REASON_DATA_EXTEND 0x00000002	File atau direktori diperluas (ditambahkan ke).
USN_REASON_DATA_OVERWRITE 0x00000001	Data dalam file atau direktori ditimpa.
USN_REASON_DATA_TRUNCATION 0x00000004	File atau direktori terpotok.
USN_REASON_EA_CHANGE 0x00000400	Pengguna membuat perubahan pada atribut file atau direktori yang diperluas. Atribut sistem file NTFS ini tidak dapat diakses oleh aplikasi berbasis Windows.
USN_REASON_ENCRYPTION_CHANGE 0x00040000	File atau direktori dienkripsi atau didekripsi.
USN_REASON_FILE_CREATE 0x00000100	File atau direktori dibuat untuk pertama kalinya.
USN_REASON_FILE_DELETE 0x00000200	File atau direktori dihapus.
USN_REASON_HARD_LINK_CHANGE 0x00010000	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.
USN_REASON_INDEXABLE_CHANGE 0x00004000	Pengguna mengubah atribut FILE_ATTRIBUTE_NOT_CONTENT_INDEXED . Artinya, pengguna mengubah file atau direktori dari file tempat konten dapat diindeks ke file yang kontennya tidak dapat diindeks, atau sebaliknya. Pengindeksan konten memungkinkan pencarian data yang cepat dengan membangun database konten yang dipilih.
USN_REASON_INTEGRITY_CHANGE 0x00800000	Pengguna mengubah status atribut FILE_ATTRIBUTE_INTEGRITY_STREAM untuk aliran yang diberikan. Pada sistem file ReFS, aliran integritas mempertahankan checksum semua data untuk aliran tersebut, sehingga konten file dapat divalidasi selama operasi baca atau tulis.
USN_REASON_NAMED_DATA_EXTEND 0x00000020	Satu atau beberapa aliran data bernama untuk file diperluas (ditambahkan ke).
USN_REASON_NAMED_DATA_OVERWRITE 0x00000010	Data dalam satu atau beberapa aliran data bernama untuk file ditimpa.
USN_REASON_NAMED_DATA_TRUNCATION 0x00000040	Satu atau beberapa aliran data bernama untuk file terpotok.
USN_REASON_OBJECT_ID_CHANGE 0x00080000	Pengidentifikasi objek file atau direktori diubah.
USN_REASON_RENAME_NEW_NAME 0x00002000	File atau direktori diganti namanya, dan nama file dalam struktur USN_RECORD_V4 adalah nama baru.
USN_REASON_RENAME_OLD_NAME 0x00001000	Nama file atau direktori diganti namanya, dan nama file dalam struktur USN_RECORD_V4 adalah nama sebelumnya.
USN_REASON_REPARSE_POINT_CHANGE 0x00100000	Titik reparse yang terkandung dalam file atau direktori diubah, atau titik reparse ditambahkan ke atau dihapus dari file atau direktori.
USN_REASON_SECURITY_CHANGE 0x00000800	Perubahan dilakukan dalam hak akses ke file atau direktori.
USN_REASON_STREAM_CHANGE 0x00200000	Aliran bernama ditambahkan ke atau dihapus dari file, atau aliran bernama diganti namanya.
USN_REASON_TRANSACTED_CHANGE 0x00400000	Aliran yang diberikan dimodifikasi melalui transaksi TxF yang diterapkan.

SourceInfo

Informasi tambahan tentang sumber perubahan, diatur oleh FSCTL_MARK_HANDLE operasi DeviceIoControl .

Saat utas menulis catatan USN baru, informasi sumber ditandai dalam catatan sebelumnya terus ada hanya jika utas juga mengatur bendera tersebut. Oleh karena itu, struktur informasi sumber memungkinkan aplikasi untuk memfilter catatan USN yang hanya ditetapkan oleh sumber yang diketahui, misalnya, filter antivirus.

Salah satu nilai berikut dapat diatur.

Nilai	Makna
USN_SOURCE_AUXILIARY_DATA 0x00000002	Operasi menambahkan aliran data privat ke file atau direktori. Salah satu contohnya adalah detektor virus yang menambahkan informasi checksum. Saat detektor virus memodifikasi item, sistem menghasilkan catatan USN. USN_SOURCE_AUXILIARY_DATA menunjukkan bahwa modifikasi tidak mengubah data aplikasi.
USN_SOURCE_DATA_MANAGEMENT 0x00000001	Operasi ini menyediakan informasi tentang perubahan pada file atau direktori yang dibuat oleh sistem operasi. Penggunaan umum adalah ketika sistem Penyimpanan Jarak Jauh memindahkan data dari penyimpanan eksternal ke lokal. Penyimpanan Jarak Jauh adalah perangkat lunak manajemen penyimpanan hierarkis. Langkah seperti itu biasanya minimal menambahkan bendera USN_REASON_DATA_OVERWRITE ke rekaman USN. Namun, data tidak berubah dari sudut pandang pengguna. Dengan mencatat USN_SOURCE_DATA_MANAGEMENT di anggota SourceInfo , Anda dapat menentukan bahwa meskipun operasi tulis dilakukan pada item, data tidak berubah.
USN_SOURCE_REPLICATION_MANAGEMENT 0x00000004	Operasi memodifikasi file agar sesuai dengan konten file yang sama yang ada di anggota lain dari set replika.
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT 0x00000008	Operasi ini memodifikasi file pada sistem klien agar sesuai dengan konten file yang sama yang ada di cloud.

RemainingExtents

Jumlah jangkauan yang tersisa setelah rekaman USN_RECORD_V4 saat ini. Beberapa rekaman versi 4.0 mungkin diperlukan untuk menjelaskan semua jangkauan yang dimodifikasi untuk file tertentu. Ketika anggota RemainingExtents adalah 0, rekaman USN_RECORD_V4 saat ini adalah rekaman USN_RECORD_V4 terakhir untuk file tersebut. Entri USN_RECORD_V4 terakhir untuk file tertentu selalu diikuti oleh catatan USN_RECORD_V3 dengan setidaknya set bendera USN_REASON_CLOSE .

NumberOfExtents

Jumlah jangkauan dalam entri USN_RECORD_V4 saat ini.

ExtentSize

Ukuran setiap struktur USN_RECORD_EXTENT dalam anggota Extents , dalam byte.

Extents[1]

Array struktur USN_RECORD_EXTENT yang mewakili jangkauan dalam entri USN_RECORD_V4 .

Keterangan

Rekaman USN_RECORD_V4 hanya output saat pelacakan rentang diaktifkan dan ukuran file sama atau lebih besar dari nilai anggota RangeTrackFileSizeThreshold . Pengguna selalu menerima satu atau beberapa catatan USN_RECORD_V4 diikuti oleh satu catatan USN_RECORD_V3 .

Untuk memberikan kompatibilitas penerusan jalur dalam klien jurnal perubahan, Microsoft menyediakan nomor versi utama dan minor dari perangkat lunak jurnal perubahan dalam struktur USN_RECORD_V4 . Kode Anda harus memeriksa nilai-nilai ini, memeriksa kompatibilitasnya sendiri dengan perangkat lunak jurnal perubahan, dan dengan anggun menangani ketidakcocokan jika perlu.

Perubahan nomor versi minor menunjukkan bahwa anggota struktur USN_RECORD_V4 yang ada masih valid, tetapi anggota baru mungkin telah ditambahkan antara anggota yang berpenulis dan yang terakhir, yang merupakan string panjang variabel.

Untuk menangani perubahan seperti itu dengan anggun, kode Anda tidak boleh melakukan aritmatika pointer waktu kompilasi yang bergantung pada lokasi anggota terakhir. Misalnya, perubahan nomor versi minor membuat panggilan tidak dapat diandalkan sizeof(USN_RECORD) . Sebagai gantinya, mengandalkan penghitungan run-time yang menggunakan anggota RecordLength .

Peningkatan nomor versi utama dari perangkat lunak jurnal perubahan menunjukkan bahwa struktur USN_RECORD_V4 mungkin telah mengalami perubahan besar, dan bahwa definisi saat ini mungkin tidak dapat diandalkan. Jika kode Anda mendeteksi perubahan nomor versi utama perangkat lunak jurnal perubahan, kode tidak boleh berfungsi dengan jurnal perubahan.

Untuk informasi selengkapnya, lihat Membuat, Memodifikasi, dan Menghapus Journal Perubahan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8.1 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 R2 [hanya aplikasi desktop]
Header	winioctl.h (termasuk Windows.h)