Funzione FltRetrieveFileInfoOnCreateCompletionEx (fltkernel.h)

Articolo
02/29/2024

FltRetrieveFileInfoOnCreateCompletionEx query per le informazioni del file specificate al completamento della creazione di file.

Sintassi

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

Parametri

[in] Filter

Puntatore filtro opaco che identifica in modo univoco il driver minifilter. Viene restituito da FltRegisterFilter e rimane costante finché viene caricato il driver minifilter.

[in] Data

Puntatore ai dati di callback FLT_CALLBACK_DATA che rappresentano l'operazione di I/O.

[in] InfoClass

Flag che indica il tipo di informazioni sui file da restituire. Si noti che non è possibile combinare i flag. I possibili valori sono i seguenti:

Contrassegno	Significato
QoCFileStatInformation (0x00000001)	Il file system restituirà le informazioni sullo stato dei file in una struttura QUERY_ON_CREATE_FILE_STAT_INFORMATION .
QoCFileLxInformation (0x00000002)	Il file system restituirà informazioni simili a Linux estese in una struttura QUERY_ON_CREATE_FILE_LX_INFORMATION .
QoCFileEaInformation (0x00000004)	Il file system restituirà attributi estesi (EA) in una struttura QUERY_ON_CREATE_EA_INFORMATION .

[out] RetInfoSize

Puntatore a un ULONG che riceve le dimensioni, in byte, del buffer a cui punta RetInfoBuffer .

[out] RetInfoBuffer

Riceve un puntatore alla struttura InfoClass richiesta. Se il file system è in grado di elaborare la richiesta, ma non è possibile trovare le informazioni sul file richiesto, questo parametro è impostato su NULL.

Valore restituito

Codice restituito	Descrizione
STATUS_SUCCESS	Il file system ha restituito correttamente le informazioni sul file richiesto.
STATUS_NOT_FOUND	Il file system ha elaborato la richiesta, ma le informazioni richieste non sono state presenti nel file o il file system non riconosce la richiesta di informazioni in InfoClass. Il chiamante non deve usare le API tradizionali del file system per richiedere le informazioni.
STATUS_NOT_SUPPORTED	Il file system non è riuscito a recuperare le informazioni richieste. Questo errore si verifica quando il file system non supporta la richiesta di informazioni o LCP associato oppure perché FltRequestFileInfoOnCreateCompletion non è stato chiamato durante la pre-creazione del file. Il chiamante deve invece usare le API tradizionali del file system per riprovare a richiedere le informazioni.
STATUS_UNSUCCESSFUL	Il file system ha ricevuto un errore durante il tentativo di recuperare le informazioni richieste. Il chiamante può provare a richiedere le informazioni in base alle normali API del file system, ma probabilmente avrà esito negativo.

Commenti

FltRequestFileInfoOnCreateCompletion e FltRetrieveFileInfoOnCreateCompletionEx consentono a un minifilter di ottenere informazioni su un file durante la creazione di file, evitando così il costo delle prestazioni di una query successiva che richiederebbe un attraversamento dello stack.

In pre-create, il minifilter effettua una chiamata a FltRequestFileInfoOnCreateCompletion con una combinazione di infoClassFlags di input che identificano le informazioni richieste.
Il file system alloca le strutture appropriate e inserisce le informazioni richieste, se supportate, mentre elabora la creazione.
In post-create, il minifilter chiama FltRetrieveFileInfoOnCreateCompletionEx per ottenere le informazioni richieste nella chiamata pre-creazione. Se il minifilter ha richiesto più di un tipo di info, deve chiamare FltRetrieveFileInfoOnCreateCompletionEx una volta per ogni tipo di info. Ad esempio:


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

// 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;

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

Una volta restituito FltRetrieveFileInfoOnCreateCompletionEx , un minifilter può scrivere nel buffer a cui punta RetInfoBuffer . Tutti i filtri sopra il minifilter visualizzeranno le modifiche se chiamano FltRetrieveFileInfoOnCreateCompletionEx nel tipo di informazioni modificato.