Fungsi FltGetFileNameInformation (fltkernel.h)

Artikel
08/07/2023

Rutinitas FltGetFileNameInformation mengembalikan informasi nama untuk file atau direktori.

Sintaks

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parameter

[in] CallbackData

Penunjuk ke struktur FLT_CALLBACK_DATA , yang merupakan struktur data panggilan balik untuk operasi I/O. Parameter ini diperlukan dan tidak boleh NULL.

[in] NameOptions

Nilai FLT_FILE_NAME_OPTIONS yang berisi bendera yang menentukan format informasi nama yang akan dikembalikan, serta metode kueri yang akan digunakan Manajer Filter. Pemanggil harus menyertakan bendera format nama dan bendera metode kueri. Bendera tambahan dapat digunakan oleh driver minifilter penyedia nama untuk menentukan opsi kueri nama. Parameter ini diperlukan dan tidak boleh NULL.

Berikut ini adalah nilai bendera format nama file. Hanya salah satu bendera berikut yang dapat ditentukan. Untuk penjelasan tentang format ini, lihat FLT_FILE_NAME_INFORMATION.

Nilai Bendera Format Nama	Makna
FLT_FILE_NAME_NORMALIZED	Parameter FileNameInformation menerima alamat struktur yang berisi nama yang dinormalisasi untuk file.
FLT_FILE_NAME_OPENED	Parameter FileNameInformation menerima alamat struktur yang berisi nama yang digunakan saat file dibuka.
FLT_FILE_NAME_SHORT	Parameter FileNameInformation menerima alamat struktur yang berisi nama pendek (8.3) untuk file. Nama pendek terdiri dari hingga 8 karakter, diikuti segera dengan titik dan hingga 3 karakter lagi. Nama pendek untuk file tidak menyertakan nama volume, jalur direktori, atau nama aliran. Tidak valid di jalur pra-buat.

Berikut ini adalah nilai bendera metode kueri nama file. Hanya salah satu bendera berikut yang dapat ditentukan.

Nilai Bendera Metode Kueri	Makna
FLT_FILE_NAME_QUERY_DEFAULT	Jika saat ini tidak aman untuk mengkueri sistem file untuk nama file, FltGetFileNameInformation tidak melakukan apa pun. Jika tidak, FltGetFileNameInformation meminta cache nama Manajer Filter untuk informasi nama file. Jika nama tidak ditemukan di cache, FltGetFileNameInformation meminta sistem file dan menyimpan hasilnya dalam cache.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation meminta cache nama Manajer Filter untuk informasi nama file. FltGetFileNameInformation tidak mengkueri sistem file.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation meminta sistem file untuk informasi nama file. FltGetFileNameInformation tidak mengkueri cache nama Manajer Filter, dan tidak menyimpan hasil kueri sistem file.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformation meminta cache nama Manajer Filter untuk informasi nama file. Jika nama tidak ditemukan di cache, dan saat ini aman untuk melakukannya, FltGetFileNameInformation meminta sistem file untuk informasi nama file dan menyimpan hasilnya.

Minifilter penyedia nama menggunakan bendera berikut untuk menentukan properti operasi nama file.

Nilai Bendera Penyedia Nama	Makna
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	Minifilter penyedia nama dapat menggunakan bendera ini untuk menentukan bahwa permintaan kueri nama harus dialihkan ke dirinya sendiri (minifilter penyedia nama) daripada dipenuhi oleh penyedia nama yang lebih rendah di tumpukan.
FLT_FILE_NAME_DO_NOT_CACHE	Bendera ini menunjukkan bahwa nama yang diambil dari kueri ini tidak boleh di-cache. Minifilter penyedia nama menggunakan bendera ini saat mereka melakukan kueri perantara untuk menghasilkan nama.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	Minifilter penyedia nama dapat menggunakan bendera ini untuk menentukan bahwa aman untuk mengkueri nama di jalur pasca-buat meskipun STATUS_REPARSE dikembalikan. Merupakan tanggung jawab pemanggil untuk memastikan bahwa bidang FileObject-FileName> tidak diubah. Jangan gunakan bendera ini dengan titik pemasangan atau titik pemilah ulang tautan simbolis.

[out] FileNameInformation

Penunjuk ke variabel yang dialokasikan penelepon yang menerima alamat struktur FLT_FILE_NAME_INFORMATION yang dialokasikan sistem yang berisi informasi nama file. FltGetFileNameInformation mengalokasikan struktur ini dari kumpulan halaman. Parameter ini diperlukan dan tidak boleh NULL.

Nilai kembali

Jika informasi nama berhasil dikembalikan, FltGetFileNameInformation mengembalikan STATUS_SUCCESS. Jika tidak, ia mengembalikan nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini:

Menampilkan kode	Deskripsi
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation tidak bisa mendapatkan informasi nama file dalam salah satu keadaan berikut jika kueri tidak dapat dipenuhi dari cache nama Manajer Filter: Di jalur I/O halaman. Ketika bidang TopLevelIrp dari utas saat ini bukan NULL, karena rekursi sistem file yang dihasilkan dapat menyebabkan kebuntuan atau luapan tumpukan. (Untuk informasi selengkapnya tentang masalah ini, lihat IoGetTopLevelIrp.) Setelah operasi IRP_MJ_CLEANUP selesai; yaitu, dalam jalur pasca-pembersihan, pra-tutup, atau pasca-tutup (objek file target memiliki bendera FO_CLEANUP_COMPLETE diatur). Dalam rutinitas panggilan balik praoperasi (PFLT_PRE_OPERATION_CALLBACK) atau pascaoperasi (PFLT_POST_OPERATION_CALLBACK) untuk salah satu operasi berikut: IRP_MJ_ACQUIRE_FOR_CC_FLUSH IRP_MJ_ACQUIRE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_CC_FLUSH IRP_MJ_RELEASE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION Dalam rutinitas panggilan balik pascaoperasi untuk IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION. Ketika semua APC dinonaktifkan; yaitu, ketika KeAreAllApcsDisabled mengembalikan TRUE. FltGetFileNameInformation tidak bisa mendapatkan nama pendek file di jalur pra-buat. STATUS_FLT_INVALID_NAME_REQUEST adalah kode kesalahan.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Dikembalikan saat parameter yang tidak valid diteruskan, seperti salah satu hal berikut ini: Parameter FileNameInformation tidak boleh NULL. Parameter CallbackData tidak boleh NULL. STATUS_INVALID_PARAMETER adalah kode kesalahan.
STATUS_FLT_NAME_CACHE_MISS	Informasi nama file tidak ditemukan dalam cache nama dan NameOptions menyertakan FLT_FILE_NAME_QUERY_CACHE_ONLY. -atau- Informasi nama file tidak ditemukan dalam singgahan nama ketika NameOptions menyertakan FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP dan informasi nama file tidak dapat dikueri dari sistem file. Panggilan tambahan ke FltGetFileNameInformation dengan FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY yang diatur di NameOptions dapat mengembalikan informasi nama file.
STATUS_NOT_SAME_DEVICE	File yang sedang dikueri selama pra-buat berada pada volume yang berbeda dari direktori induknya. Kesalahan ini dikembalikan untuk kueri nama yang dinormalisasi, di mana file adalah persimpangan atau symlink yang diselesaikan ke volume yang berbeda.
STATUS_ACCESS_DENIED	Jika pengguna membuka file dengan ID file tetapi tidak memiliki hak istimewa melintasi untuk seluruh jalur, FltGetFileNameInformation gagal dengan nilai pengembalian ini. STATUS_ACCESS_DENIED adalah kode kesalahan. -atau- File adalah file sistem dengan semua akses ditolak.

Keterangan

FltGetFileNameInformation mengembalikan informasi nama yang diminta untuk file atau direktori yang merupakan target operasi yang dijelaskan oleh CallbackData, dalam format yang ditentukan. File atau direktori belum perlu dibuka oleh sistem file.

Untuk operasi pra-buat, jika anggota CallbackData-Iopb-OperationFlags>> berisi bendera bitwise SL_OPEN_TARGET_DIRECTORY, FltGetFileNameInformation mengembalikan nama direktori yang berisi (induk) untuk file yang diberikan. Nama ini adalah jalur aktual yang dibuka operasi buat.

Untuk mengurai konten struktur FLT_FILE_NAME_INFORMATION yang dikembalikan oleh FltGetFileNameInformation, panggil FltParseFileNameInformation. (Untuk informasi selengkapnya tentang format nama file, lihat FLT_FILE_NAME_INFORMATION.)

Setelah panggilan berhasil ke FltGetFileNameInformation, pemanggil bertanggung jawab untuk merilis penunjuk yang dikembalikan dalam parameter FileNameInformation ketika penunjuk tidak lagi diperlukan. Pemanggil melakukan ini dengan memanggil FltReleaseFileNameInformation.

Pemanggil tidak boleh mengubah konten struktur yang dikembalikan dalam parameter FileNameInformation karena struktur ini di-cache oleh Manajer Filter sehingga semua driver minifilter dapat menggunakannya.

Jika FltGetFileNameInformation dipanggil dalam rutinitas panggilan balik praoperasi untuk operasi buat untuk mengambil nama yang dibuka, FltGetFileNameInformation berhasil meskipun jalur ke file yang dibuka tidak ada pada volume.

Jika FltGetFileNameInformation dipanggil dalam rutinitas panggilan balik praoperasi untuk operasi buat untuk mengambil nama yang dinormalisasi, FltGetFileNameInformation berhasil bahkan jika komponen akhir dari jalur ke file yang dibuka tidak ada pada volume.

Catatan

Dukungan Blok Pesan Server (SMB) untuk mengkueri nama file yang dinormalisasi pada volume jarak jauh bervariasi pada versi Windows 10 yang berbeda. Lihat Protokol MS-SMB2 untuk detailnya.

Dalam operasi buat, tautan keras, dan ganti nama, penerowongan nama file dapat menyebabkan komponen akhir dalam informasi nama file yang dinormalisasi yang diambil driver minifilter dalam rutinitas panggilan balik praoperasi tidak valid. Jika driver minifilter mengambil informasi nama file yang dinormalisasi dalam rutinitas panggilan balik (PFLT_PRE_OPERATION_CALLBACK) praoperasi dengan memanggil rutinitas seperti FltGetFileNameInformation, itu harus memanggil FltGetTunneledName dari rutinitas panggilan balik pascaoperasi (PFLT_POST_OPERATION_CALLBACK) untuk mengambil informasi nama file yang benar untuk file.

Untuk Windows 8.1 dan yang lebih lama, FltGetFileNameInformation hanya dapat menyertakan jenis aliransaat dipanggil dari panggilan balik pra-buat filter. Untuk membedakan antara aliran default file dan aliran metadata, panggilan ini harus dilakukan dalam operasi pra-pembuatan. Jenis aliran yang dihasilkan akan tetap valid sepanjang masa pakai file.

Sebelum Windows 8, Manajer Filter memperoleh nama yang dinormalisasi untuk file atau direktori dengan mengumpulkan informasi nama untuk setiap komponen jalur file. Ini memerlukan beberapa kueri ke sistem file untuk mengkompilasi jalur lengkap. Dimulai dengan Windows 8, sistem file lokal mendukung kelas informasi file FileNormalizedNameInformation dan hanya satu kueri yang diperlukan untuk mendapatkan nama yang dinormalisasi. Sistem file jarak jauh mungkin tidak mendukung kelas informasi file FileNormalizedNameInformation . Jika demikian, kueri untuk setiap komponen jalur file masih diperlukan untuk merakit nama yang dinormalisasi. Dalam kondisi jaringan tertentu, kueri nama lengkap dapat memerlukan banyak waktu untuk diselesaikan.

Untuk informasi selengkapnya tentang informasi nama file yang dinormalisasi, lihat FLT_FILE_NAME_INFORMATION.

Catatan

Penerowongan nama file hanya memengaruhi operasi buat, tautan keras, dan ganti nama dengan cara ini. Ini tidak memengaruhi operasi I/O lainnya, seperti baca dan tulis.

Operasi berpasangan berikut dapat menyebabkan nama file terowongan:

delete (name)/create(name)
delete (name)/rename(source, name)
ganti nama (nama, nama baru)/create(name)
ganti nama (nama, nama baru)/ganti nama(sumber,nama)

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	fltkernel.h (termasuk Fltkernel.h)
Pustaka	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (Lihat Nilai Yang Dikembalikan)