Fungsi FltRetrieveFileInfoOnCreateCompletionEx (fltkernel.h)

Artikel
05/23/2024

Kueri FltRetrieveFileInfoOnCreateCompletionEx untuk informasi file yang ditentukan setelah penyelesaian pembuatan file.

Sintaks

NTSTATUS FLTAPI FltRetrieveFileInfoOnCreateCompletionEx(
  [in]  PFLT_FILTER        Filter,
  [in]  PFLT_CALLBACK_DATA Data,
  [in]  ULONG              InfoClass,
  [out] PULONG             RetInfoSize,
  [out] PVOID              *RetInfoBuffer
);

Parameter

[in] Filter

Penunjuk filter buram yang secara unik mengidentifikasi driver minifilter. Ini dikembalikan oleh FltRegisterFilter, dan tetap konstan selama driver minifilter dimuat.

[in] Data

Arahkan ke data panggilan balik FLT_CALLBACK_DATA yang mewakili operasi I/O.

[in] InfoClass

Bendera yang menunjukkan jenis informasi file yang akan dikembalikan. Perhatikan bahwa bendera tidak dapat digabungkan. Dapat berupa salah satu dari nilai berikut:

Bendera	Makna
QoCFileStatInformation (0x00000001)	Sistem file akan mengembalikan informasi statistik file dalam struktur QUERY_ON_CREATE_FILE_STAT_INFORMATION .
QoCFileLxInformation (0x00000002)	Sistem file akan mengembalikan informasi seperti Linux yang diperluas dalam struktur QUERY_ON_CREATE_FILE_LX_INFORMATION .
QoCFileEaInformation (0x00000004)	Sistem file akan mengembalikan atribut yang diperluas (EA) dalam struktur QUERY_ON_CREATE_EA_INFORMATION .
QoCFileUsnInformation (0x00000008)	Sistem file akan mengembalikan informasi USN dalam struktur QUERY_ON_CREATE_USN_INFORMATION .
QoCFileSecurityInformation (0x00000010)	Sistem file akan mengembalikan informasi keamanan file dalam struktur QUERY_ON_CREATE_SECURITY_INFORMATION .

[out] RetInfoSize

Penunjuk ke ULONG yang menerima ukuran, dalam byte, dari buffer yang dituju retInfoBuffer .

[out] RetInfoBuffer

Menerima pointer ke struktur InfoClass yang diminta. Jika sistem file dapat memproses permintaan tetapi tidak dapat menemukan informasi file yang diminta, parameter ini diatur ke NULL.

Menampilkan nilai

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Sistem file berhasil mengembalikan informasi file yang diminta.
STATUS_NOT_FOUND	Sistem file memproses permintaan, tetapi informasi yang diminta tidak ada pada file, atau sistem file tidak mengenali permintaan informasi di InfoClass. Pemanggil tidak boleh menggunakan API sistem file tradisional untuk meminta informasi.
STATUS_NOT_SUPPORTED	Sistem file tidak dapat mengambil informasi yang diminta. Kesalahan ini terjadi ketika sistem file tidak mendukung permintaan informasi atau ECP terkait, atau karena FltRequestFileInfoOnCreateCompletion tidak dipanggil selama pra-pembuatan file. Pemanggil harus menggunakan API sistem file tradisional untuk mencoba kembali meminta informasi.
STATUS_UNSUCCESSFUL	Sistem file menerima kesalahan ketika mencoba mengambil informasi yang diminta. Pemanggil dapat mencoba meminta informasi melalui API sistem file normal, tetapi kemungkinan akan gagal.

Keterangan

FltRequestFileInfoOnCreateCompletion dan FltRetrieveFileInfoOnCreateCompletionEx memungkinkan minifilter untuk mendapatkan informasi tentang file selama pembuatan file, sehingga menghindari biaya performa kueri nanti yang akan memerlukan traversal tumpukan.

Dalam pra-buat, minifilter melakukan satu panggilan ke FltRequestFileInfoOnCreateCompletion dengan kombinasi input InfoClassFlags yang mengidentifikasi informasi yang diminta.
Sistem file mengalokasikan struktur yang sesuai dan mengisi informasi yang diminta, jika didukung, saat memproses pembuatan.
Dalam pasca-buat, minifilter memanggil FltRetrieveFileInfoOnCreateCompletionEx untuk mendapatkan informasi yang dimintanya dalam panggilan pra-buat. Jika minifilter meminta lebih dari satu jenis info, minifilter harus memanggil FltRetrieveFileInfoOnCreateCompletionEx sekali untuk setiap jenis info. Contohnya:


// Pre-create:
NTSTATUS status;
status = FltRequestFileInfoOnCreateCompletion( Filter,
                                               CallbackData,
                                               QoCFileStatInformation
                                                | QoCFileLxInformation
                                                | QoCFileEaInformation 
                                                | QoCFileUsnInformation );

// Post-create:
NTSTATUS status;
ULONG fileStatSize, fileLxSize, fileEaSize;
QUERY_ON_CREATE_FILE_STAT_INFORMATION* fileStatInfo;
QUERY_ON_CREATE_FILE_LX_INFORMATION* fileLxInfo;
QUERY_ON_CREATE_EA_INFORMATION* fileEaInfo;
QUERY_ON_CREATE_USN_INFORMATION* fileUsnInfo;
QUERY_ON_CREATE_SECURITY_INFORMATION* fileSecurityInfo;

status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileStatInformation,
                                                  &fileStatSize,
                                                  &fileStatInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileLxInformation,
                                                  &fileLxSize,
                                                  &fileLxInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileEaInformation, 
                                                  &fileEaSize, 
                                                  &fileEaInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileUsnInformation, 
                                                  &fileUsnInfo, 
                                                  &fileUsnInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileSecurityInformation,
                                                  &fileSecurityInfo,
                                                  &fileSecurityInfo);

Setelah FltRetrieveFileInfoOnCreateCompletionEx kembali, minifilter dapat menulis ke dalam buffer yang ditunjuk retInfoBuffer . Setiap filter di atas minifilter tersebut akan melihat perubahan jika mereka memanggil FltRetrieveFileInfoOnCreateCompletionEx pada jenis informasi yang dimodifikasi.