Função FltRetrieveFileInfoOnCreateCompletionEx (fltkernel.h)

Artigo
05/23/2024

Consultas FltRetrieveFileInfoOnCreateCompletionEx para as informações de arquivo especificadas após a conclusão da criação do arquivo.

Sintaxe

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

Ponteiro de filtro opaco que identifica exclusivamente o driver de minifiltro. Ele é retornado por FltRegisterFilter e permanece constante enquanto o driver de minifiltro é carregado.

[in] Data

Ponteiro para os dados de retorno de chamada FLT_CALLBACK_DATA que representam a operação de E/S.

[in] InfoClass

Sinalizador que indica o tipo de informações de arquivo a serem retornadas. Observe que os sinalizadores não podem ser combinados. Pode ser um dos seguintes valores:

Sinalizador	Significado
QoCFileStatInformation (0x00000001)	O sistema de arquivos retornará informações de estatística de arquivo em uma estrutura QUERY_ON_CREATE_FILE_STAT_INFORMATION .
QoCFileLxInformation (0x00000002)	O sistema de arquivos retornará informações estendidas semelhantes ao Linux em uma estrutura QUERY_ON_CREATE_FILE_LX_INFORMATION .
QoCFileEaInformation (0x00000004)	O sistema de arquivos retornará atributos estendidos (EA) em uma estrutura QUERY_ON_CREATE_EA_INFORMATION .
QoCFileUsnInformation (0x00000008)	O sistema de arquivos retornará informações de USN em uma estrutura de QUERY_ON_CREATE_USN_INFORMATION .
QoCFileSecurityInformation (0x00000010)	O sistema de arquivos retornará informações de segurança de arquivo em uma estrutura QUERY_ON_CREATE_SECURITY_INFORMATION .

[out] RetInfoSize

Ponteiro para um ULONG que recebe o tamanho, em bytes, do buffer para o qual RetInfoBuffer aponta.

[out] RetInfoBuffer

Recebe um ponteiro para a estrutura InfoClass solicitada. Se o sistema de arquivos puder processar a solicitação, mas não encontrar as informações de arquivo solicitadas, esse parâmetro será definido como NULL.

Retornar valor

Código de retorno	Descrição
STATUS_SUCCESS	O sistema de arquivos retornou com êxito as informações de arquivo solicitadas.
STATUS_NOT_FOUND	O sistema de arquivos processou a solicitação, mas as informações solicitadas não estavam presentes no arquivo ou o sistema de arquivos não reconhece a solicitação de informações no InfoClass. O chamador não deve usar APIs tradicionais do sistema de arquivos para solicitar as informações.
STATUS_NOT_SUPPORTED	O sistema de arquivos não pôde recuperar as informações solicitadas. Esse erro ocorre quando o sistema de arquivos não dá suporte à solicitação de informações ou ao ECP associado ou porque FltRequestFileInfoOnCreateCompletion não foi chamado durante a pré-criação do arquivo. Em vez disso, o chamador deve usar APIs tradicionais do sistema de arquivos para tentar novamente solicitar as informações.
STATUS_UNSUCCESSFUL	O sistema de arquivos recebeu um erro ao tentar recuperar as informações solicitadas. O chamador pode tentar solicitar as informações por meio de APIs normais do sistema de arquivos, mas isso provavelmente falhará.

Comentários

FltRequestFileInfoOnCreateCompletion e FltRetrieveFileInfoOnCreateCompletionEx permitem que um minifiltro obtenha informações sobre um arquivo durante a criação de arquivo, evitando assim o custo de desempenho de uma consulta posterior que exigiria uma passagem de pilha.

Na pré-criação, o minifiltro faz uma chamada para FltRequestFileInfoOnCreateCompletion com uma combinação de InfoClassFlags de entrada que identificam as informações solicitadas.
O sistema de arquivos aloca as estruturas apropriadas e preenche as informações solicitadas, se houver suporte, enquanto processa a criação.
Na pós-criação, o minifiltro chama FltRetrieveFileInfoOnCreateCompletionEx para obter as informações solicitadas na chamada de pré-criação. Se o minifiltro solicitou mais de um tipo de informação, ele deve chamar FltRetrieveFileInfoOnCreateCompletionEx uma vez para cada tipo de informação. Por exemplo:


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

Depois que FltRetrieveFileInfoOnCreateCompletionEx retornar, um minifiltro poderá gravar no buffer para o qual RetInfoBuffer aponta. Todos os filtros acima desse minifiltro verão as alterações se chamarem FltRetrieveFileInfoOnCreateCompletionEx no tipo de informação modificado.