Fungsi FltGetFileNameInformationUnsafe (fltkernel.h)

Artikel
08/07/2023

Rutinitas FltGetFileNameInformationUnsafe mengembalikan informasi nama untuk file atau direktori terbuka.

Sintaks

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parameter

[in] FileObject

Penunjuk ke objek file untuk file atau direktori. Objek file saat ini harus terbuka. Parameter ini diperlukan dan tidak dapat diatur ke NULL.

[in, optional] Instance

Penunjuk instans untuk pemanggil. Parameter ini dapat diatur ke 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 oleh Manajer Filter. Parameter ini diperlukan dan tidak dapat diatur ke NULL.

Tabel berikut ini menjelaskan nilai bendera format nama. Hanya salah satu bendera yang dapat ditentukan. Untuk informasi selengkapnya tentang format ini, lihat FLT_FILE_NAME_INFORMATION.

Nilai	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.

Tabel berikut ini menjelaskan nilai bendera metode kueri. Hanya salah satu bendera yang dapat ditentukan.

Nilai	Makna
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe meminta cache nama Manajer Filter untuk informasi nama file. Jika nama tidak ditemukan di cache, FltGetFileNameInformationUnsafe meminta sistem file dan menyimpan hasilnya.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe meminta cache nama Manajer Filter untuk informasi nama file. FltGetFileNameInformationUnsafe tidak meminta sistem file.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe meminta sistem file untuk informasi nama file. FltGetFileNameInformationUnsafe tidak meminta cache nama Manajer Filter, dan tidak menyimpan hasil kueri sistem file.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformationUnsafe meminta cache nama Manajer Filter untuk informasi nama file. Jika nama tidak ditemukan di cache, dan saat ini aman untuk melakukannya, FltGetFileNameInformationUnsafe meminta sistem file untuk informasi nama file dan menyimpan hasilnya.

[out] FileNameInformation

Penunjuk ke variabel yang dialokasikan pemanggil yang menerima alamat struktur FLT_FILE_NAME_INFORMATION yang dialokasikan sistem. FltGetFileNameInformationUnsafe mengalokasikan struktur ini dari kumpulan halaman. Ketika informasi ini tidak lagi diperlukan, pemanggil harus merilis struktur dengan memanggil FltReleaseFileNameInformation. Parameter ini diperlukan dan tidak dapat diatur ke NULL.

Nilai kembali

FltGetFileNameInformationUnsafe mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu dari berikut ini:

Menampilkan kode	Deskripsi
STATUS_FLT_INVALID_NAME_REQUEST	Objek file yang dirujuk parameter FileObject saat ini tidak terbuka. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Nilai yang tidak valid diteruskan untuk parameter FileNameInformation . Ini adalah kode kesalahan.

Keterangan

Rutinitas FltGetFileNameInformationUnsafe disediakan sehingga Anda dapat mengkueri nama objek file di luar konteks operasi I/O pada objek file tersebut; jika tidak, Anda harus memanggil FltGetFileNameInformation.

Tidak seperti rutinitas FltGetFileNameInformation , FltGetFileNameInformationUnsafe tidak melindungi pemanggil terhadap jenis keadaan berikut, di mana mengkueri sistem file untuk informasi nama dapat menyebabkan kebuntuan untuk metode kueri selain FLT_FILE_NAME_QUERY_CACHE_ONLY:

Di jalur I/O halaman.
Ketika bidang TopLevelIrp dari utas saat ini bukan NULL. Untuk informasi selengkapnya, lihat IoGetTopLevelIrp.
Setelah operasi IRP_MJ_CLEANUP selesai; yaitu, di jalur pasca-pembersihan, pra-tutup, atau pasca-tutup (objek file target memiliki set bendera FO_CLEANUP_COMPLETE).
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.

Untuk Windows Vista / Server 2008 dan yang lebih baru, jika minifilter belum memiliki instans filter, seperti dalam rutinitas DriverEntry-nya , itu dapat digunakan NULL untuk parameter Instans . Ini memungkinkan rutinitas DriverEntry untuk mengakses informasi nama file. Kecuali untuk kasus ini, NULL nilai untuk parameter instans dicadangkan untuk penggunaan sistem.

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

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