Función FltRetrieveFileInfoOnCreateCompletionEx (fltkernel.h)

Artículo
12/21/2024

FltRetrieveFileInfoOnCreateCompletionEx consulta la información de archivo especificada tras la finalización de la creación de archivos.

Sintaxis

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

Parámetros

[in] Filter

Puntero de filtro opaco que identifica de forma única el controlador de minifiltro. Lo devuelve FltRegisterFilter, y permanece constante siempre que se cargue el controlador de minifiltro.

[in] Data

Puntero al FLT_CALLBACK_DATA datos de devolución de llamada que representan la operación de E/S.

[in] InfoClass

Marca que indica el tipo de información de archivo que se va a devolver. Tenga en cuenta que las marcas no se pueden combinar. Puede ser uno de los siguientes valores:

Bandera	Significado
QoCFileStatInformation (0x00000001)	El sistema de archivos devolverá información de estadísticas de archivo en una estructura QUERY_ON_CREATE_FILE_STAT_INFORMATION.
QoCFileLxInformation (0x00000002)	El sistema de archivos devolverá información extendida similar a Linux en una estructura de QUERY_ON_CREATE_FILE_LX_INFORMATION.
QoCFileEaInformation (0x00000004)	El sistema de archivos devolverá atributos extendidos (EA) en una estructura QUERY_ON_CREATE_EA_INFORMATION.
QoCFileUsnInformation (0x00000008)	El sistema de archivos devolverá información de USN en una estructura de QUERY_ON_CREATE_USN_INFORMATION.
QoCFileSecurityInformation (0x00000010)	El sistema de archivos devolverá información de seguridad de archivos en una estructura de QUERY_ON_CREATE_SECURITY_INFORMATION.

[out] RetInfoSize

Puntero a un ULONG que recibe el tamaño, en bytes, del búfer al que RetInfoBuffer apunta.

[out] RetInfoBuffer

Recibe un puntero a la estructura InfoClass solicitada. Si el sistema de archivos puede procesar la solicitud pero no encuentra la información de archivo solicitada, este parámetro se establece en NULL.

Valor devuelto

Código devuelto	Descripción
STATUS_SUCCESS	El sistema de archivos devolvió correctamente la información de archivo solicitada.
STATUS_NOT_FOUND	El sistema de archivos procesó la solicitud, pero la información solicitada no estaba presente en el archivo, o el sistema de archivos no reconoce la solicitud de información en InfoClass. El autor de la llamada no debe usar las API tradicionales del sistema de archivos para solicitar la información.
STATUS_NOT_SUPPORTED	El sistema de archivos no pudo recuperar la información solicitada. Este error se produce cuando el sistema de archivos no admite la solicitud de información o ECP asociado, o porque no se llamó a FltRequestFileInfoOnCreateCompletion durante la creación previa del archivo. En su lugar, el autor de la llamada debe usar las API tradicionales del sistema de archivos para volver a intentar solicitar la información.
STATUS_UNSUCCESSFUL	El sistema de archivos recibió un error al intentar recuperar la información solicitada. El autor de la llamada puede intentar solicitar la información por medio de las API normales del sistema de archivos, pero es probable que se produzca un error.

Observaciones

FltRequestFileInfoOnCreateCompletion y FltRetrieveFileInfoOnCreateCompletionEx permitir que un minifiltro obtenga información sobre un archivo durante la creación de archivos, evitando así el costo de rendimiento de una consulta posterior que requeriría un recorrido de pila.

En la creación previa, el minifiltro realiza una llamada a FltRequestFileInfoOnCreateCompletion con una combinación de entrada InfoClassFlags que identifican la información solicitada.
El sistema de archivos asigna las estructuras adecuadas y rellena la información solicitada, si se admite, mientras procesa la creación.
En la creación posterior, el minifiltro llama a FltRetrieveFileInfoOnCreateCompletionEx para obtener la información que solicitó en la llamada previa a la creación. Si el minifiltro solicitó más de un tipo de información, debe llamar a FltRetrieveFileInfoOnCreateCompletionEx una vez para cada tipo de información. Por ejemplo:


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

Una vez fltRetrieveFileInfoOnCreateCompletionEx, un minifiltro puede escribir en el búfer al que apunta RetInfoBuffer. Los filtros anteriores a ese minifiltro verán los cambios si llaman a FltRetrieveFileInfoOnCreateCompletionEx en el tipo de información modificado.