Fungsi FltGetDestinationFileNameInformation (fltkernel.h)

Artikel
12/05/2023

Rutinitas FltGetDestinationFileNameInformation mengkueri nama file untuk direktori induk tujuan, lalu membuat nama jalur tujuan lengkap untuk file atau direktori yang sedang diganti namanya atau yang hard link NTFS sedang dibuat.

Sintaks

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

Parameter

[in] Instance

Penunjuk instans buram untuk instans driver minifilter yang dilampirkan ke volume tempat file berada.

[in] FileObject

Arahkan ke objek file untuk file. Parameter ini diperlukan dan tidak boleh NULL.

[in, optional] RootDirectory

Untuk operasi tautan: Jika tautan akan dibuat dalam direktori yang sama dengan file yang sedang ditautkan ke atau jika FileName berisi nama jalur lengkap untuk tautan yang akan dibuat, parameter ini adalah NULL. Jika tidak, ini adalah handel untuk direktori tempat tautan akan dibuat.

Untuk mengganti nama operasi: Jika file tidak dipindahkan ke direktori lain atau jika FileName berisi nama jalur lengkap, parameter ini adalah NULL. Jika tidak, ini adalah handel untuk direktori tempat file berada setelah diganti namanya.

[in] FileName

Untuk operasi tautan: Penunjuk ke string karakter lebar yang berisi nama yang akan ditetapkan ke tautan yang baru dibuat.

Untuk mengganti nama operasi: Penunjuk ke string karakter lebar yang berisi nama baru untuk file.

[in] FileNameLength

Panjang, dalam byte, dari string karakter lebar yang ditolak FileName .

[in] NameOptions

Nilai FLT_FILE_NAME_OPTIONS yang berisi bendera yang menentukan format informasi nama yang akan dikembalikan, metode kueri yang akan digunakan Manajer Filter, dan bendera nama file tambahan. Parameter ini diperlukan dan tidak boleh NULL.

Berikut ini adalah nilai bendera format nama. Hanya satu bendera format nama yang dapat ditentukan. (Perhatikan bahwa FLT_FILE_NAME_SHORT bukan nilai bendera yang valid untuk parameter ini.)

Nilai Bendera Format Nama	Makna
FLT_FILE_NAME_NORMALIZED	Parameter FileName menerima nama tujuan yang dinormalisasi untuk file.
FLT_FILE_NAME_OPENED	Parameter FileName menerima nama tujuan untuk file, berdasarkan nama yang digunakan saat file dibuka. Nama file ini tidak dinormalisasi.

Berikut ini adalah nilai bendera metode kueri. Hanya satu bendera metode kueri 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 tujuan, FltGetDestinationFileNameInformation tidak melakukan apa pun. Jika tidak, FltGetDestinationFileNameInformation meminta cache nama Manajer Filter untuk informasi nama file untuk direktori induk tujuan lalu menambahkan nama tujuan. Jika nama yang dihasilkan tidak ditemukan di cache, FltGetDestinationFileNameInformation meminta sistem file dan menyimpan hasilnya dalam cache.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetDestinationFileNameInformation meminta cache nama Manajer Filter untuk informasi nama file untuk direktori induk tujuan lalu menambahkan nama tujuan. Ini tidak mengkueri sistem file.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetDestinationFileNameInformation meminta sistem file untuk informasi nama file untuk direktori induk tujuan lalu menambahkan nama tujuan. Ini tidak mengkueri cache nama Manajer Filter dan tidak menyimpan cache hasil kueri sistem file.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetDestinationFileNameInformation meminta cache nama Manajer Filter untuk informasi nama file untuk direktori induk tujuan lalu menambahkan nama tujuan. Jika nama tidak ditemukan di cache, dan saat ini aman untuk melakukannya, FltGetDestinationFileNameInformation meminta sistem file untuk informasi nama file dan menyimpan hasilnya.

Berikut ini adalah nilai bendera nama file. Kombinasi bendera ini dapat ditentukan. (Perhatikan bahwa FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE bukan bendera yang relevan untuk parameter ini karena FltGetDestinationFileNameInformation tidak digunakan dalam panggilan balik pasca-buat.)

Nilai Bendera Nama File	Makna
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation mengarahkan permintaan nama ke instans filter panggilan untuk diselesaikan.
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation tidak menyimpan nama file yang diambil. Minifilter penyedia nama menggunakan bendera ini saat mereka melakukan kueri perantara untuk menghasilkan nama.

[out] RetFileNameInformation

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

Nilai kembali

FltGetDestinationFileNameInformation mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini:

Menampilkan kode	Deskripsi
STATUS_FLT_INVALID_NAME_REQUEST	Nilai ini dikembalikan karena salah satu alasan berikut: (1) FltGetDestinationFileNameInformation tidak bisa mendapatkan informasi nama file jika bidang TopLevelIrp dari utas saat ini bukan NULL, karena rekursi sistem file yang dihasilkan dapat menyebabkan kebuntuan atau luapan tumpukan. (2) FLT_FILE_NAME_SHORT ditentukan untuk bendera format nama dalam parameter NameOptions .
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Nilai yang tidak valid ditentukan untuk parameter NameOptions . Ini adalah kode kesalahan.
STATUS_MOUNT_POINT_NOT_RESOLVED	Nama jalur tujuan berisi titik pemasangan yang diselesaikan ke volume selain tempat file berada. (Karena operasi penggantian nama atau pembuatan tautan keras hanya dapat dilakukan dalam volume dan bukan di seluruh volume, operasi gagal.) Ini adalah kode kesalahan.

Keterangan

Minifilter biasanya memanggil FltGetDestinationFileNameInformation dalam rutinitas panggilan balik praoperasi untuk operasi penggantian nama atau pembuatan tautan keras, yang berarti bahwa nama file tujuan kemungkinan besar tidak ada. Nama "tujuan" adalah:

Untuk mengganti nama file, nama file akan memiliki jika penggantian nama berhasil. Misalnya, saat mengganti nama name1 menjadi name2, name2 adalah nama tujuan.
Untuk operasi pembuatan tautan keras, nama ditambahkan ke sistem file. Misalnya, saat menambahkan nama tautan keras2 ke file yang sudah ada bernama name1, name2 adalah nama tujuan.

FltGetDestinationFileNameInformation mengembalikan informasi nama file tujuan dalam format yang dinormalisasi atau "file yang dibuka". Untuk informasi selengkapnya tentang format ini, lihat struktur FLT_FILE_NAME_INFORMATION .

Penunjuk objek file yang diteruskan untuk parameter FileObject harus merupakan anggota FileObject dari struktur FLT_RELATED_OBJECTS untuk operasi atau penunjuk Data-Iopb-TargetFileObject>> untuk operasi, di mana Data adalah struktur data panggilan balik untuk operasi (FLT_CALLBACK_DATA). Penunjuk objek file tidak dapat menjadi anggota Data-Iopb-Parameters.SetFileInformation.FileObject>>, karena bidang ini tidak digunakan secara seragam di seluruh sistem file.

Jika pengguna membuka file dengan menggunakan ID file tetapi tidak memiliki hak istimewa melintasi untuk seluruh jalur, FltGetDestinationFileNameInformation hanya mengembalikan bagian jalur yang hak istimewanya dimiliki pengguna.

Operasi penggantian nama atau pembuatan tautan keras hanya dapat dilakukan dalam volume dan bukan di seluruh volume. Oleh karena itu, operasi seperti itu gagal jika nama jalur tujuan berisi titik pemasangan yang diselesaikan ke volume selain tempat file berada. Untuk informasi selengkapnya tentang mengganti nama operasi, lihat struktur FILE_RENAME_INFORMATION . Untuk informasi selengkapnya tentang operasi pembuatan tautan keras, lihat struktur FILE_LINK_INFORMATION .

Setelah panggilan berhasil ke FltGetDestinationFileNameInformation, pemanggil bertanggung jawab untuk merilis pointer yang dikembalikan dalam parameter RetFileNameInformation ketika tidak lagi diperlukan dengan memanggil FltReleaseFileNameInformation.

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

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 praoperasi (PFLT_PRE_OPERATION_CALLBACK) dengan memanggil rutinitas seperti FltGetDestinationFileNameInformation, itu harus memanggil FltGetTunneledName dari rutinitas panggilan balik pascaoperasinya untuk mengambil informasi nama file yang benar untuk file.

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

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

Operasi berpasangan berikut dapat menyebabkan nama file terowongan: