Bagikan melalui


struktur USN_RECORD_V3 (winioctl.h)

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

Sintaks

typedef struct {
  DWORD         RecordLength;
  WORD          MajorVersion;
  WORD          MinorVersion;
  FILE_ID_128   FileReferenceNumber;
  FILE_ID_128   ParentFileReferenceNumber;
  USN           Usn;
  LARGE_INTEGER TimeStamp;
  DWORD         Reason;
  DWORD         SourceInfo;
  DWORD         SecurityId;
  DWORD         FileAttributes;
  WORD          FileNameLength;
  WORD          FileNameOffset;
  WCHAR         FileName[1];
} USN_RECORD_V3, *PUSN_RECORD_V3;

Anggota

RecordLength

Panjang total rekaman, dalam byte.

Karena USN_RECORD_V3 adalah ukuran variabel, anggota RecordLength harus digunakan saat menghitung alamat rekaman berikutnya dalam buffer output, misalnya, buffer yang dikembalikan dari operasi untuk fungsi DeviceIoControl yang berfungsi dengan USN_RECORD_V3.

Ukuran dalam byte dari setiap catatan jurnal perubahan paling besar adalah ukuran struktur USN_RECORD_V3 , ditambah karakter MaximumComponentLength dikurangi 1 (untuk karakter yang dideklarasikan dalam struktur) kali ukuran karakter lebar. Nilai MaximumComponentLength dapat ditentukan dengan memanggil
Fungsi GetVolumeInformation . Di C, Anda dapat menentukan ukuran rekaman dengan menggunakan contoh kode berikut.

C++
  MaximumChangeJournalRecordSize = 
      QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR) 
       + sizeof(USN_RECORD_V3) );
Untuk mempertahankan kompatibilitas di seluruh perubahan versi perangkat lunak jurnal perubahan, gunakan perhitungan run-time untuk menentukan ukuran struktur USN_RECORD_V3 . Untuk informasi selengkapnya tentang kompatibilitas di seluruh perubahan versi, lihat bagian Keterangan dalam topik ini.

MajorVersion

Nomor versi utama perangkat lunak jurnal perubahan untuk rekaman ini.

Misalnya, jika perangkat lunak jurnal perubahan adalah versi 3.0, nomor versi utama adalah 3.

Nilai Makna
2
Strukturnya adalah struktur USN_RECORD_V2 dan sisa struktur harus diurai menggunakan tata letak tersebut.
3
Strukturnya adalah struktur USN_RECORD_V3 dan sisa struktur harus diurai menggunakan tata letak tersebut.
4
Strukturnya adalah [struktur USN_RECORD_V4](ns-winioctl-usn_record_v4.md) dan sisa struktur harus diurai menggunakan tata letak tersebut.

MinorVersion

Nomor versi minor dari perangkat lunak jurnal perubahan untuk rekaman ini. Misalnya, jika perangkat lunak jurnal perubahan adalah versi 3.0, nomor versi minor adalah nol.

FileReferenceNumber

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

Ini adalah nilai yang ditetapkan secara sembarangan yang mengaitkan rekaman jurnal dengan file.

ParentFileReferenceNumber

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

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

Usn

USN dari catatan ini.

TimeStamp

Stempel waktu UTC standar (FILETIME) dari rekaman ini, dalam format 64-bit.

Reason

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

Saat file atau direktori ditutup, rekaman USN akhir dihasilkan dengan set 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 terpotong.
USN_REASON_EA_CHANGE
0x00000400
Pengguna membuat perubahan pada atribut file atau direktori yang diperluas.
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 salah satu konten yang 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 terpotong.
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_V3 adalah nama baru.
USN_REASON_RENAME_OLD_NAME
0x00001000
Nama file atau direktori diganti namanya, dan nama file dalam struktur USN_RECORD_V3 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.

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 dari dua nilai berikut dapat diatur.

Nilai Makna
USN_SOURCE_AUXILIARY_DATA
0x00000002
Operasi menambahkan aliran data privat ke file atau direktori.

Contohnya mungkin 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.

SecurityId

Pengidentifikasi keamanan unik yang ditetapkan ke file atau direktori yang terkait dengan rekaman ini.

FileAttributes

Atribut untuk file atau direktori yang terkait dengan rekaman ini, seperti yang dikembalikan oleh fungsi GetFileAttributes . Atribut aliran yang terkait dengan file atau direktori dikecualikan.

FileNameLength

Panjang nama file atau direktori yang terkait dengan rekaman ini, dalam byte. Anggota FileName berisi nama ini. Gunakan anggota ini untuk menentukan panjang nama file, daripada bergantung pada '\0' berikutnya untuk memisahkan nama file di FileName.

FileNameOffset

Offset anggota FileName dari awal struktur.

FileName[1]

Nama file atau direktori yang terkait dengan rekaman ini dalam format Unicode. Nama file atau direktori ini memiliki panjang variabel.

Saat bekerja dengan FileName, jangan andalkan nama file yang berisi pembatas '\0' berikutnya, tetapi sebaliknya tentukan panjang nama file dengan menggunakan FileNameLength.

Jangan melakukan aritmatika penunjuk waktu kompilasi menggunakan FileName. Sebagai gantinya, buat perhitungan yang diperlukan pada durasi dengan menggunakan nilai anggota FileNameOffset . Melakukannya membantu membuat kode Anda kompatibel dengan versi USN_RECORD_V3 di masa mendatang.

Keterangan

Dalam buffer output yang dikembalikan dari operasi DeviceIoControl yang berfungsi dengan USN_RECORD_V3, semua rekaman diselaraskan pada batas 64-bit dari awal buffer.

Saat pelacakan rentang diaktifkan, NTFS beralih ke hanya menghasilkan rekaman USN_RECORD_V3 sebagai output.

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

Perubahan nomor versi minor menunjukkan bahwa anggota struktur USN_RECORD_V3 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, ini membuat kode sizeof(USN_RECORD) C tidak dapat diandalkan. Sebagai gantinya, mengandalkan penghitungan run-time dengan menggunakan anggota RecordLength .

Peningkatan nomor versi utama dari perangkat lunak jurnal perubahan menunjukkan bahwa struktur USN_RECORD_V3 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 tersebut 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 [khusus aplikasi desktop]
Server minimum yang didukung Windows Server 2012 [hanya aplikasi desktop]
Header winioctl.h (termasuk Windows.h)

Lihat juga

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V2

struktur USN_RECORD_V4

Struktur Manajemen Volume