Fungsi FltGetFileNameInformation (fltkernel.h)
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 |
---|---|
|
FltGetFileNameInformation tidak bisa mendapatkan informasi nama file dalam salah satu keadaan berikut jika kueri tidak dapat dipenuhi dari cache nama Manajer Filter:
FltGetFileNameInformation tidak bisa mendapatkan nama pendek file di jalur pra-buat. STATUS_FLT_INVALID_NAME_REQUEST adalah kode kesalahan. |
|
FltGetFileNameInformation mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan. |
|
Dikembalikan saat parameter yang tidak valid diteruskan, seperti salah satu hal berikut ini:
|
|
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. |
|
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. |
|
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) |
Lihat juga
FltGetDestinationFileNameInformation
FltGetFileNameInformationUnsafe